sdf-2.001/004075500042570001753000000000000672243774200121365ustar00iancmtr00000400000236sdf-2.001/t/004075500042570001753000000000000672243775100124015ustar00iancmtr00000400000236sdf-2.001/t/general/004075500042570001753000000000000672243775100140165ustar00iancmtr00000400000236sdf-2.001/t/general/lineno.sdf010064400042570001753000000011410672214703100157570ustar00iancmtr00000400000236# This file tests line numbering in messages Hello world UNKNOWNP[unknownp]Some text with an {{N[unknown]unknown attribute}} and [[unknown_var]] on the second and {{UNKNOWN:unknown object}} on the third line. !macro badstuff H9: Heading with a bad level Some text with an {{WXYZ:unknown tag}}. !endmacro !badstuff BADP[badp]Some more text with a {{N[bad]bad attribute}} on the second and {{BAD:bad object}} on the third line. # Try bad stuff inside a block !block appendix H0: Heading with a bad level Some text with an {{WXYZ:unknown tag}}. H9: Another heading with a bad level !endblock !badstuff sdf-2.001/t/general/checked/004075500042570001753000000000000672243774100154035ustar00iancmtr00000400000236sdf-2.001/t/general/checked/macro.log010064400042570001753000000000000622022557200171600ustar00iancmtr00000400000236sdf-2.001/t/general/checked/formats.log010064400042570001753000000000000622022557200175320ustar00iancmtr00000400000236sdf-2.001/t/general/checked/para1.log010064400042570001753000000000000622022557200170630ustar00iancmtr00000400000236sdf-2.001/t/general/checked/phrase.out010064400042570001753000000003500637716120400174030ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']Some text with an {{1[]implicit}} style. N[orig_style='N']Some text with an {{B[]explicit}} style or {{U[]two}}. N[orig_style='N']Some text with an {{EX[] example}} style or {{EX[] two}}. sdf-2.001/t/general/checked/para2.log010064400042570001753000000000000622022557200170640ustar00iancmtr00000400000236sdf-2.001/t/general/checked/lineno.log010064400042570001753000000017000672214705300173570ustar00iancmtr00000400000236lineno.sdf warning, para. on 6: unknown paragraph style 'UNKNOWNP' lineno.sdf warning, para. on 6: unknown paragraph attribute 'unknownp' lineno.sdf warning, para. on 6: variable 'unknown_var' not defined lineno.sdf warning, para. on 6: unknown phrase attribute 'unknown' lineno.sdf warning, para. on 6: unknown phrase style 'UNKNOWN' lineno.sdf warning, macro on 18: unknown paragraph style 'H9' lineno.sdf warning, macro on 18: unknown phrase style 'WXYZ' lineno.sdf warning, para. on 20: unknown paragraph style 'BADP' lineno.sdf warning, para. on 20: unknown paragraph attribute 'badp' lineno.sdf warning, para. on 20: unknown phrase attribute 'bad' lineno.sdf warning, para. on 20: unknown phrase style 'BAD' lineno.sdf warning, block on 26: unknown phrase style 'WXYZ' lineno.sdf warning, block on 26: unknown paragraph style 'A9' lineno.sdf warning, macro on 35: unknown paragraph style 'H9' lineno.sdf warning, macro on 35: unknown phrase style 'WXYZ' sdf-2.001/t/general/checked/zero.log010064400042570001753000000000000622022557200170360ustar00iancmtr00000400000236sdf-2.001/t/general/checked/expr.log010064400042570001753000000000000622022557200170350ustar00iancmtr00000400000236sdf-2.001/t/general/checked/macro.out010064400042570001753000000001710637716117200172270ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']abc is A B C. N[orig_style='N']def is D E F. N[orig_style='N']xyz is X Y Y Y . sdf-2.001/t/general/checked/formats.out010064400042570001753000000003030672214564600176000ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']Hello World in uppercase is HELLO WORLD. N[orig_style='N']Hello World in lowercase is hello world. N[orig_style='N']This file was last modified in 1999. sdf-2.001/t/general/checked/para1.out010064400042570001753000000003160637716117600171370ustar00iancmtr00000400000236__tuning[] __endtuning[] H1[orig_style='H1']First Level heading N[orig_style='N']A simple paragraph. H2[orig_style='H2']Second level heading N[orig_style='N']Another simple paragraph with more than 1 line. sdf-2.001/t/general/checked/para2.out010064400042570001753000000001110637716120200171170ustar00iancmtr00000400000236__tuning[] __endtuning[] __variable[]xx 64 N[orig_style='N']Hello world. sdf-2.001/t/general/checked/lineno.out010064400042570001753000000012330672214705300174060ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']Hello world UNKNOWNP[orig_style='UNKNOWNP';unknownp=1]Some text with an {{N[unknown=1]unknown attribute}} and on the second and {{UNKNOWN[]unknown object}} on the third line. H9[orig_style='H9']Heading with a bad level N[orig_style='N']Some text with an {{WXYZ[]unknown tag}}. BADP[badp=1;orig_style='BADP']Some more text with a {{N[bad=1]bad attribute}} on the second and {{BAD[]bad object}} on the third line. N[orig_style='N']Some text with an {{WXYZ[]unknown tag}}. A9[orig_style='H9']Another heading with a bad level H9[orig_style='H9']Heading with a bad level N[orig_style='N']Some text with an {{WXYZ[]unknown tag}}. sdf-2.001/t/general/checked/zero.out010064400042570001753000000006720637716121000171040ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']0 N[orig_style='N']1 N[orig_style='N']2 __table[format='0%-100%,1*';style='columns']2 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]F1}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]F2}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']0 __cell[cols=1;rows=1] N[orig_style='N']a __row[]Body __cell[cols=1;rows=1] N[orig_style='N']1 __cell[cols=1;rows=1] N[orig_style='N']0 __endtable[] sdf-2.001/t/general/checked/expr.out010064400042570001753000000001020637716116000170730ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']xyz is 1 and !xyz is 0. sdf-2.001/t/general/checked/phrase.log010064400042570001753000000000000622022557200173410ustar00iancmtr00000400000236sdf-2.001/t/general/zero.t010064400042570001753000000000300647265372200151500ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/general/formats.sdf010064400042570001753000000005270647017662200161650ustar00iancmtr00000400000236# This file tests variable/expression formatting #!define FORMAT_UPPER 'tr/a-z/A-Z/, $_' #!define FORMAT_LOWER 'tr/A-Z/a-z/, $_' #!define FORMAT_YEAR '&FormatTime(\'$year\', $_)' !define abc 'Hello World' [[abc]] in uppercase is [[UPPER:abc]]. [[abc]] in lowercase is [[LOWER:abc]]. This file was last modified in [[YEAR:DOC_MODIFIED]]. sdf-2.001/t/general/expr.t010064400042570001753000000000300647265372200151470ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/general/lineno.t010064400042570001753000000000300647265372200154550ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/general/macro.sdf010064400042570001753000000002470622022557200156020ustar00iancmtr00000400000236# This file tests macro continuation !define abc "A B C" !define def \ "D E F" !define xyz \ "X " .\ "Y " x\ 3 abc is [[abc]]. def is [[def]]. xyz is [[xyz]]. sdf-2.001/t/general/zero.sdf010064400042570001753000000001270622022557200154550ustar00iancmtr00000400000236# This file tests "zero" paragraphs 0 1 2 !block table F1 F2 0 a 1 0 !endblock sdf-2.001/t/general/expr.sdf010064400042570001753000000001200622022557200154450ustar00iancmtr00000400000236# This file test expressions !define xyz xyz is [[xyz]] and !xyz is [[!xyz]]. sdf-2.001/t/general/para1.sdf010064400042570001753000000002350622022557200155020ustar00iancmtr00000400000236# This file tests paragraph tagging H1: First Level heading A simple paragraph. H2: Second level heading Another simple paragraph with more than 1 line. sdf-2.001/t/general/phrase.sdf010064400042570001753000000002720635340446200157650ustar00iancmtr00000400000236# This file tests object tagging Some text with an {{implicit}} style. Some text with an {{B: explicit}} style or {{U:two}}. Some text with an {{EX: example}} style or {{EX: two}}. sdf-2.001/t/general/para2.sdf010064400042570001753000000001320622022557200154770ustar00iancmtr00000400000236# This file tests a paragraph immediately after a pragma __variable[]xx 64 Hello world. sdf-2.001/t/general/para1.t010064400042570001753000000000300647265372200151750ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/general/para2.t010064400042570001753000000000300647265372200151760ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/general/macro.t010064400042570001753000000000300647265372200152720ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/general/formats.t010064400042570001753000000000300647265372200156440ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/general/phrase.t010064400042570001753000000000300647265372200154530ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/004075500042570001753000000000000672243775200135035ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/004075500042570001753000000000000672243775200150715ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/on_para.log010064400042570001753000000000660622022557200171760ustar00iancmtr00000400000236on_para.sdf warning, text prepended to 28: prepending sdf-2.001/t/macro/checked/class.log010064400042570001753000000010610632307675400166720ustar00iancmtr00000400000236class.sdf warning, filter on 14: unknown object 'D' in class 'widgets' class.sdf warning, para. on 31: unknown object 'F' in class 'widgets' (name EP) class.sdf warning, para. on 31: unknown object 'Omega' in class 'widgets' (long EP) class.sdf warning, para. on 35: unknown object 'F' in class 'widgets' (name EP) class.sdf warning, para. on 35: unable to expand object 'F' in class 'widgets' class.sdf warning, para. on 35: unknown object 'Omega' in class 'widgets' (long EP) class.sdf warning, para. on 35: unable to shrink object 'Omega' in class 'widgets' sdf-2.001/t/macro/checked/default.out010064400042570001753000000004760637716125200172450ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']Variable num1 is 1. Variable num2 is 42. N[orig_style='N']Variable str1 is My favorite station. Variable str2 is Hello world. N[orig_style='N']Variable num3 is 28. Variable str3 is AA-My favorite station-ZZ. N[orig_style='N']Variable num2 is 42. Variable str2 is Hello world. sdf-2.001/t/macro/checked/inherit.log010064400042570001753000000003060661527233400172240ustar00iancmtr00000400000236inherit.sdf warning, macro on 22: unable to find library 'abc' inherit.sdf warning, macro on 26: unable to find library 'xyz/qwe' inherit.sdf warning, macro on 30: unable to find '/qwe/xyz/xyz.sdm' sdf-2.001/t/macro/checked/export.log010064400042570001753000000000000622022557200170640ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/undef.out010064400042570001753000000002240637716140000167040ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']Variable num1 is 42. Variable str1 is Hello world. N[orig_style='N']Variable num1 is . Variable str1 is . sdf-2.001/t/macro/checked/elsif.out010064400042570001753000000000000622022557200166730ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/init.out010064400042570001753000000001750637716133600165630ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']The new document style is memo. N[orig_style='N']The final document style is memo. sdf-2.001/t/macro/checked/else.log010064400042570001753000000001370622022557200165060ustar00iancmtr00000400000236else.sdf error, macro on 6: !else not expected else.sdf error, macro on 14: !else not expected sdf-2.001/t/macro/checked/endtable.log010064400042570001753000000001740622022557200173350ustar00iancmtr00000400000236endtable.sdf error, macro on 4: !endtable not expected endtable.sdf error, EOF at 9: !endtable missing for !table on line 7 sdf-2.001/t/macro/checked/cell.log010064400042570001753000000001370622022557200164750ustar00iancmtr00000400000236cell.sdf error, macro on 4: !cell not expected cell.sdf error, macro on 10: !cell not expected sdf-2.001/t/macro/checked/on_phras.out010064400042570001753000000007330637716136000174260ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']Some text including a {{MYTYPE[]mytype Object}} and another {{B[]bold Object}}. N[orig_style='N']Some more text including a {{U[jump='#mytype object']mytype Object}} and another {{B[]bold Object}}. N[orig_style='N']Yet another {{U[jump='#object']Object}}. H2[orig_style='H2']{{U[jump='#A Heading which is a MYTYPE']A Heading which is a MYTYPE}} N[orig_style='N']Hello {{1[]world}}1. I hope you are {{B[]really {{U[]well}}2}}3 today. sdf-2.001/t/macro/checked/endmacro.out010064400042570001753000000000000622022557200173610ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/table.log010064400042570001753000000000000622022557200166320ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/define.log010064400042570001753000000000000622022557200167750ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/macro.out010064400042570001753000000003720637716135000167140ustar00iancmtr00000400000236__tuning[] __endtuning[] H1[orig_style='H1']A heading before macro definition H1[orig_style='H1']A heading after macro definition N[orig_style='N']This is some text with several lines in it. N[orig_style='N']And a few more. N[orig_style='N']The end. sdf-2.001/t/macro/checked/catalog.out010064400042570001753000000006010637716123000172150ustar00iancmtr00000400000236__tuning[] __endtuning[] __table[format='1*';style='plain']1 __row[]Body __cell[cols=1;rows=1] N[orig_style='N']{{THING[jump='j1']ABC}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']{{THING[jump='j2']DEF}} __endtable[] N[orig_style='N']Testing masking ... __table[format='1*';style='plain']1 __row[]Body __cell[cols=1;rows=1] N[orig_style='N']{{THING[jump='j1']ABC}} __endtable[] sdf-2.001/t/macro/checked/endblock.out010064400042570001753000000000000622022557200173520ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/include.log010064400042570001753000000000000622022557200171660ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/execute.out010064400042570001753000000000660637716131200172530ustar00iancmtr00000400000236__tuning[] __endtuning[] E[orig_style='E']execute.sdf sdf-2.001/t/macro/checked/block.out010064400042570001753000000007000637716122200166760ustar00iancmtr00000400000236__tuning[] __endtuning[] E[orig_style='E']Hello world. E[orig_style='E'] E[orig_style='E']How are E[orig_style='E']you? H1[orig_style='H1']Heading 1 E[orig_style='E']Name Value E[orig_style='E']xyz 42 E[orig_style='E']abc "My favorite station" H2[orig_style='H2']Heading 2 E[orig_style='E']!block define E[orig_style='E']Name Value E[orig_style='E']xyz 42 E[orig_style='E']abc "My favorite station" E[orig_style='E']!endblock sdf-2.001/t/macro/checked/row.out010064400042570001753000000000000622022557200164000ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/endif.log010064400042570001753000000001560622022557200166440ustar00iancmtr00000400000236endif.sdf error, macro on 4: !endif not expected endif.sdf error, EOF at 20: !endif missing for !if on line 9 sdf-2.001/t/macro/checked/if.log010064400042570001753000000000000622022557200161410ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/line.log010064400042570001753000000001000622022557200164730ustar00iancmtr00000400000236line.sdf warning, macro on 43: the line number should be 43 now sdf-2.001/t/macro/checked/on_para.out010064400042570001753000000012340637716135400172340ustar00iancmtr00000400000236__tuning[] __endtuning[] H1[orig_style='H1']Heading 1 before on P1[orig_style='H1']Heading 1 after on P2[orig_style='H2']Heading 2 before on P2[orig_style='H2']HEADING 2 AFTER ON P3[orig_style='H3']Heading 3 before on P3[nopb=1;notoc=1;orig_style='H3']Heading 3 after on P4[orig_style='H4']Heading 4 after on P1[orig_style='H1']Another H1 P2[nopb=1;notoc=1;orig_style='H2']ANOTHER H2 P3[nopb=1;notoc=1;orig_style='H3']Another H3 E[orig_style='E']Some prepended example text. Note[id=2;orig_style='Note']This note should have an example paragraph prepended and a normal paragraph appended! N[orig_style='N']Some appended normal text. N[orig_style='N']Some ending text. sdf-2.001/t/macro/checked/class.out010064400042570001753000000020460637716124400167220ustar00iancmtr00000400000236__tuning[] __endtuning[] __table[format='0%-100%,1*';style='plain']2 __row[]Body __cell[cols=1;rows=1] N[orig_style='N']{{WID[jump='http://www.alpha.com']A}} __cell[cols=1;rows=1] N[orig_style='N']Alpha __row[]Body __cell[cols=1;rows=1] N[orig_style='N']{{WID[jump='http://www.gamma.com']C}} __cell[cols=1;rows=1] N[orig_style='N']Gamma __row[]Body __cell[cols=1;rows=1] N[orig_style='N']{{WID[]D}} __cell[cols=1;rows=1] N[orig_style='N'] __row[]Body __cell[cols=1;rows=1] N[orig_style='N']{{WID[jump='http://www.epsilon.com']E}} __cell[cols=1;rows=1] N[orig_style='N']Epsilon __endtable[] N[orig_style='N']This paragraph contains a short form ({{WID[jump='http://www.alpha.com']A}}) and a long form ({{WIDGET[jump='http://www.alpha.com']Alpha}}) of a widget. N[orig_style='N']This paragraph contains {{WIDGET[jump='http://www.alpha.com']Alpha}} and {{WID[jump='http://www.beta.com']B}} widgets. N[orig_style='N']This paragraph contains {{WID[]F}} and {{WIDGET[]Omega}} widgets. N[orig_style='N']This paragraph contains {{WID[]F}} and {{WIDGET[]Omega}} widgets. sdf-2.001/t/macro/checked/slide.log010064400042570001753000000000000622022557200166430ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/inherit.out010064400042570001753000000003130661527233400172500ustar00iancmtr00000400000236SDF include path is now: $SDFHOME/images. SDF include path is now: $SDFHOME/images. SDF include path is now: $SDFHOME/images. SDF include path is now: $SDFHOME/images. /qwe/xyz. __tuning[] __endtuning[] sdf-2.001/t/macro/checked/insert.log010064400042570001753000000000000622022557200170470ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/export.out010064400042570001753000000002310636603441000171200ustar00iancmtr00000400000236__tuning[] __endtuning[] __object[Name='num1';value=42]Variable __object[Name='str2';value='hello world']Variable __object[Name='num2';value=77]Variable sdf-2.001/t/macro/checked/else.out010064400042570001753000000000000622022557200165210ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/endtable.out010064400042570001753000000000000622022557200173470ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/cell.out010064400042570001753000000000000622022557200165100ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/table.out010064400042570001753000000032760637716137400167160ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']Some text before. __table[format='0%-100%,1*';style='columns']2 __row[]Heading N[orig_style='N']Hdg 1 __cell[] N[orig_style='N']Hdg 2 __row[]Body N[orig_style='N']Row 1, col 1 __cell[] N[orig_style='N']Row 1, col 2 __row[]Body N[orig_style='N']Row 2, col 1 __cell[] N[orig_style='N']Row 2, col 2 __row[]Footing N[orig_style='N']Footing 1 __cell[] N[orig_style='N']Footing 2 __endtable[] N[orig_style='N']Some text in the middle. __table[format='1*';style='rows']1 __endtable[] __table[format='1*';style='grid']1 __row[]Body __row[]Body __endtable[] __table[format='0%-100%,0%-100%,1*';style='columns']3 N[orig_style='N']Some text __cell[] __cell[] N[orig_style='N']Some text in row 1, column 3 __row[]Body __cell[] __cell[] N[orig_style='N']Some text in row 2, column2 __endtable[] __table[format='0%-100%,1*';style='columns']2 N[orig_style='N']Text in first table __row[]Body N[orig_style='N']Row 2, column 1 __cell[] N[orig_style='N']Row 2, column 2 start __table[format='0%-100%,1*';style='columns']2 N[orig_style='N']Text in second table __row[]Body N[orig_style='N']Text in second table __endtable[] N[orig_style='N']Row 2, column 2 end __row[]Body N[orig_style='N']hello world __endtable[] __table[format='0%-100%,1*';style='columns']2 __row[]Body __cell[] N[orig_style='N']This is a paragraph with a few lines. __cell[] N[orig_style='N']This is: LU1[orig_style='LU1']a list LU1[orig_style='LU1']with two entries. N[orig_style='N']And another paragraph. __row[]Body __cell[] N[orig_style='N']simple cell __cell[] N[orig_style='N']And another multi-line cell with lots and lots and lots of text. N[orig_style='N']The quick brown fox jumped over the slow green frog. __endtable[] sdf-2.001/t/macro/checked/define.out010064400042570001753000000003340637716126000170430ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']Variable num1 is 1. Variable num2 is 42. N[orig_style='N']Variable str1 is My favorite station. N[orig_style='N']Variable num2 is 28. Variable str2 is AA-My favorite station-ZZ. sdf-2.001/t/macro/checked/default.log010064400042570001753000000000000622022557200171670ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/include.out010064400042570001753000000002210637716132600172320ustar00iancmtr00000400000236__tuning[] __endtuning[] E[orig_style='E']# This file tests the include macro E[orig_style='E'] E[orig_style='E']!include "include.sdf"; example sdf-2.001/t/macro/checked/undef.log010064400042570001753000000001700622022557200166540ustar00iancmtr00000400000236undef.sdf warning, para. on 12: variable 'num1' not defined undef.sdf warning, para. on 12: variable 'str1' not defined sdf-2.001/t/macro/checked/elsif.log010064400042570001753000000002650622022557200166620ustar00iancmtr00000400000236elsif.sdf error, macro on 6: argument 'value' missing for macro 'elsif' elsif.sdf error, macro on 6: !elsif not expected elsif.sdf error, macro on 15: !elsif found after else macro sdf-2.001/t/macro/checked/init.log010064400042570001753000000001340622022557200165160ustar00iancmtr00000400000236init.sdf warning, macro on 7: 'OPT' variable 'OPT_STYLE' is read-only - ignoring definition sdf-2.001/t/macro/checked/endif.out010064400042570001753000000000000622022557200166560ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/line.out010064400042570001753000000001130637716134600165400ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']The file name is now myfile.xyz. sdf-2.001/t/macro/checked/on_phras.log010064400042570001753000000001000622022557200173550ustar00iancmtr00000400000236on_phras.sdf warning, para. on 5: unknown phrase style 'MYTYPE' sdf-2.001/t/macro/checked/endmacro.log010064400042570001753000000002020622022557200173370ustar00iancmtr00000400000236endmacro.sdf error, macro on 4: endmacro macro not expected endmacro.sdf error, EOF at 20: !endmacro missing for !macro on line 9 sdf-2.001/t/macro/checked/slide.out010064400042570001753000000006410637716137000167140ustar00iancmtr00000400000236__tuning[] __endtuning[] H2[orig_style='H2']Heading 2 H3[orig_style='H3']Heading 3 H1[orig_style='H1']Before H3[orig_style='H2']Heading 2 H4[orig_style='H3']Heading 3 H1[orig_style='H1']After H2[orig_style='H2']Heading 2 H3[orig_style='H3']Heading 3 H1[orig_style='H1']Before H4[orig_style='H2']Heading 2 H5[orig_style='H3']Heading 3 H1[orig_style='H1']After H2[orig_style='H2']Heading 2 H3[orig_style='H3']Heading 3 sdf-2.001/t/macro/checked/macro.log010064400042570001753000000000000622022557200166440ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/catalog.log010064400042570001753000000000000632311443000171470ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/execute.log010064400042570001753000000000000622022557200172050ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/endblock.log010064400042570001753000000002020622022557200173300ustar00iancmtr00000400000236endblock.sdf error, macro on 4: endblock macro not expected endblock.sdf error, EOF at 20: !endblock missing for !block on line 9 sdf-2.001/t/macro/checked/insert.out010064400042570001753000000001400637716134200171110ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']Variable varname is abc. Variable abc is hello world. sdf-2.001/t/macro/checked/block.log010064400042570001753000000000000622022557200166350ustar00iancmtr00000400000236sdf-2.001/t/macro/checked/row.log010064400042570001753000000001330622022557200163610ustar00iancmtr00000400000236row.sdf error, macro on 4: !row not expected row.sdf error, macro on 10: !row not expected sdf-2.001/t/macro/checked/if.out010064400042570001753000000007160637716132200162120ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']Monday's weather will be fine and hot with an afternoon thunderstorm. N[orig_style='N']No information for Tuesday. N[orig_style='N']Sydney will be fine on Wednesday. N[orig_style='N']Thursday's weather will be fine and hot with an afternoon thunderstorm. N[orig_style='N']No information for Friday. N[orig_style='N']Inside abc. N[orig_style='N']Inside xyz N[orig_style='N']Inside abc. N[orig_style='N']Else part of xyz. sdf-2.001/t/macro/on_para.sdf010064400042570001753000000015360626727767000156270ustar00iancmtr00000400000236# This file tests the on macro (for paragraphs) # Try changing the style H1: Heading 1 before on !on paragraph '';; $style =~ s/H/P/ H1: Heading 1 after on # Try conditionally changing the text H2: Heading 2 before on !on paragraph 'H2';; $text =~ tr/a-z/A-Z/ H2: Heading 2 after on # Try conditionally setting some attributes H3: Heading 3 before on !on paragraph 'H[23]';; $attr{'notoc'} = 1; $attr{'nopb'} = 1 H3: Heading 3 after on H4: Heading 4 after on H1: Another H1 H2: Another H2 H3: Another H3 # Try prepending/appending some text !on paragraph 'Note';; $attr{'id'}++; &PrependText('E:Some prepended example text.', '!message "prepending"; "Warning"') !on paragraph 'Note';; $attr{'id'}++; &AppendText('N:Some appended normal text.') Note: This note should have an example paragraph prepended and a normal paragraph appended! Some ending text. sdf-2.001/t/macro/block.t010064400042570001753000000000300647265372200147470ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/if.sdf010064400042570001753000000030410622022557200145560ustar00iancmtr00000400000236# This file tests conditional text # Test the if section !define CITY 'Brisbane' !if &Var("CITY") eq 'Brisbane' Monday's weather will be fine and hot with an afternoon thunderstorm. !else No information for Monday. !endif # Test the else section !define CITY 'Sydney' !if &Var("CITY") eq 'Brisbane' Tuesday's weather will be fine and hot with an afternoon thunderstorm. !else No information for Tuesday. !endif # Test the elsif section !define CITY 'Sydney' !if &Var("CITY") eq 'Brisbane' Wednesday's weather will be fine and hot with an afternoon thunderstorm. !elsif &Var("CITY") eq 'Sydney' Sydney will be fine on Wednesday. !else No information for Wednesday. !endif # Test the if section when an elsif is present !define CITY 'Brisbane' !if &Var("CITY") eq 'Brisbane' Thursday's weather will be fine and hot with an afternoon thunderstorm. !elsif &Var("CITY") eq 'Sydney' Sydney will be fine on Thursday. !else No information for Thursday. !endif # Test the else section when an elsif is present !define CITY 'Melbourne' !if &Var("CITY") eq 'Brisbane' Friday's weather will be fine and hot with an afternoon thunderstorm. !elsif &Var("CITY") eq 'Sydney' Sydney will be fine on Friday. !else No information for Friday. !endif # Test nested stuff - if inside an if !define abc !define xyz !if abc Inside abc. !if xyz Inside xyz !else Else part of xyz. !endif !else Else part of abc. !endif # Test nested stuff - else inside an if !define abc !define xyz 0 !if abc Inside abc. !if xyz Inside xyz !else Else part of xyz. !endif !else Else part of abc. !endif sdf-2.001/t/macro/else.t010064400042570001753000000000300647265372200146050ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/export.t010064400042570001753000000000300647265372200151760ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/execute.t010064400042570001753000000000300647265372200153170ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/undef.sdf010064400042570001753000000004620622022557200152650ustar00iancmtr00000400000236# This file tests the undef macro # define some values !define num1 42 !define str1 "Hello world" Variable num1 is [[num1]]. Variable str1 is [[str1]]. # now undefine them !undef num1 !undef str1 Variable num1 is [[num1]]. Variable str1 is [[str1]]. # try undefining a non-existent variable !undef num2 sdf-2.001/t/macro/inherit.sdf010064400042570001753000000010710647342107000156240ustar00iancmtr00000400000236# Test the inherit macro # Define a macro to dump the current include path in terms of # the current library directory !block script sub dump_path_Macro { local($sdfhome, $igc); $sdfhome = $'app_lib_dir; print "SDF include path is now:\n"; for $igc (@include_path) { $igc =~ s/$sdfhome/\$SDFHOME/; print "$igc.\n"; } } !endblock # Show the initial path !dump_path # Try a simple name !inherit "abc" !dump_path # Try a name with several parts !inherit "xyz/qwe" !dump_path # Try an absolute path !inherit "/qwe/xyz" !dump_path sdf-2.001/t/macro/elsif.sdf010064400042570001753000000004360622022557200152670ustar00iancmtr00000400000236# This file tests the elsif macro Some starting text. # Test an unexpected elsif (should generate an error) !elsif Some middle text. !if abc Inside abc. !else Inside else. # Test another unexpected elsif (should generate an error) !elsif xyz Inside elsif. !endif Some ending text. sdf-2.001/t/macro/on_phras.sdf010064400042570001753000000011020622022557200157650ustar00iancmtr00000400000236# This file tests the on macro (phrases) !on phrase '';; $text =~ s/object/Object/ Some text including a {{MYTYPE:mytype object}} and another {{B:bold object}}. # Try conditionally setting an attribute and changing the style !on phrase 'MY\w*';; $attr{'jump'} = "#$text"; $style = 'U' Some more text including a {{MYTYPE:mytype object}} and another {{B:bold object}}. Yet another {{MY:object}}. H2[obj="MYTYPE"] A Heading which is a MYTYPE # Try appending to a phrase !on phrase '';; $append .= ++$igc_count Hello {{world}}. I hope you are {{B:really {{U:well}}}} today. sdf-2.001/t/macro/slide.t010064400042570001753000000000300647265372400147570ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/endmacro.sdf010064400042570001753000000004650622022557200157570ustar00iancmtr00000400000236# This file tests the endmacro macro # Test an unexpected endmacro (should generate an error) !endmacro Some text. # Test a macro will no matching endmacro (should generate an error) !macro xyz Some text inside macro xyz. !macro abc This is some text with several lines in it. And a few more. !endmacro sdf-2.001/t/macro/endblock.sdf010064400042570001753000000004650622022557200157500ustar00iancmtr00000400000236# This file tests the endblock block # Test an unexpected endblock (should generate an error) !endblock Some text. # Test a block will no matching endblock (should generate an error) !block sdf Some text inside block xyz. !block sdf This is some text with several lines in it. And a few more. !endblock sdf-2.001/t/macro/insert.sdf010064400042570001753000000003260622022557200154670ustar00iancmtr00000400000236# This file tests the insert macro # define a variable with an arbitrary name !define varname "abc" !insert "define " . &Var("varname") . " 'hello world'" Variable varname is [[varname]]. Variable abc is [[abc]]. sdf-2.001/t/macro/else.sdf010064400042570001753000000003640622022557200151150ustar00iancmtr00000400000236# This file tests the else macro Some starting text. # Test an unexpected else (should generate an error) !else Some middle text. !if abc Inside abc. !endif # Test another unexpected else (should generate an error) !else Some ending text. sdf-2.001/t/macro/macro.sdf010064400042570001753000000003220622022557200152600ustar00iancmtr00000400000236# This file tests the macro macro H1: A heading before macro definition !macro abc This is some text with several lines in it. And a few more. !endmacro H1: A heading after macro definition !abc The end. sdf-2.001/t/macro/cell.sdf010064400042570001753000000001770626727672000151220ustar00iancmtr00000400000236# This file tests the cell macro # Try an unexpected cell !cell # Try another unexpected cell !table 1 !cell !endtable !cell sdf-2.001/t/macro/insert.t010064400042570001753000000000300647265372400151630ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/line.t010064400042570001753000000000300647265372400146060ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/include.sdf010064400042570001753000000001050622022557200156010ustar00iancmtr00000400000236# This file tests the include macro !include "include.sdf"; example sdf-2.001/t/macro/inherit.t010064400042570001753000000000300647265372400153210ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/elsif.t010064400042570001753000000000300647265372200147570ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/block.sdf010064400042570001753000000006620622022557200152600ustar00iancmtr00000400000236# This file tests blocks # a simple block !block example Hello world. How are you? !endblock # nested blocks where the inner one is executed !block sdf H1: Heading 1 !block example Name Value xyz 42 abc "My favorite station" !endblock H2: Heading 2 !endblock # nested blocks where the inner one is NOT executed !block example !block define Name Value xyz 42 abc "My favorite station" !endblock !endblock sdf-2.001/t/macro/on_para.t010064400042570001753000000000300647265372400152760ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/undef.t010064400042570001753000000000300647265372400147600ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/include.t010064400042570001753000000000300647265372400153020ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/if.t010064400042570001753000000000300647265372400142550ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/line.sdf010064400042570001753000000002530626730003200151050ustar00iancmtr00000400000236# This file tests the line and message macros !line 42 !message "the line number should be 43 now"; "Warning" !line 0; "myfile.xyz" The file name is now [[FILE_SHORT]]. sdf-2.001/t/macro/class.t010064400042570001753000000000300647265372200147620ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/class.sdf010064400042570001753000000015720622022557200152740ustar00iancmtr00000400000236# This file tests the class macro !class widgets 'WID,WIDGET' # Define some objects !block widgets; data; root="http://www." Name Long Jump A Alpha alpha.com B Beta beta.com C Gamma gamma.com !endblock # Now insert a table of them !block widgets Name,Jump,Long A C D E,http://www.epsilon.com,Epsilon !endblock # Hypertext should be generated for the object below This paragraph contains a short form ({{WID:A}}) and a long form ({{WIDGET:Alpha}}) of a widget. # Try short <-> long form conversion This paragraph contains {{WID[expand]A}} and {{WIDGET[shrink]Beta}} widgets. # Try unknown objects - should produce warnings This paragraph contains {{WID:F}} and {{WIDGET:Omega}} widgets. # Try short <-> long form conversion on unknown objects This paragraph contains {{WID[expand]F}} and {{WIDGET[shrink]Omega}} widgets. sdf-2.001/t/macro/endblock.t010064400042570001753000000000300647265372200154360ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/table.t010064400042570001753000000000300647265372400147460ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/macro.t010064400042570001753000000000300647265372400147600ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/endtable.sdf010064400042570001753000000001710626727522400157510ustar00iancmtr00000400000236# This file tests the endtable macro # Try an unexpected end !endtable # Try a missing end !table 1 !table 1 !endtable sdf-2.001/t/macro/row.t010064400042570001753000000000300647265372400144660ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/catalog.t010064400042570001753000000000300647265372200152670ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/define.t010064400042570001753000000000300647265372200151070ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/table.sdf010064400042570001753000000020210626727505400152570ustar00iancmtr00000400000236# This file tests the table macro Some text before. !table 2 !row "Heading" Hdg 1 !cell Hdg 2 !row Row 1, col 1 !cell Row 1, col 2 !row "Body" Row 2, col 1 !cell Row 2, col 2 !row "Footing" Footing 1 !cell Footing 2 !endtable Some text in the middle. # Try an empty table !table 1; style='rows' !endtable # Try some empty rows !table 1; style='grid' !row !row !endtable # Try some empty cells !table 3 Some text !cell !cell Some text in row 1, column 3 !row !cell !cell Some text in row 2, column2 !endtable # Try a nested table !table 2 Text in first table !row Row 2, column 1 !cell Row 2, column 2 start !table 2 Text in second table !row Text in second table !endtable Row 2, column 2 end !row hello world !endtable # Try some multi-line cells !table 2 !row !cell This is a paragraph with a few lines. !cell This is: * a list * with two entries. And another paragraph. !row !cell simple cell !cell And another multi-line cell with lots and lots and lots of text. The quick brown fox jumped over the slow green frog. !endtable sdf-2.001/t/macro/cell.t010064400042570001753000000000300647265372200145740ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/default.sdf010064400042570001753000000010150622022557200156030ustar00iancmtr00000400000236# This file tests the default macro # test numbers !default num1 !default num2 42 Variable num1 is [[num1]]. Variable num2 is [[num2]]. # test strings !default str1 "My favorite station" !default str2 "Hello world" Variable str1 is [[str1]]. Variable str2 is [[str2]]. # test expressions !default num3 42 * 2 / 3 !default str3 'AA-' . &Var("str1") . '-ZZ' Variable num3 is [[num3]]. Variable str3 is [[str3]]. # test re-definition !default num2 24 !default str2 str3 Variable num2 is [[num2]]. Variable str2 is [[str2]]. sdf-2.001/t/macro/row.sdf010064400042570001753000000001710626727515000150000ustar00iancmtr00000400000236# This file tests the row macro # Try an unexpected row !row # Try another unexpected row !table 1 !row !endtable !row sdf-2.001/t/macro/default.t010064400042570001753000000000300647265372200153010ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/endif.t010064400042570001753000000000300647265372200147420ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/endif.sdf010064400042570001753000000004300622022557200152440ustar00iancmtr00000400000236# This file tests the endif if # Test an unexpected endif (should generate an error) !endif Some text. # Test an if will no matching endif (should generate an error) !if sdf Some text inside if xyz. !if sdf This is some text with several lines in it. And a few more. !endif sdf-2.001/t/macro/init.sdf010064400042570001753000000003440622022557200151260ustar00iancmtr00000400000236!init OPT_STYLE="memo" # This file tests the init macro The new document style is [[OPT_STYLE]]. # This should produce a warning as OPT_STYLE is now readonly !define OPT_STYLE "fax" The final document style is [[OPT_STYLE]]. sdf-2.001/t/macro/export.sdf010064400042570001753000000004570622022557200155110ustar00iancmtr00000400000236# This file tests the export macro # define some variables !define num1 42 !define str1 "My favorite station" !define str2 "hello world" # export some of them !export num1 !export str2 # mark an undefined variable for export !export num2 # now define it (which should export it too) !define num2 77 sdf-2.001/t/macro/slide.sdf010064400042570001753000000005120622022557200152600ustar00iancmtr00000400000236# This file tests the slide_up and slide_down macros !macro sometext H2: Heading 2 H3: Heading 3 !endmacro !sometext # Try sliding down one level H1: Before !slide_down !sometext !slide_up H1: After !sometext # Try sliding down two levels H1: Before !slide_down !slide_down !sometext !slide_up !slide_up H1: After !sometext sdf-2.001/t/macro/on_phras.t010064400042570001753000000000300647265372400154700ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/catalog.sdf010064400042570001753000000004760632311440600156000ustar00iancmtr00000400000236# This file tests the catalog macro # Declare some objects !class things 'THING'; 'Name'; 'Jump' !block things; data Name Jump ABC j1 DEF j2 !endblock # Output a catalog of them !catalog things ''; columns="THING:Name" # Now try a mask ... Testing masking ... !catalog things 'A.*'; columns="THING:Name" sdf-2.001/t/macro/execute.sdf010064400042570001753000000002170622022557200156240ustar00iancmtr00000400000236# This file tests the include macro # Try a command which should give the same result under Unix and DOS !execute "echo execute.sdf"; example sdf-2.001/t/macro/init.t010064400042570001753000000000300647265372400146220ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/define.sdf010064400042570001753000000005640622022557200154210ustar00iancmtr00000400000236# This file tests the define macro # test numbers !define num1 !define num2 42 Variable num1 is [[num1]]. Variable num2 is [[num2]]. # test strings !define str1 "My favorite station" Variable str1 is [[str1]]. # test expressions (and re-definition) !define num2 42 * 2 / 3 !define str2 'AA-' . &Var("str1") . '-ZZ' Variable num2 is [[num2]]. Variable str2 is [[str2]]. sdf-2.001/t/macro/endtable.t010064400042570001753000000000300647265372200154330ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/macro/endmacro.t010064400042570001753000000000300647265372200154450ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/filter/004075500042570001753000000000000672243775200136675ustar00iancmtr00000400000236sdf-2.001/t/filter/checked/004075500042570001753000000000000672243775000152535ustar00iancmtr00000400000236sdf-2.001/t/filter/checked/sdf.out010064400042570001753000000016520637716147400165640ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']Some text before. N[orig_style='N']Some sdf LU2[orig_style='LU2']text. N[orig_style='N']Some middle text. N[orig_style='N']Some more sdf text. E[orig_style='E'] An example paragraph N[bold=1;orig_style='N';size='12pt';sp_before=4]Life is too short to: LU1[bold=1;orig_style='LU1';size='12pt';sp_before=4]drink bad wine LU1[bold=1;orig_style='LU1';size='12pt';sp_before=4]argue over silly things LU1[bold=1;orig_style='LU1';size='12pt';sp_before=4]not use SDF. N[bold=1;orig_style='N';size='12pt';sp_before=4]Don't you agree? N[orig_style='N']Middle. N[bad_apple=1;changed=1;orig_style='N']Life is also too short to: LU1[bad_apple=1;changed=1;orig_style='LU1']argue over good wine. N[orig_style='N';sp_before=6]Hello N[orig_style='N';sp_before=5]world N[orig_style='N';sp_before=9]goodbye N[orig_style='N';sp_before=20]world N[orig_style='N';sp_before=6]Goodbye! N[orig_style='N']Some text after. sdf-2.001/t/filter/checked/script.log010064400042570001753000000000000622022557000172310ustar00iancmtr00000400000236sdf-2.001/t/filter/checked/about.log010064400042570001753000000000000622022557200170410ustar00iancmtr00000400000236sdf-2.001/t/filter/checked/appendix.out010064400042570001753000000010410637716142000175770ustar00iancmtr00000400000236__tuning[] __endtuning[] A1[orig_style='H1']Heading 1 inside an appendix block A2[orig_style='H2']Purpose N[orig_style='N']This manual provides an overview of ... N[orig_style='N']Directions for ... are also provided. A2[orig_style='H2']Scope N[orig_style='N']This manual contains: LF1[orig_style='LF1']a summary of ... LN1[orig_style='LN1']an overview of ... N[orig_style='N']The following documents may also be of interest: LU1[orig_style='LU1']abc LU1[orig_style='LU1']xyz H2[orig_style='H2']See Also N[orig_style='N']The person next to you. sdf-2.001/t/filter/checked/front.out010064400042570001753000000004020637716144600171270ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']Some text before. N[orig_style='N']Some sdf LU2[orig_style='LU2']text. N[orig_style='N']Some middle text. N[orig_style='N']Some more sdf text. E[orig_style='E'] An example paragraph N[orig_style='N']Some text after. sdf-2.001/t/filter/checked/comment.out010064400042570001753000000001360637716142400174410ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']Some text before. N[orig_style='N']Some text after. sdf-2.001/t/filter/checked/plain.out010064400042570001753000000010350637716146400171050ustar00iancmtr00000400000236__tuning[] __endtuning[] P1[orig_style='H1']Heading 1 inside a plain block P2[orig_style='H2']Purpose N[orig_style='N']This manual provides an overview of ... N[orig_style='N']Directions for ... are also provided. P2[orig_style='H2']Scope N[orig_style='N']This manual contains: LF1[orig_style='LF1']a summary of ... LN1[orig_style='LN1']an overview of ... N[orig_style='N']The following documents may also be of interest: LU1[orig_style='LU1']abc LU1[orig_style='LU1']xyz H2[orig_style='H2']See Also N[orig_style='N']The person next to you. sdf-2.001/t/filter/checked/example.out010064400042570001753000000016210637716144200174320ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']Some text before. E[orig_style='E']# E[orig_style='E']# A header E[orig_style='E']# E[orig_style='E'] Some example E[orig_style='E'] text. E[orig_style='E'] Back to indent of 2. N[orig_style='N']Some middle text. E[orig_style='E'] Some E[orig_style='E'] {{1[]example}} text. E[orig_style='E'] Some [\[more]\] E[orig_style='E'] {\{example}\} text. E[orig_style='E'] Yet another block of E[orig_style='E']{{1[]example}} text. E[orig_style='E']123456789a 23456789b 23456789c 23456789d 23456789e 23456789f 23456789g 23456789h E[orig_style='E']123456789A 23456789B 23456789C 23456789D 23456789E 23456789F 23456789G 23456789H E80[orig_style='E80']123456789a 23456789b 23456789c 23456789d 23456789e 23456789f 23456789g 23456789h E80[orig_style='E80']123456789A 23456789B 23456789C 23456789D 23456789E 23456789F 23456789G 23456789H N[orig_style='N']Some text after. sdf-2.001/t/filter/checked/table.out010064400042570001753000000313700645642273400170740ustar00iancmtr00000400000236__tuning[] __endtuning[] __table[format='0%-100%,1*';style='columns']2 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]Name}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Age}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Bill __cell[cols=1;rows=1] N[orig_style='N']64 __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Mary __cell[cols=1;rows=1] N[orig_style='N']53 __endtable[] __table[format='0%-100%,1*';style='grid']2 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]Name}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Age}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Bill __cell[cols=1;rows=1] N[orig_style='N']64 __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Mary __cell[cols=1;rows=1] N[orig_style='N']53 __endtable[] __table[format='40%,20%';style='columns']2 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]Name}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Age}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Bill Bloggs __cell[cols=1;rows=1] N[orig_style='N']64 __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Mary Jones __cell[cols=1;rows=1] N[orig_style='N']53 __endtable[] __table[format='0%-100%,1*';style='columns']2 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]User}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Email}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']{{2[]Tim}} __cell[cols=1;rows=1] N[orig_style='N']{{EMAIL[jump='mailto:tjh']tjh}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']{{2[]Chris}} __cell[cols=1;rows=1] N[orig_style='N']{{EMAIL[jump='mailto:cjm']cjm}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']{{2[]Ian}} __cell[cols=1;rows=1] N[orig_style='N']{{EMAIL[jump='mailto:ianc']ianc}} __endtable[] __table[format='0%-100%,1*';style='columns']2 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]User}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Email}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Tim __cell[cols=1;rows=1] N[orig_style='N']tjh __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Chris __cell[cols=1;rows=1] N[orig_style='N']cjm __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Ian __cell[cols=1;rows=1] N[orig_style='N']ianc __endtable[] __table[format='0%-100%,1*';style='columns']2 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]Name}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Favorite Drink}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Bob __cell[cols=1;rows=1] N[orig_style='N']red wine __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Paul __cell[cols=1;rows=1] N[orig_style='N']anything __endtable[] __table[format='0%-100%,1*';style='columns']2 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]Name}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Favorite_Drink}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Bob __cell[cols=1;rows=1] N[orig_style='N']red wine __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Paul __cell[cols=1;rows=1] N[orig_style='N']anything __endtable[] __table[format='0%-100%,1*';style='columns']2 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]Name}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Favorite Drink}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Family: __cell[cols=1;rows=1] N[orig_style='N'] __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Bob __cell[cols=1;rows=1] N[orig_style='N']red wine __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Robyn __cell[cols=1;rows=1] N[orig_style='N']white wine __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Friends: __cell[cols=1;rows=1] N[orig_style='N'] __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Paul __cell[cols=1;rows=1] N[orig_style='N']anything __endtable[] __table[format='0%-100%,1*';style='columns']2 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]Name}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Favorite Drink}} __row[]Group __cell[cols=1;rows=1] N[orig_style='N']{{2[]Family:}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Bob __cell[cols=1;rows=1] N[orig_style='N']red wine __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Robyn __cell[cols=1;rows=1] N[orig_style='N']white wine __row[]Group __cell[cols=1;rows=1] N[orig_style='N']{{2[]Friends:}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Paul __cell[cols=1;rows=1] N[orig_style='N']anything __endtable[] __table[format='1*';style='columns']1 __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Just a body row __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Add another. __endtable[] __table[format='0%-100%,1*';style='columns']2 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]Term}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Definition}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']OMT __cell[cols=1;rows=1] N[orig_style='N']Object Modelling Technique - an object modelling method developed by Rumbaugh __row[]Body __cell[cols=1;rows=1] N[orig_style='N']VGA __cell[cols=1;rows=1] N[orig_style='N']A PC graphics card standard which defines certain sets of screen resolutions __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Port __cell[cols=1;rows=1] N[orig_style='N']Take your pick from: LU1[orig_style='LU1']an alcoholic drink LU1[orig_style='LU1']a resting place for ships LU1[orig_style='LU1']etc. __endtable[] __table[format='0%-100%,1*';style='columns']2 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]one}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]two}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']-l is the log __cell[cols=1;rows=1] __import[fullname='foo.ps']foo.ps LU2[orig_style='LU2']o is the output extension. E[orig_style='E'] example __endtable[] __table[format='0%-100%,1*';style='columns']2 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]Name}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Value}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']1 __cell[cols=1;rows=1] N[orig_style='N']a __row[]Body __cell[cols=1;rows=1] N[changed=1;orig_style='N']2 __cell[cols=1;rows=1] N[changed=1;orig_style='N']b __endtable[] __table[format='0%-100%,1*';style='columns']2 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]Name}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Value}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']1 __cell[cols=1;rows=1] N[orig_style='N']a __row[]Body __cell[cols=1;rows=1] N[changed=1;orig_style='N']2 __cell[cols=1;rows=1] N[changed=1;orig_style='N']b __row[]Body __cell[cols=1;rows=1] N[orig_style='N']3 __cell[cols=1;rows=1] N[orig_style='N']c __endtable[] __table[format='0%-100%,0%-100%,1*';style='columns']3 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]C++}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]C}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]B}} __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]a}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]b}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]c}} __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]85}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]75}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]73?}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']q __cell[cols=1;rows=1] N[orig_style='N']w __cell[cols=1;rows=1] N[orig_style='N']e __row[]Footing __cell[cols=1;rows=1] N[orig_style='N']{{2[]r}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]s}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]t}} __endtable[] __table[format='0%-100%,0%-100%,1*';style='columns']3 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]Name}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Jump}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Rubbish}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']product1 __cell[cols=1;rows=1] N[orig_style='N']url1 __cell[cols=1;rows=1] N[orig_style='N']x __row[]Body __cell[cols=1;rows=1] N[orig_style='N']product2 __cell[cols=1;rows=1] N[orig_style='N']url2 __cell[cols=1;rows=1] N[orig_style='N']y __row[]Body __cell[cols=1;rows=1] N[orig_style='N']product3 __cell[cols=1;rows=1] N[orig_style='N']url3 __cell[cols=1;rows=1] N[orig_style='N']z __endtable[] __table[format='0%-100%,0%-100%,0%-100%,0%-100%,0%-100%,1*';style='columns']6 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]Big}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Small}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Big}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Small}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Big}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Small}} __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]Letter}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]One}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Letter}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]One}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Letter}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]One}} __row[]Group __cell[cols=1;rows=1] N[orig_style='N']{{2[]Vowels:}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']A __cell[cols=1;rows=1] N[orig_style='N']a __cell[cols=1;rows=1] N[orig_style='N']E __cell[cols=1;rows=1] N[orig_style='N']e __cell[cols=1;rows=1] N[orig_style='N']I __cell[cols=1;rows=1] N[orig_style='N']i __row[]Body __cell[cols=1;rows=1] N[orig_style='N']O __cell[cols=1;rows=1] N[orig_style='N']o __cell[cols=1;rows=1] N[orig_style='N']U __cell[cols=1;rows=1] N[orig_style='N']u __row[]Group __cell[cols=1;rows=1] N[orig_style='N']{{2[]Others:}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']B __cell[cols=1;rows=1] N[orig_style='N']b __cell[cols=1;rows=1] N[orig_style='N']C __cell[cols=1;rows=1] N[orig_style='N']c __cell[cols=1;rows=1] N[orig_style='N']D __cell[cols=1;rows=1] N[orig_style='N']d __row[]Body __cell[cols=1;rows=1] N[orig_style='N']F __cell[cols=1;rows=1] N[orig_style='N']f __cell[cols=1;rows=1] N[orig_style='N']G __cell[cols=1;rows=1] N[orig_style='N']g __cell[cols=1;rows=1] N[orig_style='N']H __cell[cols=1;rows=1] N[orig_style='N']h __row[]Footing __cell[cols=1;rows=1] N[orig_style='N']{{2[]Upper}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Lower}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Upper}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Lower}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Upper}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]Lower}} __endtable[] __table[format='0%-100%,0%-100%,1*';style='columns']3 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]A}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]B}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]C}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Hello world __cell[cols=1;rows=1] N[orig_style='N']A2 __cell[cols=1;rows=1] N[orig_style='N'] __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Hi __cell[cols=1;rows=1] N[orig_style='N']How are __cell[cols=1;rows=1] N[orig_style='N']you\ __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Q __cell[cols=1;rows=1] N[orig_style='N']W __cell[cols=1;rows=1] N[orig_style='N']E:R __row[]Body __cell[cols=1;rows=1] N[orig_style='N']S\\X __cell[cols=1;rows=1] N[orig_style='N']Y\\\Z __cell[cols=1;rows=1] N[orig_style='N'] __endtable[] __table[format='0%-100%,0%-100%,0%-100%,1*';style='columns']4 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]one}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]two}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]three}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]four}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']line1-1 __cell[cols=1;rows=1] N[orig_style='N']two __cell[cols=1;rows=1] N[orig_style='N']three __cell[cols=1;rows=1] N[orig_style='N']large four E[orig_style='E']example format four __row[]Body __cell[cols=1;rows=1] N[orig_style='N']line2-1 __cell[cols=1;rows=1] N[orig_style='N']large two (2) E[orig_style='E']example format for two __cell[cols=1;rows=1] N[orig_style='N']three __cell[cols=1;rows=1] N[orig_style='N']four __row[]Body __cell[cols=1;rows=1] N[orig_style='N']line3-1 __cell[cols=1;rows=1] N[orig_style='N']large two again E[orig_style='E']example format 2+ __cell[cols=1;rows=1] N[orig_style='N']large three too E[orig_style='E']col3 example format __cell[cols=1;rows=1] N[orig_style='N']normal four __endtable[] __table[format='0%-100%,1*';style='columns']2 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]A}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]C}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']1 __cell[cols=1;rows=1] N[orig_style='N']3 __row[]Body __cell[cols=1;rows=1] N[orig_style='N']5 __cell[cols=1;rows=1] N[orig_style='N']7 __endtable[] __table[format='0%-100%,0%-100%,1*';style='columns']3 __row[]Heading __cell[cols=1;rows=1] N[orig_style='N']{{2[]A}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]B}} __cell[cols=1;rows=1] N[orig_style='N']{{2[]D}} __row[]Body __cell[cols=1;rows=1] N[orig_style='N']1 __cell[cols=1;rows=1] N[orig_style='N']2 __cell[cols=1;rows=1] N[orig_style='N']4 __row[]Body __cell[cols=1;rows=1] N[orig_style='N']5 __cell[cols=1;rows=1] N[orig_style='N']6 __cell[cols=1;rows=1] N[orig_style='N']8 __endtable[] yle='N']Bob __cell[cols=1;rows=1] N[orig_style='N']red wine __row[]Body __cell[cols=1;rows=1] N[orig_style='N']Paul __cell[cols=1;rows=1] N[orig_style='N']anything __endtable[] __table[format='0%-100%,1*';style='columns']2 __row[]Heading __cell[cols=1;rows=1] N[orsdf-2.001/t/filter/checked/parastyl.out010064400042570001753000000010240637716145600176400ustar00iancmtr00000400000236__tuning[] __endtuning[] MY1[orig_style='MY1']My level 1 paragraph MY2[orig_style='MY2']My level 2 paragraph MY3[orig_style='MY3']My level 3 paragraph MY1[orig_style='MY1']My level 1 paragraph MY2[orig_style='MY2'] My level 2 paragraph MY3[orig_style='MY3']My level 3 paragraph MY1[orig_style='MY1']My level 1 paragraph MY2[orig_style='MY2'] My level 2 paragraph MY3[orig_style='MY3']My level 3 paragraph MY1[orig_style='MY1']My level 1 paragraph MY2[orig_style='MY2'] My level 2 paragraph MY3[orig_style='MY3']My level 3 paragraph sdf-2.001/t/filter/checked/end.log010064400042570001753000000000000622022557000164730ustar00iancmtr00000400000236sdf-2.001/t/filter/checked/script.out010064400042570001753000000001220636603441000172660ustar00iancmtr00000400000236variable xyz is 42. variable abc is My favorite station. __tuning[] __endtuning[] sdf-2.001/t/filter/checked/about.out010064400042570001753000000010670637716141000171100ustar00iancmtr00000400000236__tuning[] __endtuning[] P2[component='prechapter';orig_style='H1']About This Manual P3[notoc=1;orig_style='H2']Purpose N[orig_style='N']This manual provides an overview of ... N[orig_style='N']Directions for ... are also provided. P3[notoc=1;orig_style='H2']Scope N[orig_style='N']This manual contains: LF1[orig_style='LF1']a summary of ... LN1[orig_style='LN1']an overview of ... N[orig_style='N']The following documents may also be of interest: LU1[orig_style='LU1']abc LU1[orig_style='LU1']xyz H2[orig_style='H2']See Also N[orig_style='N']The person next to you. sdf-2.001/t/filter/checked/inline.log010064400042570001753000000000000622022557000172030ustar00iancmtr00000400000236sdf-2.001/t/filter/checked/define.log010064400042570001753000000001760622022557000171750ustar00iancmtr00000400000236define.sdf warning, para. on 11: variable 'my_xyz' not defined define.sdf warning, para. on 11: variable 'my_abc' not defined sdf-2.001/t/filter/checked/address.log010064400042570001753000000000000622022557200173540ustar00iancmtr00000400000236sdf-2.001/t/filter/checked/default.log010064400042570001753000000002000622022557000173530ustar00iancmtr00000400000236default.sdf warning, para. on 13: variable 'my_xyz' not defined default.sdf warning, para. on 13: variable 'my_abc' not defined sdf-2.001/t/filter/checked/sdf.log010064400042570001753000000002140622022557000165100ustar00iancmtr00000400000236sdf.sdf warning, block on 33: unknown paragraph attribute 'bad_apple' sdf.sdf warning, block on 33: unknown paragraph attribute 'bad_apple' sdf-2.001/t/filter/checked/end.out010064400042570001753000000003140637716143600165460ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']Some text before. N[orig_style='N']Some middle text. N[orig_style='N']Some text after. N[orig_style='N']Some text inside. N[orig_style='N']Some more text inside. sdf-2.001/t/filter/checked/appendix.log010064400042570001753000000000000622022557200175370ustar00iancmtr00000400000236sdf-2.001/t/filter/checked/front.log010064400042570001753000000000000622022557200170570ustar00iancmtr00000400000236sdf-2.001/t/filter/checked/comment.log010064400042570001753000000000000622022557000173670ustar00iancmtr00000400000236sdf-2.001/t/filter/checked/plain.log010064400042570001753000000000000622022557200170320ustar00iancmtr00000400000236sdf-2.001/t/filter/checked/example.log010064400042570001753000000000760622022557000173750ustar00iancmtr00000400000236example.sdf warning, block on 18: variable 'more' not defined sdf-2.001/t/filter/checked/table.log010064400042570001753000000005640637722305200170410ustar00iancmtr00000400000236table.sdf warning, block on 97: unable to find image 'foo.ps' LAST 3,2 CELL[0,0]=Name LAST 3,2 CELL[0,1]=Jump LAST 3,2 CELL[0,2]=Rubbish LAST 3,2 CELL[1,0]=product1 LAST 3,2 CELL[1,1]=url1 LAST 3,2 CELL[1,2]=x LAST 3,2 CELL[2,0]=product2 LAST 3,2 CELL[2,1]=url2 LAST 3,2 CELL[2,2]=y LAST 3,2 CELL[3,0]=product3 LAST 3,2 CELL[3,1]=url3 LAST 3,2 CELL[3,2]=z AT END OF TABLE sdf-2.001/t/filter/checked/parastyl.log010064400042570001753000000004040622022557200175760ustar00iancmtr00000400000236parastyl.sdf warning, macro on 11: unknown paragraph style 'MY1' parastyl.sdf warning, macro on 11: unknown paragraph style 'MY2' parastyl.sdf warning, macro on 11: unknown paragraph style 'MY3' parastyl.sdf warning, macro on 21: unknown paragraph style 'MY3' sdf-2.001/t/filter/checked/inline.out010064400042570001753000000004020637716145200172520ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']Some text before. __inline[target='raw']Some inline __inline[target='raw']text. N[orig_style='N']Some middle text. __inline[target='raw']Some more __inline[target='raw']inline text. N[orig_style='N']Some text after. sdf-2.001/t/filter/checked/define.out010064400042570001753000000010570637716143200172330ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']Variable xyz is 42. Variable abc is My favorite station. N[orig_style='N']Variable my_xyz is . Variable my_abc is . N[orig_style='N']Variable xyz is 42. Variable abc is My favorite station. N[orig_style='N']Variable my_xyz is 23. Variable my_abc is Alpha Beta Gamma. __object[Name='xyz';value=17]Variable __object[Name='abc';value='My favorite 3 letters']Variable N[orig_style='N']Variable xyz is 17. Variable abc is My favorite 3 letters. N[orig_style='N']Variable my_xyz is 23. Variable my_abc is Alpha Beta Gamma. sdf-2.001/t/filter/checked/address.out010064400042570001753000000003050637716141400174210ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']Some text. Addr[orig_style='Addr']Bill Bloggs Addr[orig_style='Addr']43 Smith Lane Addr[orig_style='Addr']Brisbane Q 4001 N[orig_style='N']Some more text. sdf-2.001/t/filter/checked/default.out010064400042570001753000000010530637716143000174170ustar00iancmtr00000400000236__tuning[] __endtuning[] N[orig_style='N']Variable xyz is 77. Variable abc is My favorite station. N[orig_style='N']Variable my_xyz is . Variable my_abc is . N[orig_style='N']Variable xyz is 77. Variable abc is My favorite station. N[orig_style='N']Variable my_xyz is 23. Variable my_abc is Alpha Beta Gamma. __object[Name='xyz';value=77]Variable __object[Name='abc';value='My favorite station']Variable N[orig_style='N']Variable xyz is 77. Variable abc is My favorite station. N[orig_style='N']Variable my_xyz is 23. Variable my_abc is Alpha Beta Gamma. sdf-2.001/t/filter/appendix.sdf010064400042570001753000000005670622022557200161660ustar00iancmtr00000400000236# This file tests the appendix filter !block appendix H1: Heading 1 inside an appendix block H2: Purpose This manual provides an overview of ... Directions for ... are also provided. H2: Scope This manual contains: ^ a summary of ... + an overview of ... The following documents may also be of interest: * abc * xyz !endblock H2: See Also The person next to you. sdf-2.001/t/filter/end.sdf010064400042570001753000000002560622022557200151170ustar00iancmtr00000400000236# This file tests the end filter Some text before. !block end Some text inside. !endblock Some middle text. !block end Some more text inside. !endblock Some text after. sdf-2.001/t/filter/front.sdf010064400042570001753000000003110622022557000154670ustar00iancmtr00000400000236# This file tests the front filter Some text before. !block front Some sdf - text. !endblock Some middle text. !block front Some more sdf text. E: An example paragraph !endblock Some text after. sdf-2.001/t/filter/plain.sdf010064400042570001753000000005550622022557000154540ustar00iancmtr00000400000236# This file tests the plain filter !block plain H1: Heading 1 inside a plain block H2: Purpose This manual provides an overview of ... Directions for ... are also provided. H2: Scope This manual contains: ^ a summary of ... + an overview of ... The following documents may also be of interest: * abc * xyz !endblock H2: See Also The person next to you. sdf-2.001/t/filter/example.t010064400042570001753000000000300647265372200154740ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/filter/inline.sdf010064400042570001753000000003230622022557200156220ustar00iancmtr00000400000236# This file tests the inline filter Some text before. !block inline; target='raw' Some inline text. !endblock Some middle text. !block inline; target='raw' Some more inline text. !endblock Some text after. sdf-2.001/t/filter/define.sdf010064400042570001753000000012530622022557000155770ustar00iancmtr00000400000236# This file tests the define filter !block define Name Value xyz 42 abc "My favorite station" !endblock Variable xyz is [[xyz]]. Variable abc is [[abc]]. Variable my_xyz is [[my_xyz]]. Variable my_abc is [[my_abc]]. # Test the family parameter !block define; family="my" Name Value xyz 23 abc "Alpha Beta Gamma" !endblock Variable xyz is [[xyz]]. Variable abc is [[abc]]. Variable my_xyz is [[my_xyz]]. Variable my_abc is [[my_abc]]. # Test exporting !block define; export Name Value xyz 17 abc "My favorite 3 letters" !endblock Variable xyz is [[xyz]]. Variable abc is [[abc]]. Variable my_xyz is [[my_xyz]]. Variable my_abc is [[my_abc]]. sdf-2.001/t/filter/parastyl.sdf010064400042570001753000000013230627761471000162140ustar00iancmtr00000400000236# This file tests the parastyles filter # Setup a test section !macro MYTEXT MY1: My level 1 paragraph MY2: My level 2 paragraph MY3: My level 3 paragraph !endmacro # Test section before styles are declared !MYTEXT # Declare some styles !block parastyles Name Category MY1 MY2 example !endblock # Test section after definition but before declaration !MYTEXT # Define some styles !block parastyles Name To Attributes MY2 H2 MY3 P3 notoc !endblock # Test section after definition !MYTEXT # Redefine some styles !block parastyles Name To Attributes MY2 P2 nopb MY3 MY2 !endblock # Test section after redefinition !MYTEXT sdf-2.001/t/filter/table.sdf010064400042570001753000000067600645642270600154570ustar00iancmtr00000400000236# This file tests the table filter # Test a simple table !block table Name Age Bill 64 Mary 53 !endblock # Test the style parameter !block table; style="grid" Name Age Bill 64 Mary 53 !endblock # Test the format parameter !block table; format=42 Name Age Bill Bloggs 64 Mary Jones 53 !endblock # Test the tags parameter !block table; tags="2,EMAIL" User:Email Tim:tjh Chris:cjm Ian:ianc !endblock # Test the parseline parameter !block table; parseline="User:Email" Tim:tjh Chris:cjm Ian:ianc !endblock # Test the niceheadings parameter !block table Name Favorite_Drink Bob red wine Paul anything !endblock !block table; niceheadings=0 Name Favorite_Drink Bob red wine Paul anything !endblock # Test the groups parameter !block table Name Favorite_Drink Family: Bob red wine Robyn white wine Friends: Paul anything !endblock !block table; groups Name Favorite_Drink Family: Bob red wine Robyn white wine Friends: Paul anything !endblock # Test the noheadings parameter !block table; noheadings Dummy_Heading Just a body row Add another. !endblock # Test multi-line cells !block table Term Definition OMT << Object Modelling Technique - an object modelling method developed by Rumbaugh >> VGA << A PC graphics card standard which defines certain sets of screen resolutions >> Port << Take your pick from: * an alcoholic drink * a resting place for ships * etc. >> !endblock # Try nested macros !block table one:two -l is the log:<< !import "foo.ps" -o is the output extension. E: example >> !endblock # Try macros around rows !block table Name Value 1 a !block sdf; changed 2 b !endblock !if all 3 c !endif !endblock # And conditional macros, in particular !define all !block table Name Value 1 a !block sdf; changed 2 b !endblock !if all 3 c !endif !endblock # Test multi-line headings and footings !block table; headings=3; footings A B C C++ C B a b c 85 75 73? q w e r s t !endblock # Test oncell processing !block script sub dump { print STDERR "LAST $last_row,$last_col\n"; print STDERR "CELL[$row,$col]=$cell\n"; if ( ($row == $last_row) && ($col == $last_col) ) { print STDERR "AT END OF TABLE\n"; } } !endblock !block table; oncell='&dump()'; Name:Jump:Rubbish product1:url1:x product2:url2:y product3:url3:z !endblock # Test the wrap attribute !block table; wrap=3; groups; footings; headings=2 A B Big Small Letter One Vowels: A a E e I i O o U u Others: B b C c D d F f G g H h Upper Lower !endblock # Test continuation lines !block table A:B:C Hello \ world:A2 Hi:How are:you\\ Q:W:E:R S\\\ X:Y\\\\ Z !endblock # Test non-last multi-line cells !block table one:two:three:four line1-1:two:three:<< large four E:example format four >> line2-1:<< large two (2) E:example format for two >>:three:four line3-1:<< large two again E:example format 2+ >>:<< large three too E:col3 example format >>:normal four !endblock # Test the select attribute !block table; select='A,C' A B C D 1 2 3 4 5 6 7 8 !endblock # Test the delete attribute !block table; delete='C' A B C D 1 2 3 4 5 6 7 8 !endblock sdf-2.001/t/filter/address.t010064400042570001753000000000300647265372000154640ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/filter/parastyl.t010064400042570001753000000000300647265372200157000ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/filter/inline.t010064400042570001753000000000300647265372200153170ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/filter/default.t010064400042570001753000000000300647265372200154650ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/filter/sdf.sdf010064400042570001753000000012330622022557200151210ustar00iancmtr00000400000236# This file tests the sdf filter Some text before. !block sdf Some sdf - text. !endblock Some middle text. !block sdf Some more sdf text. E: An example paragraph !endblock # Test arbitary parameters !block sdf; size='12pt'; bold; sp_before=4 Life is too short to: * drink bad wine * argue over silly things * not use SDF. Don't you agree? !endblock Middle. # Test an unknown attribute !block sdf; bad_apple; changed Life is also too short to: * argue over good wine. !endblock # Test nesting and overriding !block sdf; sp_before=6 Hello [sp_before=5]world !block sdf; sp_before=9 goodbye [sp_before=20]world !endblock Goodbye! !endblock Some text after. sdf-2.001/t/filter/about.sdf010064400042570001753000000005400622022557200154570ustar00iancmtr00000400000236# This file tests the about filter !block about H1: About This Manual H2: Purpose This manual provides an overview of ... Directions for ... are also provided. H2: Scope This manual contains: ^ a summary of ... + an overview of ... The following documents may also be of interest: * abc * xyz !endblock H2: See Also The person next to you. sdf-2.001/t/filter/address.sdf010064400042570001753000000002050622022557200157700ustar00iancmtr00000400000236# This file tests the address filter Some text. !block address Bill Bloggs 43 Smith Lane Brisbane Q 4001 !endblock Some more text. sdf-2.001/t/filter/default.sdf010064400042570001753000000012770622022557000157770ustar00iancmtr00000400000236# This file tests the default filter !define xyz 77 !block default Name Value xyz 42 abc "My favorite station" !endblock Variable xyz is [[xyz]]. Variable abc is [[abc]]. Variable my_xyz is [[my_xyz]]. Variable my_abc is [[my_abc]]. # Test the family parameter !block default; family="my" Name Value xyz 23 abc "Alpha Beta Gamma" !endblock Variable xyz is [[xyz]]. Variable abc is [[abc]]. Variable my_xyz is [[my_xyz]]. Variable my_abc is [[my_abc]]. # Test exporting !block default; export Name Value xyz 17 abc "My favorite 3 letters" !endblock Variable xyz is [[xyz]]. Variable abc is [[abc]]. Variable my_xyz is [[my_xyz]]. Variable my_abc is [[my_abc]]. sdf-2.001/t/filter/script.t010064400042570001753000000000300647265372200153450ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/filter/appendix.t010064400042570001753000000000300647265372200156510ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/filter/define.t010064400042570001753000000000300647265372200152730ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/filter/front.t010064400042570001753000000000300647265372200151710ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/filter/comment.t010064400042570001753000000000300647265372200155030ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/filter/sdf.t010064400042570001753000000000300647265372200146150ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/filter/end.t010064400042570001753000000000300647265372200146070ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/filter/comment.sdf010064400042570001753000000001660622022557000160110ustar00iancmtr00000400000236# This file tests the comment filter Some text before. !block comment Some text inside. !endblock Some text after. sdf-2.001/t/filter/script.sdf010064400042570001753000000003250630325452200156510ustar00iancmtr00000400000236# This file tests the script filter !block define Name Value xyz 42 abc "My favorite station" !endblock !block script for $igc ('xyz', 'abc') { print "variable $igc is $var{$igc}.\n"; } !endblock sdf-2.001/t/filter/example.sdf010064400042570001753000000016670622022557200160130ustar00iancmtr00000400000236# This file tests the example filter Some text before. # Test a simple example !block example # # A header # Some example text. Back to indent of 2. !endblock Some middle text. # Test normal (non-pure) blocks !block example Some [[more]] {{example}} text. !endblock # Test pure blocks !block example; pure Some [[more]] {{example}} text. !endblock # Test the skipheader parameter !block example; skipheader # $Id$ # A header will an RCS-Id line at the top # Yet another block of {{example}} text. !endblock # Test wide blocks !block example 123456789a 23456789b 23456789c 23456789d 23456789e 23456789f 23456789g 23456789h 123456789A 23456789B 23456789C 23456789D 23456789E 23456789F 23456789G 23456789H !endblock !block example; wide 123456789a 23456789b 23456789c 23456789d 23456789e 23456789f 23456789g 23456789h 123456789A 23456789B 23456789C 23456789D 23456789E 23456789F 23456789G 23456789H !endblock Some text after. sdf-2.001/t/filter/table.t010064400042570001753000000000300647265372200151300ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/filter/about.t010064400042570001753000000000300647265372000151510ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/filter/plain.t010064400042570001753000000000300647265372200151440ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/doatest.clone010075500042570001753000000002040647265371000150570ustar00iancmtr00000400000236#!/bin/sh set -e for sdf in */*.sdf; do cmd="cp doatest.templ `dirname $sdf`/`basename $sdf .sdf`.t" echo do: $cmd ... $cmd done sdf-2.001/t/TEST010075500042570001753000000016540647270244200131030ustar00iancmtr00000400000236#!/usr/local/bin/perl # This script is run Test::Harness on the tests found under the # "t" directory. # First we check if we already are within the "t" directory unless (-d "general") { # try to move into test directory chdir "t" or die "Can't chdir: $!"; # fix all relative library locations foreach (@INC) { $_ = "../$_" unless m,^/,; } } # Pick up the library files from the ../blib directory unshift(@INC, "../../blib/lib", "../../blib/arch"); #print "@INC\n"; use Test::Harness; $Test::Harness::switches = ""; $Test::Harness::verbose = shift if $ARGV[0] =~ /^\d+$/ || $ARGV[0] eq "-v"; #$Test::Harness::verbose = 1; if (@ARGV) { for (@ARGV) { if (-d $_) { push(@tests, <$_/*.t>); } else { $_ .= ".t" unless /\.t$/; push(@tests, $_); } } } else { @tests = (, , ); } #print STDERR join("|", "tests=", @tests, "\n"); runtests @tests; (@INC, "../../blib/lib", "../../blib/arch"); #print "@INC\n"; use Test::Harness; $sdf-2.001/t/html/004075500042570001753000000000000672243774000133435ustar00iancmtr00000400000236sdf-2.001/t/html/lists.sdf010064400042570001753000000007230622022557200151650ustar00iancmtr00000400000236H2: Plain After Ordered ^ 1a . 1b . 1c + 1d H2: Plain after Unordered * 1a . 1b . 1c * 1d H2: Mixed At the Same Level ^ 1a * 1b * 1c + 1d H2: Plain Indent > 1 . 1aaaaaaaaaaaaaaaaaaaaa ... 3aaaaaaaaaaaaaaaaaaaaa .. 2aaaaaaaaaaaaaaaaaaaaa H2: Ordered Indent > 1 ^ 1a ^^^ 3a ^^ 2a ++ 2b + 1b H2: Unordered Indent > 1 * 1a *** 3a ** 2a H2: Ordered With Starting Indent > 1 ^^^ 3a ^^ 2a ++ 2b ^ 1a H2: Mixed With Starting Indent > 1 ... 3a ^^ 2a ++ 2b * 1a sdf-2.001/t/html/lists.t010064400042570001753000000000300647265372200146560ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/html/checked/004075500042570001753000000000000672243774000147315ustar00iancmtr00000400000236sdf-2.001/t/html/checked/lists.html010064400042570001753000000036310622022557200167440ustar00iancmtr00000400000236

Table of Contents

Plain After Ordered

  1. 1a
    1b
    1c
  2. 1d

Plain after Unordered

  • 1a
    1b
    1c
  • 1d

Mixed At the Same Level

  1. 1a
  • 1b
  • 1c
  1. 1d

Plain Indent > 1

    1aaaaaaaaaaaaaaaaaaaaa
        3aaaaaaaaaaaaaaaaaaaaa

      2aaaaaaaaaaaaaaaaaaaaa

Ordered Indent > 1

  1. 1a
      1. 3a
    1. 2a
    2. 2b
  2. 1b

Unordered Indent > 1

  • 1a
      • 3a
    • 2a

Ordered With Starting Indent > 1

      1. 3a
    1. 2a
    2. 2b
  1. 1a

Mixed With Starting Indent > 1

        3a
    1. 2a
    1. 2b
  • 1a
sdf-2.001/t/doatest.templ010064400042570001753000000000300647265275600151030ustar00iancmtr00000400000236require './doatest.pl'; sdf-2.001/t/sdftest.bat010064400042570001753000000036250661473075300145460ustar00iancmtr00000400000236@echo off cd general echo TESTING GENERAL STUFF ... call sdf -2raw -.test expr.sdf call sdf -2raw -.test formats.sdf call sdf -2raw -.test lineno.sdf call sdf -2raw -.test macro.sdf call sdf -2raw -.test para1.sdf call sdf -2raw -.test para2.sdf call sdf -2raw -.test phrase.sdf call sdf -2raw -.test zero.sdf cd ..\macro echo TESTING MACROS ... call sdf -2raw -.test block.sdf call sdf -2raw -.test catalog.sdf call sdf -2raw -.test cell.sdf call sdf -2raw -.test class.sdf call sdf -2raw -.test default.sdf call sdf -2raw -.test define.sdf call sdf -2raw -.test else.sdf call sdf -2raw -.test elsif.sdf call sdf -2raw -.test endblock.sdf call sdf -2raw -.test endif.sdf call sdf -2raw -.test endmacro.sdf call sdf -2raw -.test endtable.sdf call sdf -2raw -.test execute.sdf call sdf -2raw -.test export.sdf call sdf -2raw -.test if.sdf call sdf -2raw -.test include.sdf rem call sdf -2raw -.test inherit.sdf call sdf -2raw -.test init.sdf call sdf -2raw -.test insert.sdf call sdf -2raw -.test line.sdf call sdf -2raw -.test macro.sdf call sdf -2raw -.test on_para.sdf call sdf -2raw -.test on_phras.sdf call sdf -2raw -.test row.sdf call sdf -2raw -.test slide.sdf call sdf -2raw -.test table.sdf call sdf -2raw -.test undef.sdf cd ..\filter echo TESTING FILTERS ... call sdf -2raw -.test about.sdf call sdf -2raw -.test address.sdf call sdf -2raw -.test appendix.sdf call sdf -2raw -.test comment.sdf call sdf -2raw -.test default.sdf call sdf -2raw -.test define.sdf call sdf -2raw -.test end.sdf call sdf -2raw -.test example.sdf call sdf -2raw -.test front.sdf call sdf -2raw -.test inline.sdf call sdf -2raw -.test parastyl.sdf call sdf -2raw -.test plain.sdf call sdf -2raw -.test script.sdf call sdf -2raw -.test sdf.sdf call sdf -2raw -.test table.sdf cd .. echo If any tests failed, the unexpected .out or .log file echo can be found in t\general, t\macro or t\filter. sdf-2.001/t/sdftest010075500042570001753000000020230672214562300137670ustar00iancmtr00000400000236#!/bin/sh # $Id$ # # >>Title:: Execute Regression Tests # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 29-Feb-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # sdf="sdf" #sdf="$1 -I../../blib/lib ../../blib/script/sdf" echo "Using '$sdf' for the tests" cd general echo "TESTING GENERAL STUFF ..." $sdf -2raw -.test *.sdf cd ../macro echo "TESTING MACROS ..." $sdf -2raw -.test *.sdf cd ../filter echo "TESTING FILTERS ..." $sdf -2raw -.test *.sdf cd ../.. echo "SUMMARY:" bad=`/bin/ls t/*/*.out t/*/*.log 2>/dev/null | wc -l` if [ $bad -eq 0 ] then echo "All tests passed." exit 0 else echo "$bad test(s) failed." echo "" echo "The unexpected .out or .log file(s), can be found in" echo "test/general, test/macro and/or test/filter." exit 1 fi sdf-2.001/t/doatest.pl010064400042570001753000000007100647270004400143620ustar00iancmtr00000400000236print "1..2\n"; my $path = $0; $path =~ m|([^/\\]+)\.t$|; my $name = $1; my $file = "$1.sdf"; $path =~ m|^(.*[/\\]+)|; my $dir = $1; ## sdf below should at least output something like that: ## print "not" if -x "$name.log"; ## print "ok 1\n"; ## print "not" if -x "$name.out"; ## print "ok 2\n"; ## could not be done after the require because sdf calls ## exit; chdir $dir; @ARGV = ( '-2raw', '-.test=1', $name); require '../../blib/script/sdf'; 1; sdf-2.001/bin/004075500042570001753000000000000672243775100127065ustar00iancmtr00000400000236sdf-2.001/bin/mif2rtf010075500042570001753000002632150647623217200142070ustar00iancmtr00000400000236#!/usr/local/bin/perl # -*- mode:perl -*- # $Id$ # # mif2rtf - Frame Maker Interchange Format to Microsoft Rich Text Format # # Available from: # ftp.mincom.com:/pub/mtr/sdf/mif2rtf/ # # Original version available from: # ftp.irisa.fr:/pub/FrameMaker/Filters/ # # The original code has been significantly reworked in the area of # hypertext construct handling with the aim of being able to generate # Microsoft Windows Help files from FrameMaker documents # # This program can be used to generate reasonable Microsoft Windows # Help files. # # Any feedback on this code should be initially directed to tjh@mincom.com # # Parts of this program are: # Copyright 1992 by Convex Computer Corporation, Richardson, Texas. # # (see the full COPYRIGHT notice further down in the file for details of # the copyright restrictions that were part of the original version and # hence effect this derivative) # # Tim Hudson # tjh@mincom.com # # # 19-Feb-97 ianc fixed (r) and (c) characters # 02-Feb-97 ianc TOCTEXT/TOCGRAPHIC -> TOC_TITLE/TOC_GRAPHIC # 30-Dec-96 tjh center pictures ... controlled by Align=Center # ..................... in the IMPORT statement under SDF # 18-Nov-96 tjh unfortunately had to change this code for perl5.001 # ..................... so Ian is no longer the last to touch the code # 05-Aug-96 ianc changed TOC detection to use marker 11, not 9 # 30-May-96 tjh "fixed" the 23-May-96 "fix" :-) # 23-May-96 ianc "fixed" jumps to topics within another file # 09-May-96 tjh yet another bug in context stuff fixed + get # ..................... size and font changes toggling correct too # 19-Apr-96 tjh get TOC stuff right when user has specified # ..................... the name of the topic # 16-Apr-96 tjh grab title and toc text from vars # 16-Apr-96 tjh fixed up to handle TOC and HELPTOC as XRefName # ..................... which got introduced in SDF2B3? # 03-Apr-96 tjh more rework for better HLP output (Delphi-style) # 26-Mar-96 tjh Color support added ... plus SDF2 stuff # 25-Mar-96 tjh PgfNumFormat support added (and lots of other changes) # 25-Mar-96 tjh changed things to handle SDF mif input # ..................... better without having to go via FrameMaker # 15-Dec-95 craigw Modified the Hypertext markup sections, convert_table # ..................... & convert_picture # 29-Jul-95 tjh windows help output make useful ... generate # ..................... the right footnotes for all the hypertext stuff # 11-Jun-95 tjh added in the "tjh" stuff to enable better # ..................... handling of documents with hypertext links # ..................... in them as the first step in being able to # ..................... generate RTF for WinHelp purposes # # Tim Hudson - tjh@mincom.com # Craig Willis - craigw@mincom.com # # With bug fixes by: # Ian Clatworthy - ianc@mincom.com # output of # indicates loaded in a MIF statement # output of . indicates processed a MIF statement into RTF for output # HELP FOOTNOTES: # * - build tag # # - context string (jump to with \v id) # $ - topic title [one only] # + - browse sequence [one only] # K - keywords (; separated) # ! - help macro # other - alternate keyword ... see HELP_MULTIKEY for details # variables for controlling some of the current under-development stuff # which will move to a more standard location $pgfnumdebug=0; $tmpdebug=0; $sdfvartrace=0; $quiet=1; $rtfdebug=0; $fullcatalog=1; #------------------------------------------------------------------------------ # NOTES ... to be removed shortly ... perhaps into documentation for # this stuff --tjh #------------------------------------------------------------------------------ # # FrameMaker -> PgfSpBefore, PgfSpAfter are handled specially inside # Tables ... and differently to MSWord et al # # PgfPlacement -> !AnyWhere means start topic # PgfNumFormat -> can be in a Para # PgfNumString -> if not there then use PgfNumFormat information # FTag -> Italic, Bold, Blank => weight, angle # # MORE TJH NOTES: (25-Jan-96) # - duplicate stuff controlled via # - escape [] in context ids # - handle backslashes correctly # - handle curlybraces correctly # - fix convert_marker to turn jump into valid id ... had spaces etc # - added convert_context and changed everything to reference # this as it was messy how I originally did this and I needed # to escape more chars ... \{} # # The following will have to be sorted out too ... reference to paragraph # format names needs thinking about # $heading=($curtag =~ /^h[1]_Heading\b/); # if ( $State{'PgfTag'} eq 'tt_TableTitle' ) { # push(@r, "\n$PgfCatalog{'Style',b0_Body} ... # if ( $curtag eq "dn_DocName" && $DocName eq "" ) { # + references to dn_DocName in a few other places too! # if ( $State{'PgfTag'} eq 'tt_TableTitle' ) { # # TJH NOTES: (20-Jan-96) # - *never* use `date` as it will not work under DOS (see my # usage of ctime() for the "portable" way of doing things) # - don't output title line if there isn't one in the document # - Copyright should only be output if its there (rather than Pty Ltd) # - spacing in TOC was too large ... whitespace should be used # *sparingly* in HELP FILES # - fixed rtf_dimensions to handle whitespace gracefully # - typo for VariableName (was VarialbeName) # - using b0_Body as the style name in TOC is non-portable! # - twip conversion for tabs had too much space for left margin # - paragraph style and tabs for TOC need to be kept so that # we get indented reasonable looking TOC from default stuff # # #------------------------------------------------------------------------------ # HELP INFORMATION ... to be expanded #------------------------------------------------------------------------------ #> If -ftoc=n is used, it will produce a Table of Contents if hypertexting # # USE # -o [out file] Output file # -c [Copyright] Copyright message for WINHELP file # -d turn on debugging # -info TAG GROUP Put all text from TAG paragraphs into info group GROUP # -v Verbose Mode # -m [style] If style = help, use Hypertext, else create only RTF # -win [x,y,width,height] (x,y) co-ordinates, Width & Height on Help Window # Input File (MIF File) # # If -win, (x,y,width,height) must be supplied or an error will occur # # Notes: # Output of keep has been blatted in most cases as this is # not wanted with help? # The usage of -m help will generate a Help Project File (.hpj) based # on the name of the output file. The output file always has an # extension presumed to be ".rtf". The ".hpj" file is a standard file # that can be easily manipulated for specific purposes. A Table of Contents # will be generated if there is marker type of 11 and hypertext is being # generated. # # The following is the original text contained in the version that I started # with as the base for this much improved mif2rtf filter --tjh # # The changes that I have made have only one restriction ... you cannot # pretend that you wrote them and the comment blocks in the source file # must be left intact. # # Note: I have not updated any of the text in the block below ... lots of # the BUGS noted have been fixed. # # Tim Hudson # tjh@mincom.com # #------------------------------------------------------------------------------ # Code marked @@ needs fixing. # Code marked @# is an improvisation # Code marked HEURISTIC is not exact. # # COPYRIGHT # # Copyright 1992 by Convex Computer Corporation, Richardson, Texas. # # All Rights Reserved # # Permission to use, copy, modify, and distribute this software and its # documentation for any purpose and without fee is hereby granted, # provided that the above copyright notice appear in all copies and that # both that copyright notice and this permission notice appear in # supporting documentation, and that the name Convex not be # used in advertising or publicity pertaining to distribution of the # software without specific, written prior permission. # # CONVEX DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING # ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL # CONVEX BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR # ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, # WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, # ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS # SOFTWARE. # # BUGS # # @#Footnote paragraph formats not right # @#should convert page margins (frame BRect->margr etc.) # @#No way to make TOC entries # @#master pages # @# Not all document, section, or table properties are converted. # @#Hard problems: reference page items # Maybe use command line options for those. # @# LineSpacing doesn't translate # # IDEAS # absolute positioned object: frame brect etc. # #------------------------------------------------------------------------------ require 'ctime.pl'; # for date $winhelp=1; # this controls the handling of certain constructs that # are *naughty* in the context of windows help files $fixup_duplicates=0; $hyper_debug=0; $lots_of_whitespace=0; $tjh_xref_debug=0; $use_numformat=1; # switch off if you don't want section numbers in the # output (which is handy for matching the paper document # but may be irritating to some users) local($stmt_call_level); local(%SDFVAR,$USER_WH_topic,$USER_WH_context); local($done_pagebreak); local(%SavedState); local(%doc_defaults); local(%char_defaults); local(%para_defaults); # convert_paragraph() uses delayed_text to pass information that # is added using the auto-paragraph header prefix (PgfNumFormat,PgfNumString) # into convert_paraline() ... such that it stays with the text and # is not left dangling when hypertext things are inserted local($delayed_text); %skiptags = ( "dd_DocDistr",1, "dp_DocProject",1, "dn_DocName",1, "dt_DocType",1, "ds_DocStatus",1, "dc_DocCode",1, "dk_DocSkip",1, "da_DocAction",1, "du_DocAuthor",1, "dw_DocWho",1, # To remove the table of contents stuff ... which # is required to drop the TOC page for Windows Help # file generation --tjh "fh_FrontHeading",1, "h1_HeadingTOC",1, "h2_HeadingTOC",1, "h3_HeadingTOC",1, "h4_HeadingTOC",1, ); $OutputFile=''; $Usage = " $0 -o [out file] Output file -c [Copyright] Copyright message for WINHELP file -d turn on debugging -info TAG GROUP Put all text from TAG paragraphs into info group GROUP -v Verbose Mode -m [style] Determines Output style, help - Hypertext -win [x,y,width,height] (x,y) co-ordinates, Width & Height on Help Window Input File "; ######### # # main # # # %TagGroup maps MIF paragraph tags to RTF info groups # %RTFInfo holds the text of the RTF info groups # so that after &convert_pages(), # $RTFInfo{$TagGroup{pgftag}} contains all text tagged pgftag # # @@ idea: extend this to character tags # local($Debug, %TagGroup ); @ARGV = &parse_args(@ARGV); if ($OutputFile ne '' ) { open (OUTPUT,">$OutputFile") || die "Failed to open $OutputFile"; } #local($Date) = `date`; local($Date) = &ctime(time); &Verbose("Program: $0\nDate : ${Date}Input : @ARGV\nOutput : $OutputFile"); # # %State maps MIF and RTF codes to their current settings # local(%State, %CharacterConversions ); local( $paragraph_count, $browse_seqno); &initialize_state(); &debug( "initialize_state done"); local($Document, # $Document is the RTF code to get from the default # document format to what's in %State # NOTE: some MIF document attrs are RTF Section attrs # ASSUME: MIF document defaults are RTF defaults %Typeface, $Typeface, # %Typeface maps FFamilys to RTF font numbers %Tag, $Tag, # %Tag maps PgfTags to RTF style numbers %PgfCatalog, %FontCatalog, @BodyPage, %TextRect, %TextFlow, %AFrame, %Tbl ); #> Local Variables Used globally internally local( $DocName, $PgfAutoNum, $Xref_TOC); # This is the default in Frame, but not in Word. $Document = "\\widowctrl\\ftnbj\\cvmme\\sprsspbf\\brkfrm\\swpdr\\noextraspl". "\\hypcaps0"; #> CRW Modified from standard RTF file local($PageType, $TextRectID, $ID, $TblID, $XRefName, $VaraibleName); &read_whole_file ('DPageSize', '$Document .= &change_dims($data, "paperw", "paperh")', 'DStartPage', '$Document .= &change_attr("pgnstarts", $data)', 'DPageNumStyle', '$Document .= &select_attr($data, "PageNumStyle", "Arabic", "pgndec", "UCRoman", "pgnucrm", "LCRoman", "pgnlcrm", "UCALpha", "pgnucltr", "LCAlpha", "pgnlcltr")', 'DTwoSides', '$Document .= &change_attr("facingp", 1)', 'DFNoteRestart', '$Document .= &select_attr($data, "FNoteRestart", "PerPage", "ftnrestart")', 'DFNoteStartNum', '$Document .= &change_attr("fntstart", $data)', 'DAutoChBars', '$Document .= &change_attr("revisions", 1)', 'FFamily', '&intern(*Typeface, $data)', 'PgfTag', '&intern(*Tag, $data); ', 'PgfCatalog', '&convert_paragraph_catalog($here)', 'FontCatalog', '&convert_character_catalog($here)', 'PageType', '$PageType = $data', 'Page', ' push(@BodyPage, $here) if $PageType eq "BodyPage"; &debug("$PageType $here"); ', 'TextRectID', '$TextRectID ? &debug("Extra TextRect: $data") : ($TextRectID = $data)', 'TextFlow', '@TextRect{$TextRectID} = $here; &debug("flow", %TextRect); $TextRectID = ""', 'Frame', '$AFrame{&data_search($here, "ID", 1)} = $here', 'TblID', '$TblID = $data', 'Tbl', '$Tbl{$TblID} = $here', 'XRefName', '$XRefName = &convert_string($data)', 'XRefDef', '$Definition{"XRef", $XRefName} = $data; $Definition{"XRefPgfTag", $XRefName} = $State{\'PgfTag\'}; print STDERR "XRef $XRefName ($data) => $State{\'PgfTag\'}\n" if ($tjh_xref_debug); ', 'VariableName', '$VariableName = &convert_string($data)', 'VariableDef', '$Definition{"Variable", $VariableName} = $data' ); if ( $OutputFile ne '' ) { $Output = "OUTPUT"; } else { $Output = "STDOUT"; } print $Output &rtf_begin_doc; print $Output &rtf_font_table(%Typeface); if (0) { print $Output &rtf_color_table(('0 0 0', # These are Frame's colors '0 0 255', '0 255 255', '0 255 0', '255 0 255', '255 255 0', '255 255 255', '0 0 128', '0 128 128', '0 128 0', '128 0 128', '128 0 0', '128 128 0', '128 128 128', '192 192 192')); } else { # # Frame4 Colors are the following ... # Black, White, Red, Green, Blue, Cyan, Magenta, Yellow # print $Output &rtf_color_table(('0 0 0', # Black '255 255 255', # White '255 0 0', # Red '0 255 0', # Green '0 0 255', # Blue '0 255 255', # Cyan '255 0 255', # Magenta '255 255 0' # Yellow )); } print $Output $Document, "\n"; &debug("body pages: ", @BodyPage); local(@Document, $cnt); foreach $page (@BodyPage){ &debug("converting page:\n", &expand_mif_statement($page)); push(@Document, &convert_frame($page)); } if ( !defined($StyleSheet) || $StyleSheet) { print $Output &rtf_style_sheet(%Tag); } print $Output &rtf_info(%RTFInfo); print $Output @Document; print $Output &rtf_end_doc; # when debugging the hypertext stuff it is nice to be able to # output the map table directly ... might have a dinky flag for # doing this too ... if ( $hypertext_sw ) { foreach ( keys(%Context_ID)) { &debug(sprintf("%-30s %010d ; $WH_topic_comments{$_}\n", $WH_context_ids{$_}, $_)); } } print STDERR "\n"; # after all the .....'s if ( $hypertext_sw ne '' ) { local($cnt); close $Output; $ErrFile = $HPJFile = $OutputFile; $ErrFile =~ s/\.\w+$/\.err/; $HPJFile =~ s/\.\w+$/\.hpj/; open (OUTPUT,">$HPJFile") || die "open $HPJFile"; print OUTPUT "[OPTIONS]\n"; if ( scalar(@Bmroot) ) { print OUTPUT "BMROOT="; foreach (@Bmroot) { print $_ eq "$Bmroot[0]" ? "" : ":" ; print $_; } print OUTPUT "\n"; } # pick up the title from the new variable that holds this # information if (defined $Definition{"Variable", "DOC_TITLE"} ) { $DocName = &convert_string($Definition{"Variable", "DOC_TITLE"}); } # print OUTPUT "COMPRESS=ON\n"; print OUTPUT "COMPRESS=OFF\n"; print OUTPUT "COPYRIGHT=$Copyright\n" if ($Copyright ne ""); # print OUTPUT "CITATION=\n"; print OUTPUT "ERRORLOG=$ErrFile\n"; # print OUTPUT "ICON=\n"; print OUTPUT "OLDKEYPHRASE=NO\n"; print OUTPUT "REPORT=ON\n"; print OUTPUT "TITLE=$DocName\n" if ($DocName ne ""); print OUTPUT "WARNING=3\n"; # let individual options be set as variables # that make their way into the options section of the # output file foreach $key (keys %Definition) { ($defn,$var)=split($;,$key,2); #print STDERR "DEFN $defn VAR $var\n"; next unless $defn eq "Variable"; $val=&convert_string($Definition{"Variable",$var}); #print STDERR "VAR $var VALUE $val\n"; if ($var =~ /^HLP_OPTIONS_/) { $name = $var; $name =~ s/^HLP_OPTIONS_//; #print STDERR "OPTION $name = $val\n"; print OUTPUT "$name=$val\n"; } } print OUTPUT "\n[FILES]\n"; print OUTPUT "$OutputFile\n"; print OUTPUT "\n[CONFIG]\n"; # grab HLP_CONFIG as a filename variable that is read in # TODO ... print OUTPUT "BrowseButtons()\n"; print OUTPUT "\n[WINDOWS]\n"; if ($yellow_muck) { print OUTPUT "main=,($xcoordinate,$ycoordinate,$win_width,$win_height)". ",,,(255,255,0)\n"; } else { # leave the window stuff out! #print OUTPUT "main=,($xcoordinate,$ycoordinate,$win_width,$win_height)". ",,,\n"; } print OUTPUT "\n[MAP]\n"; foreach (keys (%WH_context_ids)) { print OUTPUT sprintf("%-30s %10d ; $WH_topic_comments{$_}\n", $WH_context_ids{$_}, $_); } } ##################### END OF MAIN PROGRAM #################################### # ##################### SUBROUTINES START #################################### # # USE : @ARGV = &parse_args(@ARGV); # SETS: $Debug, %TagGroup # sub parse_args{ local(@files, $style, $win_sw); while($_ = shift){ if(/^-c/){ # Copyright option $Copyright = shift; } elsif(/^-d/){ $Debug = 'debug'; } elsif(/^-hd/){ $hyper_debug = '1'; } elsif(/^-info/){ $TagGroup{shift} = shift; } elsif(/^-h[elp]/){ print "\nUsage: $Usage\n"; exit(0); } elsif(/^-m/){ $style = shift; if ( $style =~ /HELP/i ) { $hypertext_sw = 1 }; } elsif(/^-nostyles/){ $StyleSheet = 0; } elsif(/^-o/){ $OutputFile = shift; } elsif(/^-v/){ $vbs_sw = 1; } elsif(/^-win/) { # Windows co-ordinates $win_sw++; ($xcoordinate,$ycoordinate,$win_width, $win_height) = split(/,/, shift,4); } else{ push(@files, $_); } } if ( scalar(@files) == 0 ) { die "No Input file supplied\n"; } if ( $hypertext_sw && $OutputFile eq "" ) { die "Output file is mandatory with help option\n" ; } if ( $win_sw ) { if ( !$xcoordinate || !$ycoordinate || !$win_width|| !$win_height) { die "You need to supply x & y co-ordinates & window height & width\n"; } } else { $xcoordinate = 496; $ycoordinate = 128; $win_width = 512; $win_height = 768; } @files; } # # ########## # Mif Parsing Routines # # I've finally found a perl representation of a mif file that I'm happy with. # It's pretty memory intensive and not real zippy, but that's the nature # of the beast with MIF. # sub read_whole_file{ local(%Callbacks) = @_; # global(@Parts); @Parts = (0); # put one element in it so there's no statement 0. while(&read_mif_statement()) { print STDERR "#\n" unless ($quiet); } } # # Returns an index in @Parts so that # $Parts[$index] is the statement type # and @Parts[$index+1, $index+2, ...] are the parts of the statement. # For compound statement, @Parts[$index, ...] looks like # ('<', token, index1, index2, index3, ...) # where indexN are the substatements # # for each statment, $Callbacks{$token} is evaluated # with $token, $data, and $here set # sub read_mif_statement{ local($_, $type, $token, $data, @parts, $here, $line); # global(@Parts); while(<>){ $line = $.; $type = '<>', $token = $1, $data = $2, last if /^\s*<(\w+)\s+(.*\S)?\s*>/; $type = '<', $token = $1, last if /^\s*<(\w+)/; return 0 if /^\s*>/; $type = '=', $token = $1, $data = &read_mif_inset(), last if /^=(\w+)/; print STDERR "#\n" if (0); } &debug("LINE=$line $_ type=$type token=$token data=$data"); return 0 unless $type; local($callback); if($type eq '<>' || $type eq '='){ $here = $#Parts+1; push (@Parts, $type, $token, $data); eval $callback if $callback = $Callbacks{$token}; die "$@ $callback" if $@; } else{ while ($_ = &read_mif_statement()) { push(@parts, $_); } $here = $#Parts+1; push(@Parts, '<', $token, @parts); eval $callback if $callback = $Callbacks{$token}; die "$@ $callback" if $@; } $Lines{$here} = $line; # for debugging purposes $here; } # # Read until a line starts with "=EndInset" # and return all the lines concatenated # sub read_mif_inset{ local($inset); while(<>){ $inset .= $_; last if /^=EndInset/; } $inset; } sub new_statement{ local($s) = $#Parts + 1; push(@Parts, @_); return $s; } sub type{ $Parts[$_[0]]; } sub token{ $Parts[$_[0]+1]; } sub data{ $Parts[$_[0]+2]; } sub parts{ local($i) = @_; if(&type($_[0]) eq '<'){ local($s) = $i+2; for(; $Parts[$s] > 0; $s++){ } return @Parts[$i+2 .. $s-1]; }else{ return @Parts[$i+2]; #data } } # Dump the context of the MIF statement ... such that it is easier # to figure out information about where an error has occured ... the # original stuff was a little hairy in this area too --tjh # TODO: compare this with expand_mif_statement() sub DUMP_CONTEXT { local($__s) = @_; local($here,$exp); foreach $here (&parts($__s)){ local($type) = &type($here); local($token) = &token($here); local($data) = &data($here); # exp has newline in it! $exp=&expand_mif_statement($here,"EXP: "); print STDERR "[$here]:$type:$token:$data || $exp"; } } sub do_statement{ # global(@Parts); local($__s, %__callbacks) = @_; local($here, $__cb); # one level deeper in the do_statement call stack $stmt_call_level++; foreach $here (&parts($__s)){ local($token) = &token($here); local($data) = &data($here); $stmt_call_level_context{"$stmt_call_level"}=$here; eval $__cb if $__cb = $__callbacks{$token}; warn "Error executing: $__cb \n-->$@" if $@; warn "DEBUG: statement=$__s token=$token data=$data here=$here parts=". &parts($__s) . "line:", $Lines{$here} if (0); if ((&type($here) ne '<>') && !$__cb) { warn "IGNORED: statement=$__s token=$token data=$data here=$here ". "parts=" . &parts($__s) . "line:" , $Lines{$here}; # TJH ADDITION print STDERR "HERE:\n"; &DUMP_CONTEXT($here); print STDERR "STMT:\n"; &DUMP_CONTEXT($__s); # print STDERR "PARENT:\n"; # &DUMP_CONTEXT($stmt_call_level_context{$stmt_call_level-1}); } # TJH took this out # &assert('$token =~ /\w+/'); } # returning from one level down ... $stmt_call_level--; } sub expand_mif_statement{ # global(@Parts); local($i, $leader) = @_; local($_) = &type($i); if($_ eq '<>'){ return (sprintf("%s<%s %s>\n", $leader, @Parts[$i+1, $i+2])); }elsif($_ eq '='){ return (sprintf("=%s\n%s", @Parts[$i+1, $i+2])); }elsif($_ eq '<'){ local(@lines); @lines = (sprintf("%s<%s\n", $leader, &token($i))); foreach (&parts($i)){ #TJH#push (@lines, &expand_mif_statement($_, " $leader")); push (@lines, &expand_mif_statement($_, "$leader ")); } push(@lines, "$leader>\n"); return @lines; } } # # use $tag = &data_search($para, 'PgfTag', 2) # to search 2 levels of the $para statement, # and return the data of the first PgfTag statement found. # sub data_search{ local($s, $t, $levels) = @_; foreach (&parts($s)){ if(&type($_) eq '<'){ if($levels>1){ $s = &data_search($_, $t, $levels-1); return $s if $s ne ''; } }else{ return &data($_) if &token($_) eq $t; } } return ''; } # # use &token_search($compound_statement, "token", 3) # to search the next three levels of hairy_statement for # "token" statements. # sub token_search{ local($s, $t, $levels) = @_; local(@matches, $_); foreach (&parts($s)){ push(@matches, $_) if &token($_) eq $t; push(@matches, &token_search($_, $t, $levels-1)) if &type($_) eq '<' && $levels>1; } return @matches; } # # ######## # %State manipulation # sub change_attr{ local($attr, $val) = @_; &debug("change attr: $attr ($State{$attr}) -> [$val]"); $State{$attr} = $val , return "\\$attr$val " unless $State{$attr} eq $val; ''; } sub change_dims{ local($dims, @attrs) = @_; local($_, $r); foreach (&rtf_dimensions($dims)){ local($attr) = shift(@attrs); last unless $attr; $attr =~ s-/(\d+)-- && ($_ = int($_/$1)); #HACK $r .= &change_attr($attr, $_); } #print STDERR "change_dims $dims->$r\n"; $r; } sub select_attr{ local($key, $s, %attrs) = @_; if($attrs{$key}){ &debug("select attr: '$s=$key' from ", join(",", %attrs)), $State{$s} = $attrs{$key}, return "\\$attrs{$key} " unless $State{$s} eq $attrs{$key}; } $State{$s} = ''; } ############# # # Conversions # sub convert_paragraph_catalog{ local($s) = @_; #global(%State, %PgfCatalog); local($tag); &do_statement($s, 'Pgf', ' $tag = &convert_string(&data_search($here, "PgfTag")); $PgfCatalog{"Statement", $tag} = $here; # for a full catalog we want conversion now! if ($fullcatalog) { &change_style($tag); } ' ); } # convert a freeform string into a "safe" context id for # the purposes of Windows Help sub convert_context { local($s)=@_; $s =~ s/[#, ._\/\-><()?&\[\]\\{}+'`~:]//g; ##print STDERR "FROM: @_ to $s\n"; return $s; } sub convert_character_catalog{ local($s) = @_; #global(%State, %FontCatalog); local($tag); &do_statement($s,'Font', ' $tag = &convert_string(&data_search($here, "FTag")); $FontCatalog{"Statement", $tag} = $here;' ); } # # Returns RTF to change from what's in %State to what's in $s # EXCEPT TABS! use ¤t_tabs() to get them. # sub convert_pgf_format{ local($s) = @_; local($rtf, $_); local($lindent) = &data_search($s, 'PgfLIndent'); local($li); if ($lindent gt ''){ print STDERR "LINDENT: $lindent\n" if ($tmpdebug); ($li) = &rtf_dimensions($lindent); $State{'LIndent'}=$lindent; } else{ ($li) = &rtf_dimensions($State{'LIndent'}); } local($findent) = &data_search($s, 'PgfFIndent'); local($fi); if ($findent gt ''){ ($fi) = &rtf_dimensions($findent); $State{'FIndent'}=$findent; } else{ ($fi) = &rtf_dimensions($State{'FIndent'}); } $rtf .= &change_attr("fi", $fi - $li); $rtf .= &change_attr("li", $li); &debug("findent: $findent fi: $fi lindent: $findent li: $li"); &do_statement ($s, 'PgfNumberFont', '$State{"NumberFont"} = &convert_string($data)', 'PgfNumFormat', '$State{"NumFormat"} = &convert_string($data, $State{"Family"} ne "Symbol");', 'PgfNextTag', '$rtf .= &change_attr("snext", &intern(*Tag, $data))', 'PgfNumTabs', 'undef($State{"TabStops"})', 'TabStop', '0 && &TabStop($here)', 'PgfAlignment', '$rtf .= &select_attr($data, "Alignment", "Left", "ql", "Center", "qc", "Right", "qr", "LeftRight", "qj")', # RTF & MIF are different about tabs and first indents 'PgfRIndent', '$rtf .= &change_dims($data, "ri")', 'PgfTopSeparator', '$rtf .= &change_attr("brdrt", 1) if $data ne "`\'"', #@# 'PgfBotSeparator', '$rtf .= &change_attr("brdrb", 1) if $data ne "`\'"', #@# #TJHNEW# 'PgfPlacement', ' $State{"Placement"} = &convert_string($data); if ($winhelp) { # look at for not Anywhere as TOPIC start trigger if ( $State{"Placement"} ne "Anywhere" ) { $State{"NEWTOPIC"} = 1; } else { $State{"NEWTOPIC"} = 0; } } else { $rtf .= &select_attr($data, "Placement", "ColumnTop", "pagebb", "PageTop", "pagebb", "LPageTop", "pagebb", "RPageTop", "pagebb"); } ', 'PgfSpBefore', '$State{"SpBefore"} = &change_dims($data,"sb")', 'PgfSpAfter', '$State{"SpAfter"} = &change_dims($data,"sa")', #@# withprev ##TJH-WINHELP-no keepn0 'PgfWithNext', ' if (!$winhelp) { $rtf .= &select_attr($data, "WithNext","Yes", "keepn", "No", "keepn0") } ', ##TJH-WINHELP-no keep1 'PgfBlockSize', ' if (!winhelp) { $rtf .= &change_attr("keep", 1) unless $data <2 }', 'PgfLeading', '$rtf .= &change_dims($data, "sl")', 'PgfFont', '$rtf .= &convert_char_format($here)' ); &debug("converted $State{'PgfTag'} -> $rtf"); $rtf; } sub TabStop { local($s) = @_; #@# tab alignment ignored! $State{'TabStops'} .= " " . &data_search($s, 'TSX'); } sub convert_char_format{ local($rtf); &do_statement ($_[0], 'FFamily', '$State{"Family"} = &convert_string($data); $rtf .= &change_attr("f", &intern(*Typeface, $data))', #@# 'FVar', 'warn "IGNORED: Variation $data" unless $data =~ /regular/i', ##TJHNEW## # FTag can also be used to set the font to Italic or Bold or # also to reset both of these back to "normal" 'FTag', ' $str=&convert_string($data); $rtf .= &handle_font_change($str); ', 'FColor', '$rtf .= &select_attr(&convert_string($data),"Color", "Black", "cf0", "White", "cf1", "Red", "cf2", "Green", "cf3", "Blue", "cf4", "Cyan", "cf5", "Magenta", "cf6", "Yellow", "cf7", "", "cf0" )', 'FWeight', '$rtf .= &select_attr(&convert_string($data),"Weight", "Bold", "b", "Regular", "b0")', 'FAngle', '$rtf .= &select_attr(&convert_string($data), "Angle", "Italic", "i", "Oblique", "i2", "Regular", "i0")', 'FSize', '$State{"fs"}=$data; $rtf .= &change_dims($data, "fs/10")', 'FUnderline', '$rtf .= &select_attr($data, "Underline", "Yes", "ul", "No", "ulnone")', 'FStrike', '$rtf .= &select_attr($data, "Strike", "Yes", "strike", "No", "strike0")', 'FSupScript', '$rtf .= &select_attr($data, "SupScript", "Yes", "up6", "No", "up0")', 'FSubScript', '$rtf .= &select_attr($data, "SubScript", "Yes", "dn6", "No", "dn0")', 'FChangeBar', '$rtf .= &select_attr($data, "ChangeBar", "Yes", "revised", "No", "revised0")', 'FOutline', '$rtf .= &select_attr($data, "Outline", "Yes", "outl", "No", "outl0")', 'FShadow', '$rtf .= &select_attr($data, "Shadow", "Yes", "shad", "No", "shad0")', 'FSeparation', '$rtf .= &change_attr("cf", $data)' ); &debug("char format: $rtf"); ### print STDERR "convert_char_format: Weight $State{'Weight'} Angle $State{'Angle'}\n"; $rtf; } ######## sub convert_frame{ local($s) = @_; #@@ local(@BRect) = @BRect; local(@ret); local($align,$oldalign)=0; &debug("convert frame: $s"); &do_statement ($s, 'TextRect', 'push(@ret, &convert_textrect($here))', 'Frame', 'push(@ret, &convert_frame($here))', 'ImportObject', 'push(@ret, &convert_picture($here))', 'BRect', 'push(@ret, &change_dims($data, "posx", "posy", "absw"))', 'AnchorAlign', '$oldalign=$State{"Alignment"}; $align=1; push(@ret, &select_attr($data, "Alignment", "Left", "ql", "Center", "qc", "Right", "qr", "LeftRight", "qj"));', 'FrameType', 'push(@ret, &select_attr($data, "FrameType", "Inline", "posyil", "Top", "posyt", "Bottom", "posyb", "Left", "posxl", "Right", "posxr", "Near", "posxi", "Far", "posxo"))' ); # if we fiddled the alignment then we put it back how # it was as we don't want to affect other things --tjh if ($align) { push(@ret,"\\par\\pard"); $State{"Alignment"}=$oldalign; } @ret; } sub convert_textrect{ local($tr) = @_; local(@ret); local($myparts) = &parts($tr); local($mytoken) = &token($tr); local($mydata) = &data($tr); ## &DUMP_CONTEXT($tr); ##print STDERR "TEXTRECT: $_ : $tr => $myparts $mytoken : $mydata\n"; &do_statement ($tr, 'DashedPattern', ' # do nothing ... print STDERR "GOT DASHED PATTERN\n"; ', 'ID', 'local($_) = $TextRect{$data}; $_ && !$TextFlow{$_}++ ? push(@ret, &convert_flow($_)) : &debug("no flow or repeated flow:$data line: ",$Lines{$_});', ); @ret; } # # this is one alternative... # sub old_convert_textrect{ local($tr) = @_; local($id, @ret); &debug("convert textrect $tr"); for($id = &data_search($tr, 'ID', 1); $id; $id = &data_search($tr, 'TRNext', 1)){ local($s) = $TextRect{$id}; last if $TextRect[$s]++; &debug("TextRectID = $id"); push(@ret, &convert_flow($s)); } @ret; } #> Modified Table conversion to work. #> Assumption: That TblColumnWidth, TblH & TblBody are the main parts #> for conversion only #> Global_Var: Tbl_sw: Used in convert_paragraph for special paragraph handling sub convert_table{ local($s) = @_; local(@r, @cellx); #>Added @cellx for cell dimensions #>Set table switch used in convert_paragraph section $Tbl_sw++; # need to know which row we are on in the table $State{$Tbl_Sw,"ROW"}=0; &do_statement ($s, 'TblColumnWidth', 'push(@cellx, &rtf_dimensions(&data($here)))', 'TblH','push(@r, &convert_rows($here, *cellx, 1))', # handle the title like "normal" text for the moment 'TblTitleContent', 'push(@r, &convert_flow($here), "" ); ', 'TblFormat', '#IGNORED#', 'TblBody','push(@r, &convert_rows($here, *cellx, 0))', ); push(@r, "\\pard"); #> Requires mark to terminate table $Tbl_sw--; #> Set table switch used in convert_paragraph @r; } #> Converts a row for a table #> Sets standard headings for the row and converts cell size into twips, then #> converts cells data #> sub convert_rows{ local($s, *cellx, $row_sw) = @_; local(@r); &do_statement ($s, 'Row', '$State{$Tbl_Sw,"ROW"}++; push(@r, "\n\\\\trowd\\\\trgaph108\\\\trleft-108 "); local($cell, $cell_twips); foreach $cell (@cellx) { $cell_twips = $cell_twips + $cell; push(@r, "\\\\cellx$cell_twips "); } push(@r, "\\\\pard\\\\plain\\\\intbl ",&convert_cells($here), " \\\\pard \\\\intbl \\\\row")' ); @r; } #> Convert cells of a table # sub convert_cells{ local($s) = @_; local(@r); &do_statement ($s, 'Cell', 'push(@r, &convert_cell($here))' ); @r; } #> Convert single cell in table and suffix of cell to terminate cell definition # sub convert_cell{ local($s) = @_; local(@r); #@@ cell formatting! &do_statement ($s, 'CellContent', ' $State{$Tbl_sw,"FirstCellPara"}=1; $State{$Tbl_sw,"FirstTableRow"}=($State{$Tbl_sw,"ROW"}==1); push(@r, &convert_flow($here), "\\\\cell ")' ); @r; } #> Converts a picture into RTF #> Assumptions: That all 'ImportObFileDI' will have a corresponding bitmap. #> Glbal_Var: @Bmroot : A list of paths used for Bitmaps sub convert_picture{ local($s) = @_; local(@r, $color, $unixpath, $dipath, $epsi, $image, $brect); &do_statement ($s, 'Separation', '$color = $data', 'ImportObFile', '$unixpath = $data', 'ImportObFileDI', '$dipath = $data', 'EPSI', '$epsi = $data', 'FrameImage', 'push(@r, "\\\\frameimage\n", $data)', 'BRect', '$brect = $data' ); &debug("picture: color($color) file($unixpath,$dipath) brect($brect)"); if($brect){ local($l, $t, $h, $w) = &rtf_dimensions($brect); unshift(@r, "\\picwgoal$w\\pichgoal$h\n"); } undef($unixpath) if $unixpath =~ /internal inset/; local($path, $filename); if($dipath){ ($path, $filename) = &convert_filename($dipath); #> CRW warn "no path is : $dipath" if ( $filename eq "" ); #> CRW if ( $filename ) { #> CRW if (0) { # center the pictures ... might stuff up a few # things with inline mini-images but that can # be sorted out later --tjh push(@r, "\n\\qc\\{bmc $filename\\}\\par\n" ); } else { push(@r, "\n\\{bmc $filename\\}\n" ); #> CRW } push(@Bmroot, $path) if ( $path ); #> CRW } } else { if($epsi){ $epsi =~ s/.*&%v\s*&//; $epsi =~ s/\n&//g; push(@r, "\\epsi\n", $epsi); } @r = ("\\qc{\\pict\n", @r, "}\\par\n"); # put in a centered paragraph @r = ("{\\cf$color", @r, "}") if $color; } @r; } #> CRW convert_filename : Converts Frame file names into paths , storing #> those paths, to be used in the hpj files sub convert_filename{ local( $Filename) = @_; local( $Directory, $file, @File_Parts, $Path_sw, $Temp_File ); $Filename =~ s/[`']//g; @File_Parts = split( // ) { # Root Directory - Unix ($Directory = $_ ) =~ s/r\\>/\// ; } elsif ( $_ =~ /^c\\>/ ) { # Relative Path name unless 'C' if ($Path_sw) { $file =~ s/^c\\>/\//; $Directory .= $file; } else { $file =~ s/^c\\>//; } $Path_sw = 1; if ( $_ = $File_Parts[$#File_Parts] ) { ($Filename = $_) =~ s/^c\\>//; } else { $Directory .= $file; } } elsif ( $_ =~ /^u\\>/ ) { # Previous directory ie go up $Directory .= "../"; $file =~ s/^u\\>//; if ( $_ = $File_Parts[$#File_Parts] ) { ($Filename = $_) =~ s/^u\\>//; } else { $Directory .= $file; } } } # Should have Directory & Filename #> Convert filename to be a "BMP" always for WinHelp Files if ( $Filename ne "" ) { $Filename =~ s/\.(gif|mif|epsi|eps)$/\.bmp/; } return($Directory, $Filename); } # sub convert_flow{ local($s, $Container) = @_; local(@r, %Notes); &do_statement ($s, 'Notes', '&save_notes($here)', 'Para', 'push(@r, &convert_paragraph($here))' ); @r; } sub save_notes{ local($s) = @_; local($_, $n); foreach (&parts($s)){ $n = &data_search($_, 'ID', 1); # &debug("note: $n is:", &expand_mif_statement($_)); $Notes{$n} = $_; } } #> Convert a block of markers/text that starts with the marker * 'PgfNumberFont', '$State{"NumberFont"} = &convert_string($data); ', 'PgfNumFormat', '$State{"NumFormat"} = &convert_string($data,$State{"Family"} ne "Symbol");', # certainly need to support spacing overrides! 'PgfSpBefore', '$State{"SpBefore"} = &change_dims($data,"sb")', 'PgfSpAfter', '$State{"SpAfter"} = &change_dims($data,"sa")', 'ParaLine', ' @newdata=(); if ($State{$Tbl_sw,"FirstCellPara"}) { $State{"SpBefore"} = &change_dims("0 pt","sb"); $State{"SpAfter"} = &change_dims("0 pt","sa"); } push(@newdata,"$State{SpBefore}","$State{SpAfter}"); # add in NumFormat if there is no NumString setting # and a NumFormat exists ... if ( !$have_numstring && $State{"NumFormat"} ) { $delayed_text=&convert_numformat($State{"NumFormat"}); } push(@newdata,&convert_paraline($here, *pre, *post)); if ($verbose && $pgfnumdebug) { $newdatastring = join("|",@newdata); print STDERR "STATE " . $State{"NumFormat"} . "\n"; print STDERR "STMT $have_numstring $newdatastring\n"; } push(@lines, @newdata, "\n"); ', ); # we have done at least one paragraph so we are no longer # on the first paragraph of a cell ... so clear it now $firstcellpara=$State{$Tbl_sw,"FirstCellPara"}; # we need this below! undef $State{$Tbl_sw,"FirstCellPara"}; &debug("convert_paragraph: ",$State{'PgfTag'}); print STDERR "." unless ($quiet); push(@lines, $HyperGroup), undef($HyperGroup) if $HyperGroup; local($group); #@#lines is arbitrary $RTFInfo{$group} .= join('', @lines)."\\par\n" if $group = $TagGroup{$State{'PgfTag'}}; &debug(%TagGroup); &debug("tag: ", $State{'PgfTag'}, " group: ", $group); #> CRW Added !$Tbl_sw #if ( !$skiptags{$State{PgfTag}} && !$Tbl_sw ) { if ( !$skiptags{$State{PgfTag}} ) { # $Container is, e.g. '\intbl ' (for tables) #> CRW Added Test for tt_TableTitle to generate Autonumber Title # THIS IS OLD CODE ... we now look at the table title stuff # as the user can set that to whatever they like! if (0) { if ( $State{'PgfTag'} eq 'tt_TableTitle' ) { local($Table_Hdr) = "{\\b Table ". ++$PgfAutoNum{'tt_TableTitle'} .": }"; unshift(@lines, "$Table_Hdr"); } } # return(@pre, @fmt, $Container, ¤t_tabs(), # @lines, "\\par", @post, "\n"); # moved the insert of the "\\par" between lines and post # up to the start of the next one ... if (!$SDFVAR{"header"} && ($paragraph_count>1)) { ##print STDERR "inserting par\n"; if ( ! $firstcellpara ) { if ($rtfdebug) { unshift(@pre,"\\par{{ENDPARA}}"); } else { unshift(@pre,"\\par"); } } else { if ($rtfdebug) { unshift(@pre,"{{FIRSTCELL-NOENDPARA}}"); } } } $paragraph_count++; if ($rtfdebug) { return(@pre, @fmt, $Container, ¤t_tabs(), @lines, "{{OLD-PAR}}", @post, "\n"); } else { return(@pre, @fmt, $Container, ¤t_tabs(), @lines, "\\line", @post, "\n"); } } else { # $Container is, e.g. '\intbl ' (for tables) return ( ($Tbl_sw) ? "@fmt@lines" : ""); } } sub current_tabs{ local($rtf, $_); local($li) = &rtf_dimensions($State{'LIndent'}); foreach (&rtf_dimensions($State{'TabStops'})){ $_ -= $li; #@# MIF to RTF mindset $_ = $_ - 720 + 72 if ( $winhelp ); $rtf .= "\\tx$_ "; } $rtf; } sub convert_numstring{ local($string) = @_; local(%State) = %State; # don't clobber font local($numfont) = $State{'NumberFont'}; local($font) = $numfont ? &change_char_style($numfont) : ''; local($form) = $State{'NumFormat'}; $string = &convert_string($string, $State{'Family'} ne 'Symbol'); &debug("numstring($string) [font($numfont): $font form: $form]"); local($tabs) = ¤t_tabs(); return "{\\field{\\fldinst PgfNumFormat $form}{\\fldrslt $font$tabs$string}}"; } # # convert_numformat : handle the FrameMaker PgfNumFormat construct # # [TAG:][TEXT|]* # # TAG is anything ... typically a single letter # EXPR is something like , , # or the above with A for alpha # # From FrameMaker 4 - Using FrameMaker 4-38 # # keep same don't display # reset to zero ... don't display # n=numeric 1,2,3,4,... # r=lower roman i,ii,iii,iv,... # R=upper roman I,II,III,IV,... # a=lower alpha a,b,c,...,aa # A=upper alpha A,B,C,...,AA # sub num_eval{ local($tag,$level,$text,$expr)=@_; local($result,$op,$arg,$type); # keep state local here ... makes moving this to other packages # much easier ... who knows if I've got the following list right # as I cannot recollect much of my Latin classes from so long ago # -- tjh :-) if (!defined $num_to_roman) { @num_to_roman=('0','i','ii','iii','iv','v','vi','vii','viii','ix','x', 'xi','xii','xiii','xiv','xv','xvi','xvii', 'xviii', 'xix','xx' ); } $type=''; $op=''; $arg=''; $type=substr($expr,0,1); if (length($expr)>1) { $op=substr($expr,1,1); $arg=substr($expr,2); $arg = '1' if ($arg eq ''); } # make the tag the combined name and the type so that # things are easier to follow if we have to debug this :-) $tag = "$tag$type"; $result=''; if ($op eq '') { if (!defined($NUM_EVAL{$tag,$level})) { $NUM_EVAL{$tag,$level}=1; } } elsif ($op eq '+') { $NUM_EVAL{$tag,$level}+=$arg; } elsif ($op eq '-') { $NUM_EVAL{$tag,$level}-=$arg; } elsif ($op eq '=') { $NUM_EVAL{$tag,$level}=$arg; } # altering the lowest level value *always* clears # the other dependant values ... # i.e. 1.2 changing the 1->2 means .2->.1 if ($op ne '') { undef $NUM_EVAL{$tag,$level+1}; } # A = alpha, n = numeric if ($type eq 'A') { $result = sprintf("%c",ord('A')+$NUM_EVAL{$tag,$level}-1); } elsif ($type eq 'a') { $result = sprintf("%c",ord('a')+$NUM_EVAL{$tag,$level}-1); } elsif ($type eq 'R') { $result=$NUM_EVAL{$tag,$level}; $result =~ s/(\S+)/\U$1\E/g; } elsif ($type eq 'r') { $result=$num_to_roman[$NUM_EVAL{$tag,$level}]; } else { $result=$NUM_EVAL{$tag,$level}; } if ($pgfnumdebug) { print STDERR "num_eval($tag,$level) $expr :OP=$op ARG=$arg -> $result [$text]\n"; } if ($use_numformat) { return "$text$result"; } else { return "$text"; } } sub convert_numformat{ local($str) = @_; local($format,$tag,$rest,$level); $format=$str; if (substr($format,1,1) eq ':') { $tag=substr($format,0,1); substr($format,0,2)=''; } # throw away ">." if not using the number stuff as # it is probably not what the user wants or expects to see if (!$use_numformat) { $format =~ s/>\./>/g; } $level=0; $format =~ s/([^<]*)(<([^>]*)>)/&num_eval($tag,$level++,$1,$3)/ge; if ($pgfnumdebug) { print STDERR "NUMFORMAT($str) => TAG $tag FORMAT $format\n"; } return $format; } sub change_style{ local($tag) = @_; local($style, $_); if($PgfCatalog{"Style", $tag}){ &set_paragraph_format($tag); $style = $PgfCatalog{"Style", $tag}; }else{ local($pgf_fmt) = $PgfCatalog{'Statement', $tag}; if($pgf_fmt){ &reset_paragraph_format(); &reset_character_format(); $style = &convert_pgf_format($pgf_fmt); $PgfCatalog{"Style", $tag} = $style; ##STYLE## #warn "Catalog entry for '$tag' added as $style"; &save_paragraph_format($tag); }else{ warn "No catalog entry for '$tag'"; } } if ($pgfnumdebug) { print STDERR "CHANGE_STYLE to \"$tag\" NumFormat \"$State{'NumFormat'}\" Placement \"$State{'Placement'}\" NEWTOPIC $State{'NEWTOPIC'}\n"; } $State{'PgfTag'} = $tag; join('', "\\pard\\plain\\s", &intern(*Tag, $tag), " ", $style); } sub change_char_style{ local($tag) = @_; local($style, $_); &reset_character_format(); $State{'FTag'} = $tag; local($s) = $FontCatalog{'Statement', $tag}; $s ? "\\plain" . &convert_char_format($s) : ''; } #> Converts the block of text/markes which start with $HyperGroup is determined from Marker Type 8 #> $Xref_TOC is determined from Marker Type 11 sub convert_paraline{ local($s, *pre, *post) = @_; #@# empty_hyper gets around the: hot-text bug. local(@text, $empty_hyper); #print STDERR "SDFVAR header = " . $SDFVAR{"header"} . "\n"; #print STDERR "SDFVAR window = " . $SDFVAR{"window"} . "\n"; &do_statement ($s, 'DashedPattern', '# do nothing', 'String', 'local(@tmptext)=&convert_string($data,$State{"Family"} ne "Symbol"); # if we have hypertext information then we process it # now we have all the pieces required --tjh if ( $Xref_TOC && $hypertext_sw ) { #> If TOC has been defined $Xref{$Xref_TOC} = "@tmptext"; $XrefTopic{$Xref_TOC} = &convert_context("@tmptext"); if ($tjh_xref_debug) { print STDERR "Xref{$Xref_TOC}=\"$Xref{$Xref_TOC}\"\n"; } } ##print STDERR "Text: " . join(" ",@tmptext) . " Delayed $delayed_text\n"; # force a page break here for the first time we hit a # popup window ... might have to think about how to # separate multiple popup windows too ... if ($SDFVAR{"window"}) { if (!$done_pagebreak) { $done_pagebreak=1; if ($rtfdebug) { push(@text, "\n\\\\page{{WINDOWSTART}}\n"); } else { push(@text, "\n\\\\page\n"); } } } elsif ($SDFVAR{"endwindow"}) { # push another page break? if ($rtfdebug) { push(@text, "\n\\\\page{{WINDOWEND}}\n"); }else { push(@text, "\n\\\\page\n"); } $done_pagebreak=0; } elsif ($SDFVAR{"header"}) { # keep this with the previous paragraph! if ($rtfdebug) { push(@text, "\n\\\\keepn{{HEADERKEEP}}\n"); } else { push(@text, "\n\\\\keepn\n"); } } # if we have saved up some text that goes before the # next output string and it has formatting information # (i.e. font specification) then we must grab that # now and then reset back to current ... ##if ($delayed_text && $State{"NumberFont"} ) if ($delayed_text) { &save_char_format(); $delayed_text = &handle_font_change($State{"NumberFont"}) . $delayed_text . &restore_char_format(); } if ( $HyperGroup && $hypertext_sw ) { ($token,$arg) = $HyperGroup =~ /(\S+) (.*)/; $curtag=$State{PgfTag}; #$heading=($curtag =~ /^h[1]_Heading\b/); #$heading=$State{"PgfPlacement"} ne "Anywhere"; $heading=$State{"NEWTOPIC"} eq "1"; $WH_topic = &convert_context($arg); &hyperdebug("Token=$token Arg=$arg Hyper=$HyperGroup Tmptext=@tmptext"); # handle each hypertext construct ... if ( $token eq "newlink" ) { #>Added enhanced footnote text, check that tmptext is not blank if ( $heading && $tmptext[0] ne "") { #> Footnote - Title $Footnote_txt = "\\\\keepn {\\\\up6 \${\\\\footnote \\\\pard". "\\\\plain{\\\\up6 \$} @tmptext}}\n"; $Footnote_txt .= "{\\\\up6 +{\\\\footnote \\\\pard\\\\plain". "{\\\\up6 +}"; #>Footnote Browse Seqeunce $Footnote_txt = sprintf("$Footnote_txt %04d}}\n",++$browse_seqno); push(@text, "\n"); # page break *before* the topic starts ... push(@text, $paragraph_count>0 ? "\\\\page" : "", "\n"); push(@text, $Footnote_txt); $paragraph_count++; #>New Page after every major header/topic } &rtf_topic_keyword(*WH_topic, *text, $arg); &Generate_ID($WH_topic,*tmptext); # override TOC marker text from the default of the # value of the string to being what was directly # specified --tjh if ( $Xref_TOC && $hypertext_sw ) { $XrefTopic{$Xref_TOC} = "$WH_topic"; } if ( $ExtraHyperGroup ) { ($token,$arg) = $ExtraHyperGroup =~ /(\S+) (.*)/; $WH_topic=&convert_context($arg); &hyperdebug( "Extra Token=$token Arg=$arg"); if ( $token eq "HELPTOC" ) { push(@text,"{\\\\up6 #{\\\\footnote \\\\pard\\\\plain". "{\\\\up6 #} $WH_topic}}\n"); &Generate_ID($WH_topic, *tmptext); } undef ($ExtraHyperGroup); } # allow for delayed text that must stay with # the real string and not be broken by the hypertext # stuff being inserted! push(@text,$delayed_text) if ($delayed_text); $delayed_text=""; push(@text,@tmptext); # Push Actual Header into Document } elsif ( $token eq "gotolink" ) { # allow for delayed text that must stay with # the real string and not be broken by the hypertext # stuff being inserted! push(@text,$delayed_text) if ($delayed_text); $delayed_text=""; if ( $arg =~ /\.fvo:/ ) { #> CRW This is an external link local($file, $link); $arg =~ s/\.fvo/\.hlp/; #>Strip .fvo ext ($file, $link) = split(/:/, $arg); # IGC begin #$file = &convert_context($file); $link = &convert_context($link); # IGC end $WH_topic = "$link\@$file"; } if ($SDFVAR{"popup"}) { push(@text,"{\\\\ul @tmptext}{\\\\v $WH_topic}"); undef $SDFVAR{"popup"}; } else { push(@text,"{\\\\uldb @tmptext}{\\\\v $WH_topic}"); } } elsif ( $token eq "HELPTOC" ) { #> $ Footnote - Title $Footnote_txt = "{\\\\up6 \${\\\\footnote \\\\pard\\\\plain". "{\\\\up6 \$} @tmptext}}\n"; $Footnote_txt .= "{\\\\up6 #{\\\\footnote \\\\pard\\\\plain". "{\\\\up6 #} $WH_topic}}\n";#> # Footnote Context String $Footnote_txt .= "\\\\keepn{\\\\up6 +{\\\\footnote \\\\pard". "\\\\plain{\\\\up6 +}"; #> + Footnote Browse Seqeunce $Footnote_txt = sprintf("$Footnote_txt %04d}}\n",++$browse_seqno); push(@text, "\n"); push(@text, $paragraph_count>0 ? "\\\\page" : "", "\n"); push(@text, $Footnote_txt); &Generate_ID($WH_topic, *tmptext); if ( $ExtraHyperGroup ) { ($token,$arg) = $ExtraHyperGroup =~ /(\S+) (.*)/; $WH_topic=&convert_context($arg); &hyperdebug("Extra Token=$token Arg=$arg"); if ( $token eq "HELPTOC" ) { push(@text,"{\\\\up6 #{\\\\footnote \\\\pard\\\\plain". "{\\\\up6 #} $WH_topic}}\n"); &Generate_ID( $WH_topic, *tmptext); } undef ($ExtraHyperGroup); } # allow for delayed text that must stay with # the real string and not be broken by the hypertext # stuff being inserted! push(@text,$delayed_text) if ($delayed_text); $delayed_text=""; push(@text,@tmptext); #> Assume that gotopage is external document(Table of ContentsId=1) } elsif ( $token eq "gotopage" ) { local($macro); ($WH_topic = $arg) =~ s/\.fvo.*/\.hlp/; #$macro = "{\\\\v \!JC("; #$macro .= "\"$WH_topic\"\,0000000001)}"; # use the JumpContents option and then we do not # get two error windows ... --tjh $macro = "{\\\\v \!JumpContents(\"$WH_topic\")}"; # allow for delayed text that must stay with # the real string and not be broken by the hypertext # stuff being inserted! push(@text,$delayed_text) if ($delayed_text); $delayed_text=""; push(@text, "{\\\\uldb @tmptext}", $macro); #> #> Assume that the gotourl is a URL for WWW } elsif ( $token eq "gotourl" ) { if ($sdfvartrace) { print STDERR ("SDF:gotourl: $tmptext\n"); } # allow for delayed text that must stay with # the real string and not be broken by the hypertext # stuff being inserted! push(@text,$delayed_text) if ($delayed_text); $delayed_text=""; push(@text, "{\\\\b @tmptext}"); #> URL is bolded with text } else { # allow for delayed text that must stay with # the real string and not be broken by the hypertext # stuff being inserted! push(@text,$delayed_text) if ($delayed_text); $delayed_text=""; push(@text, "{{\\\\v \\\\xe $HyperGroup}}"); } # once we use the hypertext stuff in the output it # is totally finished with ... so blow it away! undef ($HyperGroup); # these are cleared on para entry so can be removed # from here soon ... #undef ($USER_WH_context); #undef ($USER_WH_topic); } else { if ( $HyperGroup && !$hypertext_sw ) { push( @tmptext , "{\\\\pard \\\\plain \\\\v\\\\f4\\\\fs20". "{\\\\xe {@tmptext}}}"); undef $HyperGroup; } # any delayed text must go out now as it can be # delayed no longer! push(@text,$delayed_text) if ($delayed_text); $delayed_text=""; push(@text,@tmptext); } # finished with this stuff now ... if ( $Xref_TOC && $hypertext_sw ) { #> If TOC has been defined $Xref_TOC = ""; } $empty_hyper=0;', 'Char', 'push(@text, &convert_character($data))', 'ATbl', 'local(%State) = %State; local(@tbl) = &convert_table($Tbl{$data}); $State{"TblPlacement"} =~ /Top|Left|Right|Near|Far/ ? push(@pre, "{", @tbl, "}") : push(@post, "{", @tbl, "}")', 'AFrame', 'local(%State) = %State; &debug("converting AFrame $data"); local(@af) = &convert_frame($AFrame{$data}); $State{"FrameType"} =~ /Top|Left|Right|Near|Far/ ? push(@pre, "{", @af, "}") : push(@post, "{", @af, "}")', 'FNote', 'push(@text, &convert_footnote($Notes{$data}))', 'XRefEnd', 'push(@text, &convert_xref_end($data))', #@@ there could be a problem with tagged fonts here: # convert_char_format ignores tags. Catalog lookup occurs # in its caller (e.g. convert_character_catalog). # And this is its caller. 'Font', 'push(@text, $HyperGroup), undef($HyperGroup) if $HyperGroup && !$empty_hyper; push(@text, &convert_char_format($here))', 'Marker', 'push(@text, &convert_marker($here)); $empty_hyper=1', 'Variable', 'push(@text, &convert_definition("Variable", &data_search("VariableName", $here)))', 'XRef', 'push(@text, &convert_xref($here))' ); @text; } local($active); sub handle_font_change{ local($str)=@_; local($ret); return '' if ($active); $ret=''; if ($str eq "Bold") { # Bold by itself means Bold with *no* Italics $ret = &select_attr($str,"Weight", $str, "b"); $ret .= &select_attr($str,"Angle", $str, "i0"); } elsif ($str eq "Italic") { # Italics by itself means Italics with *no* Bold $ret = &select_attr($str,"Angle", $str, "i"); $ret .= &select_attr($str,"Weight", $str, "b0"); } elsif ($str eq "" || $str eq "Default" ) { $ret .= &select_attr($str,"Weight", $str, "b0"); $ret .= &select_attr($str,"Angle", $str, "i0"); $ret .= &select_attr($str,"Color", $str, "cf0"); } else { $active=1; # assume that it is a "normal" font catalog entry $stmt=$FontCatalog{'Statement', $str}; if ($stmt) { $State{'FTag'} = $str; $ret = &convert_char_format($stmt); ## Debug stuff ... ##&DUMP_CONTEXT($stmt); #warn "font change \"$str\" maps to $ret\n"; } else { warn "unknown font change ignored \"$str\"\n"; } #$ret=&change_char_style($str); $active=0; } return $ret; } # Change a MIF String datum (without newlines) to a rtf string # sub convert_string{ local($_, $do_hex) = @_; # put backslashes out of band if (0) { s/\\\\/\n\n/g; } else { #s/\\\\/\0\0/g; s/\\\\/\\/g; } # undo MIFisms s/^`//; s/'.*//; s/\\q/'/g; s/\\Q/`/g; s/\\/>/g; # tjh added s/\\ / /g ; s/\\x15 /-/g ; # handle non-breaking hyphen! # convert hex stuff $do_hex ? s/\\x(\w\w) /$FrameCode[hex($1)]/ge : s/\\x(\w\w) /pack('C', hex($1))/ge; # protect RTFisms if (0) { s/\{/\n\{/; s/\}/\n\}/; } else { # TJH get the curlybraces right s/{/\\{/g; s/}/\\}/g; } s/\\t/\\tab /g; #TJH # convert the bullet into something that actually looks right! ###TODO XXXX GET THIS RIGHT!!!### #s/\\bullet/&convert_other("SYMBOL 183 \\\\\\\\f \\"Symbol\\" \\\\\\\\s 10 \\\\\\\\h");/ge; s/\\bullet/\\f99 \\'B7 \\f- /g; # put backslashed back in! --tjh if (0) { } else { s/\0\0/\\\\/g; } $_; } sub convert_character{ local($name) = @_; $CharacterConversions{$name}; } sub convert_footnote{ return ("\\chftn{\\footnote\n", &convert_flow($_[0]), "}"); } sub convert_xref{ local($s) = @_; $XRefSrcText = ""; $XRefSrcFile = ""; if ( $hypertext_sw ) { #> If hypertext add TOC, add TOC at fron of doco $XRefName = &convert_string(&data_search($s, 'XRefName')); $XRefSrcText = &convert_string(&data_search($s, 'XRefSrcText')); # Used for TOC types if ( $XRefName eq 'TOC' || $XRefName eq 'HELPTOC' ) { # also keep track of the paragraph style when the # XRef is seen as we need this for handling multi-level # table of contents for sorting out the indent side # of things --tjh $XrefStyle{$XRefSrcText} = $State{'PgfTag'}; $XrefTabs{$XRefSrcText} = ¤t_tabs(); if ($tjh_xref_debug) { print STDERR "XREF::$XRefSrcText=>$State{'PgfTag'}::" . ¤t_tabs() . "\n"; print STDERR "XRefSrcText: $XRefSrcText $State{'PgfTag'}\n"; } push(@XRefTOC, $XRefSrcText); } } return ""; } sub convert_xref_end{ $XRefSrcText = ""; $XRefSrcFile = ""; return ""; } sub convert_definition{ local($type, $name) = @_; #@# converts Frame variables literally to RTF return &convert_string($Definition{$type, $name}); } sub convert_other{ local($token, $text, $invisible) = @_; local($fldpriv) = $invisible ? '\fldpriv\v' : ''; print STDERR "CONVERT_OTHER: $token $text\n"; return "{\\field$fldpriv{\\fldinst $token}{\\fldrslt $text}}"; } #> Converts the ' string ' where 0 Change the index to a keyword for Help files if ( $hypertext_sw ) { $keyword = "{\\up6 K{\\footnote \\pard\\plain{\\up6 K} $text}}"; if ( $State{'PgfTag'} eq 'dn_DocName' ) { $Keyword_dn_DocName = $keyword; } } return "$keyword{\\v{\\xe $text}}"; #@# text needs to be interpreted } else { # The following does a different job ... not sure what # Craig wanted above ... treat it like a marker of type 8 # ... think about this ... we are working in DOS without # having gone through framemaker ... this could be the issue! $HyperGroup = "gotolink $text"; &debug( "HyperGroup = $HyperGroup"); return ""; } } elsif ($type == 3) { $RTFInfo{'comment'} .= "$text\n"; } elsif ($type == 4) { $RTFInfo{'subject'} .= "$text\n"; } elsif ($type == 5) { #> This is 'Author' type indexes #> Change 'Author' index to a keyword for Help files if ( $hypertext_sw ) { $keyword = "{\\up6 K{\\footnote \\pard\\plain{\\up6 K} $text}}"; } $RTFInfo{'author'} .= "$text\n"; return "$keyword"; #> Return Keyword } elsif($type == 6) { $RTFInfo{'keywords'} .= "$text\n"; #@# glossary, really } elsif($type == 7) { return '{\|}'; #@# equation marker->formula character } elsif($type == 8) { # &Verbose("Marker text=$text"); # save the text for when we have the string the follows # the text and hence can process it ... as we may need # to embed the following string in the output! --tjh # ($token,$arg) = $text =~ /(\S+) (.*)/; # handle the variables that SDF is passing through to # us to indicate the values to use for topic names # and context ids so that we have total control # over things in the HELP output if ( $token eq "sdf" ) { ($var,$value)=split(/=/,$arg); $SDFVAR{$var}=$value; if ($sdfvartrace) { print STDERR ("SDF SET => $var=$value\n"); } if ( $var eq "topic" ) { # use whatever is given as the topic name $USER_WH_topic=$value; if ($sdfvartrace) { print STDERR ("SDF:USER_WH_topic: $USER_WH_topic\n"); } # DO NOT PUT ANYTHING IN HERE ... if the user does not # have this defined as a link then too bad! # make sure we get a hypertext link in here ... # which the user can override if the wish but # we will use the saved value for the topic name # ZZZZ if ( ! $HyperGroup ) { $HyperGroup="newlink $value"; } } elsif ( $var eq "context" ) { # use whatever is given as the context ID $USER_WH_context=$value; if ($sdfvartrace) { print STDERR ("SDF:USER_WH_context: $USER_WH_context\n"); } # DO NOT PUT ANYTHING IN HERE ... if the user does not # have this defined as a link then too bad! # make sure we get a hypertext link in here ... # which the user can override if the wish but # we will use the saved value for the context id # ZZZZ if ( ! $HyperGroup ) { $HyperGroup="newlink $value"; } } elsif ( $var eq "header" ) { # the current paragraph is included in the header # of the non-scrolling region ... so do not close that # off just yet! # ZZZZ if ( ! $HyperGroup ) { $HyperGroup="newlink $value"; } } elsif ( $var eq "window" ) { # the current paragraph is part of a popup window # and hence we need to do special things } elsif ( $var eq "endwindow" ) { # the current paragraph is a marker of the end # of a popup window ... we can toss it! } elsif ( $var eq "popup" ) { # jump off to a popup window ... which we want # to be just link gotolink $HyperGroup="gotolink $value"; } elsif ( $var eq "url" ) { # just like the old gotourl $HyperGroup="gotourl $value"; } else { # Warn the user that there is something that we do not # understand being sent there ... at least for the # moment until we get this working smoothly print STDERR ("Warning: Unknown SDF variable $var=$value\n"); } } else { # otherwise "normal" thing ... $HyperGroup = "$text"; &debug( "HyperGroup = $HyperGroup"); } return ""; } elsif ( $type == 9 ) { return ""; } elsif ( $type == 11 ) { if ( $hypertext_sw && $State{PgfTag} ne 'dn_DocName') { $Xref_TOC = $text; } return ""; } return &convert_other('FrameMarker ' . ($type+1), $text, 1); #@# } # # Output routines # sub debug{ # print STDERR @_, " @$.\n" if ( $Debug ); print STDERR @_, "\n" if ( $Debug ); } sub hyperdebug{ print STDERR @_, "\n" if ( $hyper_debug ); } #> Calls debug sub Verbose{ if ( $vbs_sw ) { if ( $Debug ) { &debug(@_); } else{ $Debug = 1; &debug(@_); $Debug = 0; } } } # # Initialize global variables #> Added 'pb_PageBreak' to SkipTags if Hypertext sub initialize_state{ @FrameCode = ('', '', '', '', '\-', '', '\_', '', '\tab', '\line', "\266", "\247", '', '', '', '', " ", "\240", " ", " ", " ", "\255", '', '', '', '', '', '', '', '', '', '', ' ', '!', '"', '#', "\$", '%', '&', "\'", '(', ')', '*', '+', ',', '-', '.', '/', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', ':', ';', '<', '=', '>', '?', '@', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', '[', "\\", ']', '^', '_', "\`", 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', '{', '|', '}', '~', '', # 0x80 "\304", "\305", "\307", "\311", "\321", "\326", "\334", "\341", # 0x88 "\340", "\342", "\344", "\343", "\345", "\347", "\351", "\350", # 0x90 "\352", "\353", "\355", "\354", "\356", "\357", "\361", "\363", # 0x98 "\362", "\364", "\366", "\365", "\372", "\371", "\373", "\374", # 0xa0 #TJH "**", "\260", "\242", "\243", "\247", "\267", "\266", "\337", "**", "\260", "[CENT]", "[POUND]", "\247", "\\bullet", "\266", "\337", # 0xa8 "(r)", "(c)", "(tm)", "\264", "\250", "", "\306", "\330", # 0xb0 "", "", "", "", "\225", "", "", "", # 0xb8 "", "", "", "\252", "\272", "", "\346", "\370", # 0xc0 "\277", "\241", "\254", "", "f", "", "", "\253", # 0xc8 "\273", "...", "", "\300", "\303", "\325", "OE", "oe", # 0xd0 "\255", "--", "``", "''", "`", "'", "", "", # 0xd8 "\377", "Y", "/", "\244", "<", ">", "fi", "fl", # 0xe0 "***", "\267", ",", ",,", "%.", "\302", "\312", "\301", # 0xe8 "\313", "\310", "\315", "\316", "\317", "\314", "\323", "\324", # 0xf0 "", "\322", "\332", "\333", "\331", "i", "^", "~", # 0xf8 "\256", "\257", ".", "\260", "\270", "''", ","); %CharacterConversions = ('Tab', '\tab ', 'HardSpace', '\~ ', 'SoftHypen', '\_ ', #@# 'DiscHypen', '\- ', # 'Cent', "\242", # from ISO8859-1 # 'Pound', "\243", # 'Yen', "\245", 'Cent', "[CENT]", #TJH# 'Pound', "[POUND]", #TJH# 'Yen', "[YEN]", #TJH# 'EnDash', "\255", 'EmDash', '-', #@# 'Dagger', '**', #@# 'DoubleDagger', '***', #@# # 'Bullet', "\267", 'Bullet', "\\bullet", #TJH# 'HardReturn', '\line ', 'EndOfPara', "\266", 'EndOfFlow', "\247", 'NumberSpace', ' ', #@# 'ThinSpace', ' ', #@# 'EnSpace', ' ', 'EmSpace', ' ' ); %doc_defaults = ('paperw', 12240, 'paperh', 15840, 'margl', 1800, 'margr', 1800, 'margt', 1440, 'margb', 1440, 'facingp', '', 'TwoSides', 'No', 'gutter', 0, 'deftab', 720, 'widowctrl', '', 'hyphhotz', '', 'fntsep', '', 'ftnsepc', '', 'ftncn', '', 'endnotes', 1, 'enddoc', 0, 'ftntj', 0, 'ftnbj', 1, 'ftnstart', 1, 'pgnstart', 1, 'linestart', 1, 'landscape', 0, 'fracwidth', 0, 'nextfile', '', 'template', '', 'makeback', '', 'defformat', '', 'revisions', '', 'margmirror', '', 'revprop', 3, 'revbar', 3); %para_defaults = ('snext', '', 'sbasedon', '', 'pard', '', 's', '', 'ql', '', 'qr', '', 'qj', '', 'qc', '', 'Alignment', 'ql', 'LIndent', '0', 'FIndent', '', 'NumberFont', '', 'fi', 0, 'li', 0, 'ri', 0, 'sb', 0, 'sa', 0, 'sl', '', 'intbl', '', ##TJH-WINHELP-no keepn0 'keep', '', 'keepn', '', 'WithNext', 'keep0', 'sbys', '', 'pagebb', '', 'Placement', 'Anywhere', 'noline', '', 'TabStops', '', 'tx', '', 'tqr', '', 'tqc', '', 'tqdec', '', 'tb', '', 'brdrt', '', 'brdrb', '', 'brdrl', '', 'brdrr', '', 'box', '', 'brdrs', '', 'brdrth', '', 'brdrsh', '', 'brdrdb', '', 'brdrdot', '', 'brdrhair', '', 'brsp', '', 'tldot', 1, 'tlhyph', '', 'tlul', '', 'tlth', '', #TJHNEW# # the following also should always be preserved # across changes ... we need this to do handling of # bulletted lists and other things too! 'NEWTOPIC', '', 'NumberFont', '', 'NumString', '', 'NumFormat', '', 'SpBefore', '', 'SpAfter', '' ); %char_defaults = ('f', '', 'Family', '', 'b', '', 'Weight', 'b0', 'i', '', 'Angle', 'i0', 'strike', '', 'Strike', 'strike0', 'outl', '', 'Outline', 'outl0', 'shad', '', 'Shadow', 'shad0', 'scaps', '', 'caps', '', 'v', '', 'fn', '', 'fs', '24', 'expnd', 0, 'ul', '', 'ulw', '', 'uld', '', 'uldb', '', 'ulnone', '', 'Underline', 'ulnone', 'up', '', 'SupScript', 'up0', 'dn', '', 'SubScript', 'dn0', 'revised', '', 'ChangeBar', 'revised0', 'cf', 0, #TJHNEW# 'Color', 'cf0' ); local($_); @DocumentAttrs = keys(%doc_defaults); foreach (@DocumentAttrs){ push(@DocumentDefaults, $doc_defaults{$_}); } @State{@DocumentAttrs} = @DocumentDefaults; @ParagraphAttrs = keys(%para_defaults); foreach (@ParagraphAttrs){ push(@ParagraphDefaults, $para_defaults{$_}); } @State{@ParagraphAttrs} = @ParagraphDefaults; @CharacterAttrs = keys(%char_defaults); foreach (@CharacterAttrs){ push(@CharacterDefaults, $char_defaults{$_}); } @State{@CharacterAttrs} = @CharacterDefaults; # $SkipTags{'pb_PageBreak'} = 1 if ( $hypertext_sw ); #> Added $paragraph_count = 0; $browse_seqno = 1; } sub reset_paragraph_format{ @State{@ParagraphAttrs} = @ParagraphDefaults; ''; } sub set_paragraph_format{ local($tag) = @_; local($_); &reset_paragraph_format(); &reset_character_format(); grep($State{$_} = $PgfCatalog{$_, $tag}, @ParagraphAttrs, @CharacterAttrs); } sub save_paragraph_format{ local($tag) = @_; local($_); grep($PgfCatalog{$_, $tag} = $State{$_}, @ParagraphAttrs, @CharacterAttrs); } sub reset_character_format{ @State{@CharacterAttrs} = @CharacterDefaults; ''; } sub mini_reset{ # make sure we actually know what things are! if ($State{"Weight"} eq "") { $State{"Weight"} = $char_defaults{"Weight"}; } if ($State{"Angle"} eq "") { $State{"Angle"} = $char_defaults{"Angle"}; } if ($State{"Color"} eq "") { $State{"Color"} = $char_defaults{"Color"}; } } sub save_char_format{ local($ret); &mini_reset(); $SavedState{"Family"}=$State{"Family"}; #print STDERR "Saving fs as " . $State{"fs"} . "\n"; $SavedState{"fs"}=$State{"fs"}; $SavedState{"Weight"}=$State{"Weight"}; $SavedState{"Angle"}=$State{"Angle"}; $SavedState{"Color"}=$State{"Color"}; $ret=''; $ret.="F:$SavedState{'Family'} "; $ret.="S:$SavedState{'fs'} "; $ret.="W:$SavedState{'Weight'} "; $ret.="A:$SavedState{'Angle'} "; $ret.="C:$SavedState{'Color'}"; ##print STDERR "SAVE: $ret\n"; } sub restore_char_format{ local($ret); &mini_reset(); if ($State{"Family"} ne $SavedState{"Family"}) { # $ret .= &change_attr("f", &intern(*Typeface, $SavedState{"Family"})); $ret .= "\\f$SavedState{'f'} " if ($SavedState{"f"}); $State{"Family"}=$SavedState{"Family"}; } if ($State{"fs"} ne $SavedState{"fs"}) { #print STDERR "Restoring fs as " . $State{"fs"} . " was " . $SavedState{"fs"} . "\n"; # $ret .= &change_dims($State{"fs"}, "fs/10"); $ret .= "\\fs$SavedState{'fs'} " if ($SavedState{"fs"}); $State{"fs"}=$SavedState{"fs"}; } if ($State{"Weight"} ne $SavedState{"Weight"}) { $ret .= "\\$SavedState{'Weight'} " if ($SavedState{"Weight"}); $State{"Weight"}=$SavedState{"Weight"}; } if ($State{"Angle"} ne $SavedState{"Angle"}) { $ret .= "\\$SavedState{'Angle'} " if ($SavedState{"Angle"}); $State{"Angle"}=$SavedState{"Angle"}; } if ($State{"Weight"} ne $SavedState{"Weight"}) { $ret .= "\\$SavedState{'Color'} " if ($SavedState{"Color"}); $State{"Color"}=$SavedState{"Color"}; } ##print STDERR "RESTORE: $ret\n"; return ($ret); } ############### # # ############### # # sub rtf_begin_doc{ return "{\\rtf1\\ansi\n"; } sub rtf_end_doc{ return "}\n"; } sub rtf_info{ local(%groups) = @_; local(@r, $_); local($toctext); push(@r, "{\\info\n"); foreach (keys %groups){ push(@r, "{\\$_ ", $groups{$_}, "}\n"); } push(@r, "}\n"); if ( $hypertext_sw ) { #> If the TOC is set, add a header and the table of contents if ( scalar(keys(%Xref)) > 0 && $hypertext_sw ) { if (defined $Definition{"Variable", "DOC_TOC_TITLE"} ) { $toctext=&convert_string($Definition{"Variable", "DOC_TOC_TITLE"}); } else { $toctext="Table of Contents"; } push(@r, "\n$PgfCatalog{'Style',h2_Heading}\\keepn"); # a nice graphic can make all the difference in the world # for doing things ... if (defined $Definition{"Variable", "DOC_TOC_GRAPHIC"} ) { push(@r, "\n\\{bml " . &convert_string($Definition{"Variable", "DOC_TOC_GRAPHIC"}) . "\\}\n" ); } if ($lots_of_whitespace) { push(@r, "\n{\\up6 \${\\footnote \\pard\\plain{\\up6 \$} $toctext}}"); push(@r, "\n{\\up6 +{\\footnote \\pard\\plain{\\up6 +} 0000}}$toctext\\par\\pard"); push(@r, "\n{\\up6 #{\\footnote \\pard\\plain{\\up6 #} TableofContents}}\\par\\pard\\plain"); } else { push(@r, "\n{\\up6 \${\\footnote {\\up6 \$} $toctext}}"); push(@r, "\n{\\up6 +{\\footnote {\\up6 +} 0000}}$toctext\\par\\pard\\plain"); push(@r, "\n{\\up6 #{\\footnote {\\up6 #} TableofContents}}"); } foreach ( sort (keys (%Xref))) { local($sty,$str); if ($lots_of_whitespace) { $sty="b0_Body"; } else { $sty="$XrefStyle{$_}"; } $str="\n$PgfCatalog{'Style',$sty}\\snext-1\\sl-1\\sb-1$XrefTabs{$_}\\tab{\\uldb ". $Xref{$_} ."}{\\v $XrefTopic{$_}}\\par\\pard\\plain\n"; if ($tjh_xref_debug) { print STDERR "TOC added: $Xref{$_}\n"; push(@r,"TOCSTART $Xref{$_}\n"); print STDERR "TOCSTYLE \"$PgfCatalog{'Style',$XrefStyle{$_}}\"\n"; print STDERR "$str\n"; } if (0) { if ($lots_of_whitespace) { push(@r, "\n$PgfCatalog{'Style',b0_Body}" . "{\\uldb " . "$Xref{$_}" . "}" . "{\\v $XrefTopic{$_}}\\par" ); push(@r, "WOW", "$str", "WOW" ); } else { #push(@r, "\n$PgfCatalog{'Style',$XrefStyle{$_}}\\snext-1\\sl-1\\sb-1$XrefTabs{$_}\\tab{\\uldb ". $Xref{$_} ."}{\\v $XrefTopic{$_}}\\par\\pard\\plain"); push(@r, "FOO", "FOO $str BAR-Introduction", "BAR", "asdasd"); } } # work around perl 5.001 "features" push(@r, "$str" ); if ($tjh_xref_debug) { push(@r,"TOCFINISH $Xref{$_}\n"); } } push(@r, "\\par\\plain\n\\page"); } else { push(@r, "+{\\footnote + 0000}\n"); } } return @r; } sub intern{ local(*arr, $_) = @_; s/^\`//; s/\'.*//; $arr{$_} || ($arr{$_} = ++$arr); # $_ = $arr{$_} || ($arr{$_} = ++$arr); # &debug("intern: $_[1] -> $_"); # $_; } # # HEURISTIC: uses \fnil for unrecognized fonts. # recognizes all FrameMaker 2.1 fonts # sub rtf_font_table{ local(%fonts) = @_; local(@r, $have_zero, $n, $family, $_); foreach (keys %fonts){ $family = 'nil'; $n = $fonts{$_}; $have_zero = 1 if ( $n eq "0" ); $family = 'roman' if /serif/ || /times/i || /palatino/i || /bookman/i || /newcenturysch/; $family = 'swiss' if /sans/ || /helvetica/i || /avantgarde/i; $family = 'modern' if /courier/i; $family = 'script' if /cursive/i; $family = 'decor' if /zapfchancery/i; $family = 'tech' if /symbol/i; push(@r, "{\\f$n\\f$family $_;}\n"); } # for RTF help files we *must* have a font 0 entry --tjh # and I happen to like Times Roman push(@r, "{\\f0\\froman Times;}\n"); push(@r, "{\\f99\\ftech Symbol;}\n"); return("{\\fonttbl\n", @r, "}\n"); } sub rtf_style_sheet{ local(%styles) = @_; local(@r); local($n, $style, $_); foreach (keys %styles){ $n = &intern(*Tag, $_); #@# all styles mentioned in the document will appear in the # stylesheet, but only styles used in the document will be defined! $style = $PgfCatalog{'Style', $_}; # TJH - blank styles are illegal ... # MS WORD 2 will reject the RTF file if ( "$style$_" ne "" ) { push(@r, "{\\s$n $style$_;}\n"); } } return("{\\stylesheet\n", @r, "}\n"); } sub rtf_color_table{ local(@colors) = @_; local($red, $green, $blue, $_); foreach (@colors){ ($red, $green, $blue) = split(/\s+/, $_); push(@r, "\\red$red\\green$green\\blue$blue;\n"); } return("{\\colortbl\n", @r, "}\n"); } sub rtf_dimensions{ local($_, $twips) = @_; local(@trect); # # convert all dimensions to twips # didot@@ cicero@@ # while($_){ warn "\@\@Dimensions: (@_) \"$_\"\n" if ($tjhdebug); if( s/\s*(-?\d*(\.\d*)?)\s*//){ $twips = $1 * 1440; }else{ warn "\@\@Bad dimensions: (@_) \"$_\"\n"; return (); } s/"//; s/in//; s/pt// && ($twips = $twips/72); s-cm-- && ($twips = $twips/2.54); s-mm-- && ($twips = $twips/25.4); # TJH # remove leading spaces s/^\s+//; push (@trect, int($twips)); } @trect; } #> rtf_topic_keyword: Will produce a keyword with a topic. #> Params: *keyword, *text, Topic Text #>Process: Check there is not a duplicate keyword, if it is, apply alogrithm #> to create a new keyword #> sub rtf_topic_keyword { local(*WH_topic, *text, @tmptext) = @_; # allow the user to override the automatic stuff if ( defined($USER_WH_topic) ) { $WH_topic=&convert_context($USER_WH_topic); } if ( ! $skiptags{$State{PgfTag}} ) { if ( $Keywords{$WH_topic} ) { if ( $fixup_duplicates ) { warn "\nDuplicate Keyword: $WH_topic"; $WH_topic = "$WH_topic". ++$Keywords{$WH_topic}; warn " replaced with Keyword: $WH_topic TEXT:@tmptext"; } else { # warn "\nHandling Duplicate Keyword: $WH_topic (@tmptext)"; } } push(@text,"{\\up6 #{\\footnote \\pard\\plain{\\up6 #} $WH_topic}}\n"); push(@text,"{\\up6 K{\\footnote \\pard\\plain{\\up6 K} @tmptext}}\n"); #> Print the keywords for Docname on the first available opportunity if ( $Keyword_dn_DocName ne "" ) { push(@text, "$Keyword_dn_DocName\n"); $Keyword_dn_DocName = ""; } $Keywords{$WH_topic} = @tmptext; } } # #> Generate_ID: Generate unique ID numbers with context string #> Parsed: Context String, Text #> sub Generate_ID { local( $WH_context, *tmptext) = @_; local( @characters, $operator, $value); # allow the user to override the automatic stuff if ( defined($USER_WH_context) ) { $value=&convert_context($USER_WH_context); $WH_context=&convert_context(@tmptext); } if ( ! $skiptags{$State{PgfTag}} ) { $operator = 1; @characters = split(//, $WH_context); if ( !defined($USER_WH_context) ) { foreach (@characters) { $value = $value + (ord($_) * $operator); $operator = $operator + 2; } # MOD zero is illegal $value=1 if ($value == 0); $value = 9393931%$value; if ($fixup_duplicates) { while ( $Context_ID{$value} ) { warn "Duplicate Context ID:$value String:$string\n"; $value++; } } } $WH_topic_comments{$value} = "@tmptext"; $WH_context_ids{$value} = $WH_context; } } ############## # # tchrists' assert stuff # sub assert { &panic("ASSERTION BOTCHED: $_[0]",$@) unless eval $_[0]; } sub panic { select(STDERR); print "\npanic: @_"; exit 1 if $] <= 4.003; # caller broken # stack traceback stolen from perl debugger local($i,$_); local($p,$f,$l,$s,$h,$a,@a,@sub); for ($i = 1; ($p,$f,$l,$s,$h,$w) = caller($i); $i++) { @a = @DB'args; for (@a) { if (/^StB\000/ && length($_) == length($_main{'_main'})) { $_ = sprintf("%s",$_); } else { s/'/\\'/g; s/([^\0]*)/'$1'/ unless /^-?[\d.]+$/; s/([\200-\377])/sprintf("M-%c",ord($1)&0177)/eg; s/([\0-\37\177])/sprintf("^%c",ord($1)^64)/eg; } } $w = $w ? '@ = ' : '$ = '; $a = $h ? '(' . join(', ', @a) . ')' : ''; push(@sub, "$w&$s$a from file $f line $l\n"); last if $signal; } for ($i=0; $i <= $#sub; $i++) { last if $signal; print $sub[$i]; } # kill 'TERM', -$Start_Pid; exit 1; } r"}; $ret=''; $ret.="F:$SavedState{'Family'} "; $ret.="S:$SavedState{'fs'} "; $ret.="W:$SavedState{'Weight'} "; $ret.="A:$SavedState{'Angle'} "; $ret.="C:$SavedState{'Color'}"; ##print STDERR "SAVE: $ret\n"; } sub restore_char_format{ local($ret); &mini_reset(); if ($State{"Family"} ne $SavedState{"Family"}) { # $ret .= &change_attr("f", &insdf-2.001/bin/dos/004075500042570001753000000000000672243774000134715ustar00iancmtr00000400000236sdf-2.001/bin/dos/sdf2rtf.bat010064400042570001753000000001140614606737000155220ustar00iancmtr00000400000236@echo off call sdf -o -dmif %1 call mif2rtf -o %1.rtf %1.out del %1.out sdf-2.001/bin/dos/sdf2hlp.bat010064400042570001753000000001320614606735400155140ustar00iancmtr00000400000236@echo off call sdf -o -dmif -thlp %1 call mif2rtf -m help -o %1.rtf %1.out del %1.out sdf-2.001/bin/dos/sdf.bat010064400042570001753000000000670647623412200147300ustar00iancmtr00000400000236@echo off perl %sdfbin%%0 %1 %2 %3 %4 %5 %6 %7 %8 %9 sdf-2.001/bin/dos/mkpldocs.bat010064400042570001753000000000670647624263000157730ustar00iancmtr00000400000236@echo off perl %sdfbin%%0 %1 %2 %3 %4 %5 %6 %7 %8 %9 sdf-2.001/bin/dos/sdf2mif.bat010064400042570001753000000000440614606736400155070ustar00iancmtr00000400000236@echo off call sdf -omif -dmif %1 sdf-2.001/bin/dos/pod2sdf.bat010064400042570001753000000000670647624263000155200ustar00iancmtr00000400000236@echo off perl %sdfbin%%0 %1 %2 %3 %4 %5 %6 %7 %8 %9 sdf-2.001/bin/dos/sdfcli.bat010064400042570001753000000000670647624263200154250ustar00iancmtr00000400000236@echo off perl %sdfbin%%0 %1 %2 %3 %4 %5 %6 %7 %8 %9 sdf-2.001/bin/dos/mif2rtf.bat010064400042570001753000000000670647623442400155320ustar00iancmtr00000400000236@echo off perl %sdfbin%%0 %1 %2 %3 %4 %5 %6 %7 %8 %9 sdf-2.001/bin/dos/sdfget.bat010064400042570001753000000000670647623442400154350ustar00iancmtr00000400000236@echo off perl %sdfbin%%0 %1 %2 %3 %4 %5 %6 %7 %8 %9 sdf-2.001/bin/dos/sdngen.bat010064400042570001753000000000670647624263200154370ustar00iancmtr00000400000236@echo off perl %sdfbin%%0 %1 %2 %3 %4 %5 %6 %7 %8 %9 sdf-2.001/bin/dos/prn2ps.bat010064400042570001753000000000670647624263000154030ustar00iancmtr00000400000236@echo off perl %sdfbin%%0 %1 %2 %3 %4 %5 %6 %7 %8 %9 sdf-2.001/bin/dos/sdfbatch.bat010064400042570001753000000000670647624263200157370ustar00iancmtr00000400000236@echo off perl %sdfbin%%0 %1 %2 %3 %4 %5 %6 %7 %8 %9 sdf-2.001/bin/dos/sdfapi.bat010064400042570001753000000000670647624263200154270ustar00iancmtr00000400000236@echo off perl %sdfbin%%0 %1 %2 %3 %4 %5 %6 %7 %8 %9 sdf-2.001/bin/dos/poddiff.bat010064400042570001753000000000670647624263000155720ustar00iancmtr00000400000236@echo off perl %sdfbin%%0 %1 %2 %3 %4 %5 %6 %7 %8 %9 sdf-2.001/bin/sdngen010075500042570001753000000214020661420536500141000ustar00iancmtr00000400000236#!/usr/local/bin/perl # $Id$ $VERSION{'PUBLIC'} = '2.000'; $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: SDF Tuning File Generator # # >>Copyright:: # Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 18-Jan-97 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # {{CMD:sdngen}} extracts SDF template information from a [[FrameMaker]] # template. # # >>Description:: # !SDF_OPT_STD # # The -p option can be used to specify the root paragraph format from # which others are derived. The default paragraph root is {{Body}}. # # The -f option can be used to specify the root font (i.e. phrase) format # from which others are derived. The default font root is {{Emphasis}}. # # The -t option can be used to specify the root table format from # which others are derived. The default table root is {{Format A}}. # # As formats often appear in families (e.g. Heading1, Heading2, # etc.), {{sdngen}} will use the (alphabetically) previous format as # the parent if it makes a better parent (i.e. there are less differences) # than the default one. # # If a template already exists, it can be specified using the -e option. # In this case, {{sdngen}} will get as much information as it can from # that file including: # # * the root format for each type # * the order of formats within a type # * the parent for each format. # # Within each type, formats which are unknown in the existing template # are output after those that are known. # # >>Examples:: # To generate an SDF tuning file file: # # V: sdngen -osdn mytemplate.mif # # This will create a template file called {{FILE:mytemplate.sdn}}. # # >>Limitations:: # require "sdf/app.pl"; require "sdf/parse.pl"; require "sdf/tomif.pl"; ########## Initialisation ########## # define configuration %app_config = ( 'libdir', 'sdf/home', ); # define options push(@app_option, ( #'Name|Spec|Help', 'para_root|STR;Body|default parent for a paragraph format', 'font_root|STR;Emphasis|default parent for a font format', 'tbl_root|STR;Format A|default parent for a table format', 'existing_template|STR|existing template file', )); # handle options &AppInit('file ...', 'generate an SDF template from a Frame one', 'SDF') || &AppExit(); # initialise the lookup tables loaded when a template already exists %objects = (); %parents = (); # if a template already exists, get as many details as we can from it if ($existing_template ne '') { # Open the file unless(open(EXISTING, $existing_template)) { &AppExit("fatal", "unable to open existing template '$existing_template'"); } # Scan the template for useful information while () { next unless /^\s*\!targetobject\s+/; ($type, $name, $parent) = split(/\s*\;\s*/, $'); $type =~ s/^\s*["']//; $type =~ s/["']\s*$//; $name =~ s/^\s*["']//; $name =~ s/["']\s*$//; $parent =~ s/^\s*["']//; $parent =~ s/["']\s*$//; # Save the information $parents{$type,$name} = $parent; if ($objects{$type} eq '') { $objects{$type} = $name; $para_root = $name if $type eq 'Para'; $font_root = $name if $type eq 'Phrase'; $tbl_root = $name if $type eq 'Table'; } else { $objects{$type} .= "\000$name"; } } close(EXISTING); } ########## Support routines ########## sub ConvertCatalogToSdf { local($type, $root, *catalog, *known_objects, *known_parents, *my_attr_list) = @_; # local(); local(@names, @known_names, %known, @ordered_names); local(@attr_list); local(%root_attrs); local($name, $parent, %attrs, %parent_attrs); local($prev, %prev_attrs); local(%prev_diff, %root_diff, %this_diff); local($prev_diff_cnt, $root_diff_cnt); local($obj_cnt, $attr_cnt, $diff_cnt, $diff_avg); # Check that the catalog is not empty @names = sort keys %catalog; $obj_cnt = scalar(@names); unless ($obj_cnt) { &AppMsg("object", "NO $type formats found"); return; } # Check that the root object exists if (!defined($catalog{$root})) { &AppMsg("warning", "root $type '$root' not found (using '$names[0]' instead)"); $root = shift(@names); } # Get the attributes of the root object %root_attrs = &_MifAttrSplit($catalog{$root}); # Output the root print "# Define the root '$type' format\n"; &OutputTargetObject($type, $root, '', *root_attrs); # Decide on the attribute list to use @attr_list = @my_attr_list ? @my_attr_list : sort keys %root_attrs; # If there are known objects, output them first @known_names = split(/\000/, $known_objects{$type}); if (@known_names) { %known = (); grep($known{$_}++, @known_names); @ordered_names = @known_names; for $name (@names) { push(@ordered_names, $name) unless $known{$name}; } } else { @ordered_names = @names; } # Analyse and output the non-root formats print "\n# Define the other '$type' formats\n"; %prev_attrs = (); $prev = ''; $diff_cnt = 0; for $name (@ordered_names) { # Skip the root next if $name eq $root; # If the list includes names from an existing template, # the object might not exist in the catalog, so skip it next if $catalog{$name} eq ''; # Get the attributes %attrs = &_MifAttrSplit($catalog{$name}); # Get the parent and the attribute differences $parent = $known_parents{$type,$name}; if ($parent ne '') { %parent_attrs = &_MifAttrSplit($catalog{$parent}); %this_diff = &DiffAttrs(*attrs, *parent_attrs, *attr_list); } else { # Decide on the best parent %root_diff = &DiffAttrs(*attrs, *root_attrs, *attr_list); %prev_diff = &DiffAttrs(*attrs, *prev_attrs, *attr_list); $root_diff_cnt = scalar(keys %root_diff); $prev_diff_cnt = scalar(keys %prev_diff); if ($root_diff_cnt < $prev_diff_cnt) { $parent = $root; %this_diff = %root_diff; } else { $parent = $prev; %this_diff = %prev_diff; } } # Output the object &OutputTargetObject($type, $name, $parent, *this_diff); # Collect some stats $diff_cnt += scalar(keys %this_diff); } continue { # Save away the previous attributes and name %prev_attrs = %attrs; $prev = $name; } # Output some basic stats $attr_cnt = scalar(@attr_list); $diff_avg = sprintf("%.1f", $diff_cnt/($obj_cnt - 1)); &AppMsg("object", "$obj_cnt $type formats, $attr_cnt attrs each," . " average difference is $diff_avg"); } sub OutputTargetObject { local($type, $name, $parent, *attrs) = @_; # local(); local($attr, $value); # Print the macro header $parent = " \"$parent\"" if $parent ne ''; print "!targetobject \"$type\"; \"$name\";$parent"; # Print the attributes, if any for $attr (sort keys %attrs) { $value = &FormatValue($attrs{$attr}); print "; \\\n $attr=$value"; } print "\n\n"; } sub FormatValue { local($value) = @_; local($result); # Integers and enumerated values are fine as is # Values with " are enclosed in '', otherwise # the value is enclosed in "". if ($value =~ /^\d+$/ || $value =~ /^[A-Z][a-z]+$/) { return $value; } elsif ($value =~ /["\\]/) { return "'$value'"; } else { return '"' . $value . '"'; } } sub DiffAttrs { local(*nv1, *nv2, *name_list) = @_; local(%diff); local($name); # Check the empty set first return %nv1 unless %nv2; # Find the differences %diff = (); for $name (@name_list) { $diff{$name} = $nv1{$name} unless $nv1{$name} eq $nv2{$name}; } # Return result return %diff; } ########## Processing ########## sub argProcess { local($ARGV) = @_; # local(); # Fetch the template unless (&_MifFetchTemplate($ARGV)) { &AppMsg("abort", "unable to fetch MIF template '$ARGV'"); return; } # Convert the MIF catalogs into an SDF template &ConvertCatalogToSdf('Para', $para_root, *_mif_tpl_paras, *objects, *parents, *MIF_PARA_ATTRS); &ConvertCatalogToSdf('Phrase', $font_root, *_mif_tpl_fonts, *objects, *parents, *MIF_FONT_ATTRS); &ConvertCatalogToSdf('Table', $tbl_root, *_mif_tpl_tbls, *objects, *parents); } &AppProcess('argProcess'); &AppExit(); sdf-2.001/bin/sdfcli010075500042570001753000000112760661420536500140760ustar00iancmtr00000400000236#!/usr/local/bin/perl # $Id$ $VERSION{'PUBLIC'} = '2.000'; $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: Command Line Interface Utility # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 29-Feb-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # {{CMD:sdfcli}} extracts command line interface (CLI) information from # applications and formats it into [[SDF]]. # # >>Description:: # !SDF_OPT_STD # # {{CMD:sdfcli}} executes each argument with a -h flag and converts # the resultant output to nicely formatted [[SDF]]. An argument of "-" # specifies that the help should be read from standard input. # # Formatting is done as follows: # # ^ lines are tagged as {{Example}} paragraphs, with the # first line formatted to wrap option usage specifications nicely # + if a line is found that starts with 'options:', it is replaced # with a {{Body}} paragraph saying "The options are:", and the # following lines are formatted as a table of codes and descriptions # + if a line is found that starts with 'aliases:', it is replaced # with a {{Body}} paragraph saying "The aliases are:", and the # following lines are formatted as a table of names and descriptions # + each option code in the table is formatted as a hypertext # jump to a tag called {{cmd_opt}} where: # # - {{cmd}} is the command name # - {{opt}} is the option code # # The -w option specifies at what column to wrap option specifications. # The default is 50 - this is the best for output imported into the # [[Mincom]] templates. # # >>Limitations:: # The table formats used are hard coded. # # >>Resources:: # # >>Implementation:: # require "sdf/app.pl"; ########## Initialisation ########## # define configuration %app_config = ( 'libdir', 'sdf/home', ); # define options push(@app_option, ( #'Name|Spec|Help', 'wrap|INT;50|column at which to wrap option specifications', )); # handle options &AppInit('utility ...', "format a utility's command line interface into SDF", 'SDF') || &AppExit(); ########## Processing ########## sub argProcess { local($ARGV) = @_; # local(); local(@help, $line, $spec, $length, @option_specs); local($code, $desc); local($base); # Get the help for this utility, unless given already in STDIN if ($ARGV eq "-") { @help = ; } else { unless (open(HELP, "$ARGV -h|")) { &AppMsg("abort", "failed to execute '$ARGV'"); return; } @help = ; close(HELP); } # Nicely wrap option specifications on the first line @option_specs = split(/\] /, shift(@help)); $spec = shift(@option_specs); print "E:$spec"; $length = length($spec); while ($spec = shift(@option_specs)) { if ($length + length($spec) < $wrap) { print "] $spec"; $length += length($spec) + 2; } else { print "]\nE: $spec"; $length = length($spec) + 9; } } # Get the command name $base = (&NameSplit($ARGV))[1]; # Format the rest while ($line = shift(@help)) { if ($line =~ /^options:/) { print "\nThe options are:\n\n"; print "!block table; format=28\n"; print "Option:Description\n"; while ($_ = shift(@help)) { if (/^aliases:/) { unshift(@help, $_); last; } elsif (/^\s*$/) { print $_; } else { # strip the long option name & format ($code, $desc) = /^-(\w), --\w+\s+(.*)$/; print "{{N[jump='#${base}_$code']-$code}}:$desc\n"; } } print "!endblock\n"; } elsif ($line =~ /^aliases:/) { print "\nThe aliases are:\n\n"; print "!block table; format=28\n"; print "Alias:Description\n"; while ($_ = shift(@help)) { if (/^options:/) { unshift(@help, $_); last; } elsif (/^\s*$/) { print $_; } else { ($code, $desc) = /^\+(\w+)\s+(.*)$/; print "$code:$desc\n"; } } print "!endblock\n"; } else { print "E:$line"; } } } &AppProcess('argProcess'); &AppExit(); sdf-2.001/bin/sdfapi010075500042570001753000000120420661420536500140700ustar00iancmtr00000400000236#!/usr/local/bin/perl # $Id$ $VERSION{'PUBLIC'} = '2.000'; $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: API Extraction Utility # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 29-Feb-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # {{CMD:sdfapi}} extracts {{Application Programming Interface}} information # from ([[Perl]]) source code. # # >>Description:: # !SDF_OPT_STD # # The format of the output can be controlled using the -f option. # Supported formats are {{std}} and {{concise}}. The default is {{std}}. # {{std}} format is: # # E:require "abc.pl"; # E: # E:$myvar = ... # E: # E:$result = # E:&myfunc($myparams); # # {{concise}} format has fewer blank lines and uses 1 line per symbol. # # A comma-separated list of symbol types to output can be specified # using the -s option. Supported symbol types are: # # * {{sub}} - subroutines # * {{var}} - variables # # The default is to extract all symbols. # # The -p option is used to extract only a subset of the symbols. # If not supplied, the pattern is symbols beginning with a letter. # If supplied without an option, the pattern defaults to all symbols. # If perl libraries use the coding convention that symbols beginning # with underscore are private, then -p_ can be used to extract the # private symbols. # # The -j option can be used to request SDF-style hypertext jumps # be added for each symbol. The jump target is {{lib_sym}} where: # # * {{lib}} is the library name # * {{sym}} is the symbol name. # # >>Limitations:: # The only language currently supported is [[Perl]]. # # It would be useful to extract messages from the scripts too. # This would require a new utility called {{sdfmsg}} say, # which searched through the source (including libraries) for # {{Y:AppMsg}} and {{Y:AppExit}} calls. # # Internally, it may be better to implement formats via routines. # This would give better control over output. e.g. it would be up to # the routine to decide if it wanted to output the 'require' header. # # >>Resources:: # # >>Implementation:: # require "sdf/app.pl"; require "sdf/apiperl.pl"; ########## Initialisation ########## # Table of formatting tags # (update %PERLIF_RULE if you change this) @PERLIF_FMT = ('std', 'concise'); # Tables of formatting rules. Each format needs 3 rules: # # * var - variable format # * proc - routine with no result (i.e. procedure) # * func - routine with result (i.e. function). # %PERLIF_RULE = ( "std.var", '"${prefix}$name = ...\n\n"', "std.proc", '"${prefix}$name($params);\n\n"', "std.func", '"$result =\n${prefix}$name($params);\n\n"', "concise.var", '"${prefix}$name = ...\n"', "concise.proc", '"${prefix}$name($params);\n"', "concise.func", '"$result = ${prefix}$name($params);\n"', ); # define configuration %app_config = ( 'libdir', 'sdf/home', ); # define options push(@app_option, ( #'Name|Spec|Help', 'fmt_tag|STR-@PERLIF_FMT;std|output format tag', 'pattern|STR;^[A-Za-z];|only symbols matching pattern', 'sym_type|STRLIST-("sub","var")|only symbols of these types', 'jumps|BOOL|add SDF-style hypertext jumps from each symbol', )); # handle options &AppInit('file ...', 'extract the API from a (perl) library', 'SDF') || &AppExit(); ########## Processing ########## sub argProcess { local($perl_file) = @_; # local(); # Fetch File ($ok_perl, @perl) = &PerlFetch($perl_file); unless ($ok_perl) { &AppMsg('abort', "error fetching perl file '$perl_file'"); return; } # Get perl symbols @symbol = &PerlSymbols(*perl, $pattern, @sym_type); # Find longest strings (optionally used in routine formatting) $max_name = 0; $max_result = 0; $max_params = 0; for $symbol (@symbol) { ($sym_type, $name, $result, $params) = split(/:/, $symbol); next unless $sym_type eq 'sub'; $len = length($name); $max_name = $len if $len > $max_name; $len = length($result); $max_result = $len if $len > $max_result; $len = length($params); $max_params = $len if $len > $max_params; } # Output the header unless a subset requested if (scalar(@sym_type) == 0) { ($dir, $base, $ext) = &NameSplit($perl_file); printf "require \"%s\";\n\n", &NameJoin('', $base, $ext); } # Output symbols for $symbol (@symbol) { ($sym_type, $name, $result, $params) = split(/:/, $symbol); if ($sym_type eq 'sub') { $sym_type = $result ? 'func' : 'proc'; $prefix = '&'; } else { $name =~ s/^(.)//; $prefix = $1; } $action = $PERLIF_RULE{"$fmt_tag.$sym_type"}; if ($jumps) { $action =~ s/\$name/{{N[jump='#\${base}_\$name']\$name}}/; } print eval $action; } } &AppProcess('argProcess'); &AppExit(); sdf-2.001/bin/sdfget010075500042570001753000000230310671643537500141070ustar00iancmtr00000400000236#!/usr/local/bin/perl # $Id$ $VERSION{'PUBLIC'} = '2.000'; $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: Documentation Extraction Utility # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 29-Feb-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # {{CMD:sdfget}} extracts documentation embedded in source code. # # >>Description:: # !SDF_OPT_STD # # The -f option can be used to specify a filename to use when # formatting the output. This is useful when the text is coming from # the standard input stream. # # The {{get-rule}} nominates the formatting of the embedded # documentation to be extracted. All currently defined get-rules # assume the documentation is in comment blocks in one of the # following formats: # # V: >>section_title1:: # V: text of section 1, line 1 # V: text of section 1, line .. # V: # V: >>section_title2:: # V: text of section 2, line 1 # V: text of section 2, line .. # V: >>END:: # V: # V: >>section_title3:: text of section 3 # # The first form is most commonly used. In this format, the text # in a section extends until the end of the current "comment block" # or the start of the next section, whichever comes first. The # second form (i.e. explicitly specifying where the section ends) is # useful if you wish to add some normal comments (i.e. non-documentation) # which you do not want extracted. If the text is short, the # third form can be used. Regardless of the format, if a section # is found which is already defined, the text of the section is # concatenated onto the existing text. This permits the documentation # for each entity to be specified immediately above where it is # defined in the source code. # # The -g option specifies the {{get-rule}} to use. # The available get-rules differ on the prefix expected at the front # of each line as shown below. # # !block table # Rule Prefix # perl # # cpp // # c * or /* # fortran c (with 5 preceding spaces) # eiffel -- # bat rem # !endblock # # Within C code, a trailing space is required after the characters above. # For other languages, a trailing space is optional. # Within FORTRAN code, the "c" character must be preceded by exactly # 5 spaces. For other languages, zero or more whitespace characters are # permitted before the characters above. # # For example, embedded documentation within C code looks like: # # V: /* >>Purpose:: # V: * This library provides a high level interface # V: * to commonly used network services. # V: */ # # If the -g option is not specified, # {{perl}} is the default get-rule. If the -g option is specified # without a parameter, the extension in lowercase of the filename # (or the {{formatting filename}} if the text is coming from standard input) # is used to guess the get_rule as shown below. # # !block table # Rule Extensions # cpp cpp, c++, cc, hpp, hpp, h, java, idl # c c # fortran fortran, for, f77, f # eiffel eiffel, ada # bat bat, cmd # !endblock # # A report filename can be specified using the -r option. # If the name doesn't include an extension, sdg is assumed. # Reports provide a mechanism for: # # * selectively extracting sections, and # * rudimentary reformatting (e.g. to [[SDF]]) # # If no report is specified, all sections are output in the # following format: # # V: section_title1 # V: section_text1 # V: # V: section_title2 # V: section_text2 # # If -r is specified on its own, {{FILE:default.sdg}} is assumed. # This report selects the set of sections (within the [[SDF]] # documentation standards) which form the user documentation and # formats them into [[SDF]]. # Details on the report format are specified below. # Reports are searched for in the current directory, # then in the {{stdlib}} directory within SDF's library directory. # # The -s option can be used to specify the scope of the documentation # to be extracted. (This is an experimental feature and may change # so most users should avoid using it.) # # The -i option outputs only those lines which the get-rule did # not match. This option is useful for extracting non-documentation # from a file to give just the code. # # Note: The -r option is ignored if -i is specified. # # The -v option enables verbose mode. This is useful for seeing # which rule is being used for each file. # # >>Examples:: # # To extract the user documentation from a [[SDF]] application # written in C++ ({{CMD:xyz}}, say) and save it into {{FILE:xyz.sdf}}: # # V: sdfget -gcpp -r -osdf xyz.cpp # # >>Resources:: # # >>Limitations:: # It would be nicer if the get-rule was always guessed from the # filename extension but changing the default from perl could # break existing scripts. Therefore, get-rule guessing must be # explicitly enabled by specifging the -g option without a # parameter. # # >>Implementation:: # require "sdf/app.pl"; require "sdf/dict.pl"; require "sdf/sdfget.pl"; ########## Initialisation ########## # # >>_Description:: # {{Y:_SDFGET_RULES}} is the lookup table used to guess the get_rule. # The key is the (lowercase) filename extension and the # value is the get_rule to use. If a get_rule isn't specified and # the filename extension isn't in this table, the get_rule is assumed # to be 'perl'. # %_SDFGET_RULES = ( 'cpp', 'cpp', 'c++', 'cpp', 'cc', 'cpp', 'hpp', 'cpp', 'h', 'cpp', 'java', 'cpp', 'idl', 'cpp', 'c', 'c', 'fortran', 'fortran', 'for', 'fortran', 'f77', 'fortran', 'f', 'fortran', 'eiffel', 'eiffel', 'ada', 'eiffel', 'bat', 'bat', 'cmd', 'bat', ); # # >>_Description:: # {{@_GET_RULES}} contains a table of {{get-rule}} definitions. # Each rule is defined by the fields in the table below. # # !block table # Field Description # Name rule name # Begin regular expression matching the start of a key # Sep regular expression matching the end of the key # End regular expression matching the end of a description # Prefix regular expression matching the start of each line # Desc description # !endblock # @_GET_RULES = &TableParse ( 'Name Begin Sep End Prefix Desc', 'perl >> ::\s* >>END:: \s*#[ ]? Perl/Shell source code', 'cpp >> ::\s* >>END:: \s*\/\/[ ]? C++ source code', 'c >> ::\s* >>END:: \s*\/?\*[ ] C source code', 'fortran >> ::\s* >>END:: [ ]{5}c[ ]? FORTRAN source code', 'eiffel >> ::\s* >>END:: \s*\-\-[ ]? Eiffel/Ada source code', 'table >> ::\s* >>END:: \s*\/\*[ ]? Mincom TP table files', 'bat >> ::\s* >>END:: \s*rem[ ]? batch source code', ); # Index into the rules table - we don't mind duplicates @_get_rules_dupl = (); %_GET_RULES_INDEX = &TableIndex(*_GET_RULES, *_get_rules_dupl, 'Name'); @_RULE_IDS = keys %_GET_RULES_INDEX; push(@_RULE_IDS, '-'); # valid scope values @_SDFGET_SCOPE = ('PUBLIC','PROTECTED','PRIVATE'); # define configuration %app_config = ( 'libdir', 'sdf/home', ); # define options push(@app_option, ( #'Name|Spec|Help', 'formatting_filename|STR|filename to use when formatting the output', 'get_rule|STR-@_RULE_IDS;perl;-|rule to use to get documentation', 'rpt_file|STR;;default.sdg|report file', 'scope|STR-@_SDFGET_SCOPE;PUBLIC|scope of documentation to be extracted', 'inverse|BOOL|only output lines not extracted', 'verbose|INT;;1|verbose mode', )); # handle options &AppInit('file ...', 'extract documentation embedded in source code', 'SDF') || &AppExit(); # Initialise trace levels $app_trace_level{"user"} = $verbose if $verbose > $app_trace_level{"user"}; # If supplied, fetch the report file. @report = (); if ($rpt_file) { local($rpt, $rpt_dir); my $rpt_ext = (&NameSplit($rpt_file))[2]; $rpt_file = &NameJoin('', $rpt_file, 'sdg') if $rpt_ext eq ''; $rpt_dir = "$app_lib_dir/stdlib"; unless ($rpt = &NameFind($rpt_file, ".", $rpt_dir)) { &AppExit('fatal', "cannot find report-file '$rpt_file'"); } ($all_ok, @report) = &TableFetch($rpt); $all_ok || &AppExit('fatal', "error opening report-file '$rpt': $!"); } ########## Processing ########## sub argProcess { local($ARGV) = @_; # local(); local($success, $buflistref); local($level) = 0; # Get the file extension my $filename = $ARGV eq '-' ? $formatting_filename : $ARGV; my $ext = (&'NameSplit($filename))[2]; # Use the current file extension to guess the rule, if necessary my $rule = $get_rule; if ($rule eq '-') { $rule = $_SDFGET_RULES{"\L$ext"} || 'perl'; &AppTrace("user", 1, "derived get_rule for filename '$ARGV' is '$rule'"); } # Get the rule parameters my %rule = &TableLookup(*_GET_RULES, *_GET_RULES_INDEX, $rule); # Fetch the data ($success, $buflistref) = &DictFetch($ARGV, $rule{"Begin"}, $rule{"Sep"}, $rule{"End"}, $rule{"Prefix"}); return 1 unless $success; # Print report if ($inverse) { print grep(! /^$rule{"Prefix"}$/, @dict_rest); } else { # Patch $ARGV to the formatting filename if requested $ARGV = $formatting_filename if $formatting_filename ne ''; &DictPrint(STDOUT, 0, 'main', $buflistref, @report); } } &AppProcess('argProcess'); &AppExit(); sdf-2.001/bin/prn2ps010075500042570001753000000044760661420555300140610ustar00iancmtr00000400000236#!/usr/local/bin/perl # $Id$ $VERSION{'PUBLIC'} = '2.000'; $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: PostScript Conversion Utility # # >>Copyright:: # Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 18-Jul-97 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # {{CMD:prn2ps}} converts Windows PostScript to Unix PostScript. # The input to this program is typically generated by printing # to a PostScript printer connected to the FILE: logical device. # The output can be converted to Encapsulated PostScript using # GhostScript's {{CMD:p2epsi}} program. # # >>Description:: # !SDF_OPT_STD # # For each input file, the output is generated by: # # * deleting the {{PageSize}} information # * deleting the control-D at the end of the file. # # >>Limitations:: # If {{CMD:ps2epsi}} doesn't like the output, you may need to # use another printer driver to generate the input. # On Windows NT 4.0, the {{Canon PS-IPU Color Laser Copier v52.3}} # driver works most of the time. # # >>Examples:: # To generate an Encapsulated PostScript file from Windows PostScript: # # > prn2ps -ops myfig.prn # > ps2epsi myfig.ps # # >>Implementation:: # require "sdf/app.pl"; ########## Initialisation ########## # define configuration %app_config = ( 'libdir', 'sdf/home', ); # define options #push(@app_option, ( # #'Name|Spec|Help', #)); # handle options &AppInit('prn_file ...', "convert Windows PostScript to Unix PostScript", 'SDF') || &AppExit(); ########## Processing ########## sub argProcess { my($ARGV) = @_; # my(); local($_); # Open the input unless (open(FILE, $ARGV)) { &AppMsg("abort", "failed to open '$ARGV'"); return; } # Generate the output my $end = ''; while () { if ($end) { $end = '' if /^\Q$end/; next; } elsif (index($_, '%%BeginFeature: *PageSize') == 0) { $end = '%%EndFeature'; next; } next if /^\004/; # Ignore the terminating ^D print; } close(FILE); } &AppProcess('argProcess'); &AppExit(); sdf-2.001/bin/Makefile.PL010064400042570001753000000002570647263711000146520ustar00iancmtr00000400000236 use ExtUtils::MakeMaker; WriteMakefile( NAME => 'SDF::bin', EXE_FILES => [ qw( fm2ps mif2rtf pod2sdf poddiff prn2ps sdf sdfapi sdfbatch sdfcli sdfget sdngen ) ], ); sdf-2.001/bin/mkpldocs010075500042570001753000000012440647623231200144360ustar00iancmtr00000400000236#!/usr/local/bin/perl use File::Find; # Check the usage unless (@ARGV) { print "usage: mkplhtml all\n"; print " or mkplhtml dir1 ...\n"; exit 1; } # Traverse the directories my @dirs = $ARGV[0] eq 'all' ? ('ext', 'lib', 'pod', 'vms', 'utils') : @ARGV; find(\&wanted, @dirs); # Build the catalog print "building the catalog...\n"; system("sdf -2html catalog"); # Convert each .pm and .pod file sub wanted { if (/\.(pm|pod)$/ || $File::Find::dir eq 'utils' && /\.PL$/) { my $depth = scalar(split(/\//, $File::Find::dir)); print "$File::Find::name (depth: $depth)\n"; system("sdf -2html -cperl -DPERL_DIR_DEPTH=$depth $_"); } } sdf-2.001/bin/pod2sdf010075500042570001753000000017540647623231200141710ustar00iancmtr00000400000236#!/usr/local/bin/perl use Pod::Sdf; use strict; # Get the options, if any my %param = (); if ($ARGV[0] eq '-m') { $param{'main'} = 1; shift; } # Check the usage unless (scalar(@ARGV) == 1) { print "usage: pod2sdf [-m] infile > outfile\n"; exit 1; } # Load the pod into an array my $infile = shift; open(INFILE, $infile) || die "unable to open '$infile': $!\n"; my @pod = ; chop(@pod); # Convert it to SDF and output it my @sdf = pod2sdf(\@pod, \%param); print join("\n", @sdf), "\n"; 1; __END__ =head1 NAME pod2sdf - converts POD to SDF markup =head1 SYNOPSIS pod2sdf [-m] infile > outfile =head1 DESCRIPTION B should be used when one wants to use SDF instead of POD as the base documentation format. B does this convertion on the fly for C<*.pod, *.pl, *.pm> files for you. So B is only needed when one wants to make extensive use of the powerful features of SDF and marking them with C<=begin sdf> and C<=end sdf> gets inconvenient. =cut sdf-2.001/bin/fm2ps010055500042570001753000000223730661420536500136570ustar00iancmtr00000400000236#!/usr/local/bin/perl # $Id$ $VERSION{'PUBLIC'} = '2.000'; $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: Batch Processing Utility # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 29-Feb-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # {{CMD:sdfbatch}} is a preprocessor for {{CMD:fmbatch}}, # [[FrameMaker]]'s command-line driven batch processing utility. # # >>Description:: # Given a set of [[FrameMaker]] documents, {{CMD:sdfbatch}} can be used to: # # * change the formatting of the documents (ala {{Use Formats From}}) # * update the documents (i.e. cross-references, etc.) # * print the documents # * save the documents in a nominated file format # # !SDF_OPT_HELP # # To change formatting, use the -f option to specify the file # to import the formats from. The -F option can be used to # specify what formats are imported. The argument to the -F # option is a set of the characters in the table below. # # !block table; format=28 # Character Meaning # p Paragraph formats # f Font formats # l Page layouts # c Cross references # v Variables # r Reference page contents # t Table formats # x Conditional text # k Color # m math # B Preserve manual page breaks # O Preserve other formatting overrides # !endblock # # By default, all formats are imported. # # To update documents, use the -u option. # # To print documents, use the -p option. If a parameter is not provided, # the file will be printed to the default printer. To print to a # [[PostScript]] file, specify the "file" keyword as the parameter. # Alternatively, the parameter is the name of a {{print settings}} file. # # When generating a [[PostScript]] file, the paper size can be specified # using the -P option. The default value is {{global}}. The paper size # name is actually mapped to a {{print settings}} file called # {{paper_size}}.{{fmver}} in the {{FILE:stdlib}} library directory. # {{fmver}} is typically either fm4 or fm5, depending on which version # of FrameMaker you are using. # # To save documents, use the -s option. By default, this saves each file. # To change the extension, supply an argument to the -s option. # # To specify a different format, use the -S option. Possible # values are: # # * m - MIF # * a - line-oriented ASCII # * t - paragraph-oriented ASCII # * d - Frame document # * l - View-Only Frame document # * - - file's current format [default] # # Take care with the file extension - any existing files will be # replaced without warning. # # The -n option causes the generated {{CMD:fmbatch}} file to be output. # i.e. fmbatch is not called. This option is useful for debugging. # # The -t option enables the user to tune the time-out used when # waiting for the print driver to generate a PostScript file. # The default value is 300 seconds (i.e. 5 minutes). # # A combination of the f, u, p and s options can be supplied if more # that one operation is required per file. For example, you may # wish to import formats and then save the resultant file. For # each file, the operations are always done in the following order: # # ^ formatting # + updating # + printing # + saving # # Note: Not all of the values documented for the -F and -S options # may be supported in Frame versions before 4.0 and additional # values may be supported in future versions. As such, the # values supplied to these options are simply embedded in the # generated {{CMD:sdfbatch}} file. i.e. no checking is done on the value. # This behaviour is considered a feature. # # >>Examples:: # # To format and print a set of files: # # V: sdfbatch -fmyfmts.doc -p *.doc # # To convert mif files to binary files: # # V: sdfbatch -sdoc -Sd *.mif # # To copy Frame variables from a file to a set of files: # # V: sdfbatch -fvariable.mif -Fv -s *.doc # # >>Limitations:: # # >>Resources:: # # >>Implementation:: # require "sdf/app.pl"; ########## Initialisation ########## # define configuration %app_config = ( 'inifile', 'sdfbatch.ini', 'libdir', 'sdf/home', ); # define options @app_option = @app_option_core; push(@app_option, ( #'Name|Spec|Help', 'fmt_file|STR|formats file', 'fmt_what;F|STR|formats to import', 'update_doc|BOOL|update documents', 'print_doc|STR;;-|print documents', 'paper_size;P|STR;global|paper size name', 'save_ext|STR;;-|save extension', 'save_fmt;S|STR;-|save file format', 'no_action|BOOL|output the batch file (instead of calling fmbatch)', 'timeout|INT;300|timeout for printer driver to generate ps', )); # setup default values for: # * the path of the Frame executables # * the fmbatch command to use # * the FrameMaker extension to use # * the temporary file #$fmhome = $ENV{'FMHOME'} ? $ENV{'FMHOME'} : "/usr/frame"; $fmbatch = "fmbatch -i"; $fmext = "fm5"; $tmp_file = "/tmp/sdfbatch$$"; # ini-file handler sub iniProcess { local($fname, *data) = @_; # local(); local($section, %values); for $section (sort keys %data) { if ($section eq 'Frame') { %values = &AppSectionValues($data{$section}); $fmbatch = $values{'fm_batch'} if $values{'fm_batch'} ne ''; $fmext = $values{'fm_ext'} if $values{'fm_ext'} ne ''; delete $data{$section}; } else { delete $data{$section}; } } } # handle options &AppInit('frame_file ...', 'generate fmbatch input file', 'SDF', 'iniProcess') || &AppExit(); # set up print settings file, if any if ($print_doc && $print_doc ne '-') { if ($print_doc eq 'file') { $prt_file = "$app_lib_dir/stdlib/$paper_size.$fmext"; } else { $prt_file = $print_doc; } } # This is the set of filenames collected during argument processing @doc_files = (); ########## Argument Processing ########## sub argProcess { local($doc_file) = @_; # local(); push(@doc_files, $doc_file); push(@batch, "Open \"$doc_file\""); if ($fmt_file) { push(@batch, "UseFormatsFrom $fmt_what \"$doc_file\" \"$fmt_file\""); } if ($update_doc) { push(@batch, "Update \"$doc_file\""); } if ($print_doc) { if ($prt_file) { push(@batch, "Print \"$doc_file\" \"$prt_file\""); } else { push(@batch, "Print \"$doc_file\""); } } if ($save_ext) { if ($save_ext eq '-' && $save_fmt eq '-') { push(@batch, "Save \"$doc_file\""); } elsif ($save_ext eq '-') { $new_file = $doc_file; push(@batch, "SaveAs $save_fmt \"$doc_file\" \"$new_file\""); } else { $new_file = &NameSubExt($doc_file, $save_ext); push(@batch, "SaveAs $save_fmt \"$doc_file\" \"$new_file\""); } } push(@batch, "Quit \"$doc_file\""); # return result return 0; } ########## Main Program ########## # Build the batch file @batch = (); push(@batch, "Open \"$fmt_file\"") if $fmt_file; push(@batch, "Open \"$prt_file\"") if $prt_file; &AppProcess('argProcess'); push(@batch, "Quit \"$fmt_file\"") if $fmt_file; push(@batch, "Quit \"$prt_file\"") if $prt_file; # If requested, output the batch file if ($no_action) { printf "%s\n", join("\n", @batch); } # Otherwise, pass it to fmbatch for execution else { # call fmbatch unless (open(FMBATCH, "|$fmbatch > $tmp_file")) { &AppExit("fatal", "failed to pipe data to fmbatch"); } printf FMBATCH "%s\n", join("\n", @batch); # clean up close(FMBATCH); if ($? || $debug) { unless (open(TMPFILE, $tmp_file)) { &AppExit("app_warning", "unable to open tmp file '$tmp_file'"); } else { print ; close(TMPFILE); } } unlink($tmp_file); # Rename the ps files, if necessary if ($print_doc eq 'file' && $fmext ne 'fm4') { for $doc_file (@doc_files) { &RenamePS($doc_file); } } } # Exit the program &AppExit(); ########## Support Routines ########## # Signam handler for alarms $timed_out = 0; sub handle_alarms { $timed_out = 1; } # Rename a PostScript file from the form xx.out.ps to the form xx.ps. # {{base_ext}} is the orginal filename without the ps (e.g. xx.out). sub RenamePS { local($base_ext) = @_; # local(); local($base, $ext); local($old_name, $new_name); # Get the filenames if ($base_ext =~ /\.(\w+)$/) { $base = $`; $ext = $1; } else { $base = $base_ext; $ext = ''; } $old_name = "$base_ext.ps"; $new_name = "$base.ps"; # Setup the alarm handler for RenamePS timeouts $timed_out = 0; $SIG{'ALRM'} = 'handle_alarms'; alarm($timeout); # Wait until the print driver has finished, if necessary unless (-f $old_name) { print STDERR "waiting for '$old_name' to finish printing\n"; until (-f $old_name) { last if $timed_out; sleep(1); print STDERR "."; } print STDERR "\n"; } # Rename the file, if possible if ($timed_out) { &AppMsg("app_warning", "'$old_name' not found after $timeout seconds"); } else { rename($old_name, $new_name) || &AppMsg("app_warning", "unable to rename '$old_name' to '$new_name':$!"); } } sdf-2.001/bin/sdfbatch010075500042570001753000000223730661420536500144100ustar00iancmtr00000400000236#!/usr/local/bin/perl # $Id$ $VERSION{'PUBLIC'} = '2.000'; $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: Batch Processing Utility # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 29-Feb-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # {{CMD:sdfbatch}} is a preprocessor for {{CMD:fmbatch}}, # [[FrameMaker]]'s command-line driven batch processing utility. # # >>Description:: # Given a set of [[FrameMaker]] documents, {{CMD:sdfbatch}} can be used to: # # * change the formatting of the documents (ala {{Use Formats From}}) # * update the documents (i.e. cross-references, etc.) # * print the documents # * save the documents in a nominated file format # # !SDF_OPT_HELP # # To change formatting, use the -f option to specify the file # to import the formats from. The -F option can be used to # specify what formats are imported. The argument to the -F # option is a set of the characters in the table below. # # !block table; format=28 # Character Meaning # p Paragraph formats # f Font formats # l Page layouts # c Cross references # v Variables # r Reference page contents # t Table formats # x Conditional text # k Color # m math # B Preserve manual page breaks # O Preserve other formatting overrides # !endblock # # By default, all formats are imported. # # To update documents, use the -u option. # # To print documents, use the -p option. If a parameter is not provided, # the file will be printed to the default printer. To print to a # [[PostScript]] file, specify the "file" keyword as the parameter. # Alternatively, the parameter is the name of a {{print settings}} file. # # When generating a [[PostScript]] file, the paper size can be specified # using the -P option. The default value is {{global}}. The paper size # name is actually mapped to a {{print settings}} file called # {{paper_size}}.{{fmver}} in the {{FILE:stdlib}} library directory. # {{fmver}} is typically either fm4 or fm5, depending on which version # of FrameMaker you are using. # # To save documents, use the -s option. By default, this saves each file. # To change the extension, supply an argument to the -s option. # # To specify a different format, use the -S option. Possible # values are: # # * m - MIF # * a - line-oriented ASCII # * t - paragraph-oriented ASCII # * d - Frame document # * l - View-Only Frame document # * - - file's current format [default] # # Take care with the file extension - any existing files will be # replaced without warning. # # The -n option causes the generated {{CMD:fmbatch}} file to be output. # i.e. fmbatch is not called. This option is useful for debugging. # # The -t option enables the user to tune the time-out used when # waiting for the print driver to generate a PostScript file. # The default value is 300 seconds (i.e. 5 minutes). # # A combination of the f, u, p and s options can be supplied if more # that one operation is required per file. For example, you may # wish to import formats and then save the resultant file. For # each file, the operations are always done in the following order: # # ^ formatting # + updating # + printing # + saving # # Note: Not all of the values documented for the -F and -S options # may be supported in Frame versions before 4.0 and additional # values may be supported in future versions. As such, the # values supplied to these options are simply embedded in the # generated {{CMD:sdfbatch}} file. i.e. no checking is done on the value. # This behaviour is considered a feature. # # >>Examples:: # # To format and print a set of files: # # V: sdfbatch -fmyfmts.doc -p *.doc # # To convert mif files to binary files: # # V: sdfbatch -sdoc -Sd *.mif # # To copy Frame variables from a file to a set of files: # # V: sdfbatch -fvariable.mif -Fv -s *.doc # # >>Limitations:: # # >>Resources:: # # >>Implementation:: # require "sdf/app.pl"; ########## Initialisation ########## # define configuration %app_config = ( 'inifile', 'sdfbatch.ini', 'libdir', 'sdf/home', ); # define options @app_option = @app_option_core; push(@app_option, ( #'Name|Spec|Help', 'fmt_file|STR|formats file', 'fmt_what;F|STR|formats to import', 'update_doc|BOOL|update documents', 'print_doc|STR;;-|print documents', 'paper_size;P|STR;global|paper size name', 'save_ext|STR;;-|save extension', 'save_fmt;S|STR;-|save file format', 'no_action|BOOL|output the batch file (instead of calling fmbatch)', 'timeout|INT;300|timeout for printer driver to generate ps', )); # setup default values for: # * the path of the Frame executables # * the fmbatch command to use # * the FrameMaker extension to use # * the temporary file #$fmhome = $ENV{'FMHOME'} ? $ENV{'FMHOME'} : "/usr/frame"; $fmbatch = "fmbatch -i"; $fmext = "fm5"; $tmp_file = "/tmp/sdfbatch$$"; # ini-file handler sub iniProcess { local($fname, *data) = @_; # local(); local($section, %values); for $section (sort keys %data) { if ($section eq 'Frame') { %values = &AppSectionValues($data{$section}); $fmbatch = $values{'fm_batch'} if $values{'fm_batch'} ne ''; $fmext = $values{'fm_ext'} if $values{'fm_ext'} ne ''; delete $data{$section}; } else { delete $data{$section}; } } } # handle options &AppInit('frame_file ...', 'generate fmbatch input file', 'SDF', 'iniProcess') || &AppExit(); # set up print settings file, if any if ($print_doc && $print_doc ne '-') { if ($print_doc eq 'file') { $prt_file = "$app_lib_dir/stdlib/$paper_size.$fmext"; } else { $prt_file = $print_doc; } } # This is the set of filenames collected during argument processing @doc_files = (); ########## Argument Processing ########## sub argProcess { local($doc_file) = @_; # local(); push(@doc_files, $doc_file); push(@batch, "Open \"$doc_file\""); if ($fmt_file) { push(@batch, "UseFormatsFrom $fmt_what \"$doc_file\" \"$fmt_file\""); } if ($update_doc) { push(@batch, "Update \"$doc_file\""); } if ($print_doc) { if ($prt_file) { push(@batch, "Print \"$doc_file\" \"$prt_file\""); } else { push(@batch, "Print \"$doc_file\""); } } if ($save_ext) { if ($save_ext eq '-' && $save_fmt eq '-') { push(@batch, "Save \"$doc_file\""); } elsif ($save_ext eq '-') { $new_file = $doc_file; push(@batch, "SaveAs $save_fmt \"$doc_file\" \"$new_file\""); } else { $new_file = &NameSubExt($doc_file, $save_ext); push(@batch, "SaveAs $save_fmt \"$doc_file\" \"$new_file\""); } } push(@batch, "Quit \"$doc_file\""); # return result return 0; } ########## Main Program ########## # Build the batch file @batch = (); push(@batch, "Open \"$fmt_file\"") if $fmt_file; push(@batch, "Open \"$prt_file\"") if $prt_file; &AppProcess('argProcess'); push(@batch, "Quit \"$fmt_file\"") if $fmt_file; push(@batch, "Quit \"$prt_file\"") if $prt_file; # If requested, output the batch file if ($no_action) { printf "%s\n", join("\n", @batch); } # Otherwise, pass it to fmbatch for execution else { # call fmbatch unless (open(FMBATCH, "|$fmbatch > $tmp_file")) { &AppExit("fatal", "failed to pipe data to fmbatch"); } printf FMBATCH "%s\n", join("\n", @batch); # clean up close(FMBATCH); if ($? || $debug) { unless (open(TMPFILE, $tmp_file)) { &AppExit("app_warning", "unable to open tmp file '$tmp_file'"); } else { print ; close(TMPFILE); } } unlink($tmp_file); # Rename the ps files, if necessary if ($print_doc eq 'file' && $fmext ne 'fm4') { for $doc_file (@doc_files) { &RenamePS($doc_file); } } } # Exit the program &AppExit(); ########## Support Routines ########## # Signam handler for alarms $timed_out = 0; sub handle_alarms { $timed_out = 1; } # Rename a PostScript file from the form xx.out.ps to the form xx.ps. # {{base_ext}} is the orginal filename without the ps (e.g. xx.out). sub RenamePS { local($base_ext) = @_; # local(); local($base, $ext); local($old_name, $new_name); # Get the filenames if ($base_ext =~ /\.(\w+)$/) { $base = $`; $ext = $1; } else { $base = $base_ext; $ext = ''; } $old_name = "$base_ext.ps"; $new_name = "$base.ps"; # Setup the alarm handler for RenamePS timeouts $timed_out = 0; $SIG{'ALRM'} = 'handle_alarms'; alarm($timeout); # Wait until the print driver has finished, if necessary unless (-f $old_name) { print STDERR "waiting for '$old_name' to finish printing\n"; until (-f $old_name) { last if $timed_out; sleep(1); print STDERR "."; } print STDERR "\n"; } # Rename the file, if possible if ($timed_out) { &AppMsg("app_warning", "'$old_name' not found after $timeout seconds"); } else { rename($old_name, $new_name) || &AppMsg("app_warning", "unable to rename '$old_name' to '$new_name':$!"); } } sdf-2.001/bin/sdf010075500042570001753000000520200672214532300133730ustar00iancmtr00000400000236#!/usr/local/bin/perl # $Id$ $VERSION{'PUBLIC'} = '2.001'; $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: SDF Conversion Utility # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 29-Feb-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # {{CMD:sdf}} converts [[SDF]] files to other document formats. # # >>Description:: # !SDF_OPT_STD # # The -2 option is a convenient way of specifying the alias (collection # of options) which generates the output you want. e.g. # # V: sdf -2html abc # # is equivalent to: # # V: sdf +sdf2html abc # # The -D option is used to define variables. These are typically # used for controlling conditional text and substituting text which # changes. The format used is: # # V: -Dvariable1=value1,variable2=value2 # # A flag is a shorthand way of specifying variables in the DOC family. # i.e. -ftoc=3 is equivalent to -DDOC_TOC=3. # The format of the -f option is: # # V: -fflag1=value1,flag2=value2 # # If a variable or flag is specified without a value, 1 is assumed. # # To generate [[HTML]] topics, the command is: # # V: sdf -2topics abc # # By default, this will create sub-topics for each heading already in a # separate file. It will also {{autosplit}} level 1 headings into sub-topics. # The -n option can be used to control which level headings are split at: # # * 1 autosplits on level 1 headings (the default) # * 2 autosplits on level 2 headings # * 3 autosplits on level 3 headings # * 0 disables autosplitting. # # Include files are searched for in the current directory, # then in the directories given by the -I option, # then in the default library directory. # # By default, {{CMD:sdf}} is configured to {{prefilter}} files with # certain extensions. For example: # # V: sdf mytable.tbl # # is equivalent to executing {{CMD:sdf}} on a file which only contains: # # V: !include "mytable.pl"; table # # The -p option can be used to explicitly prefilter files or to # override the default prefilter used. If a parameter is not provided, # the prefilter is assumed to be {{table}}. # # The -a option can be used to specify parameters for the prefilter. # For example: # # V: sdf -aformat='15,75,10' mytable.tbl # # The -P option prefilters the input files as programming languages. # The parameter is the language to use. If none is provided, the # extension is assumed to be the language name. For example: # # V: sdf -P myapp.c # # is equivalent to executing {{CMD:sdf}} on a file which only contains: # # V: !include "myapp.c"; example; wide; lang='c' # # The -N option adds line numbers at the frequency given. # The default frequency is 1. i.e. every line. # # The -g option prefilters the input files by executing {{CMD:sdfget}} # using the default report (default.sdg). To change the report used, # specify the report name as the parameter. # If the report name doesn't include an extension, sdg is assumed. # # Note: {{CMD:sdfget}} searches for reports in the current directory, # then in the {{stdlib}} directory within SDF's library directory. # # The -r option runs the nominated SDR report on each input before formatting. # In other words, SDR reports provide a mechanism for: # # * analysing the SDF just before it would be formatted, and # * replacing that SDF with the output of the report (also SDF) # so that the final output is a nicely formatted report. # # For example, the {{sdf_dir}} report generates a directory (tree) of # the components (files) included in an SDF document. # Reports are stored in {{sdr}} files and are searched for using the # usual rules. # # The -L option can be used to specify a {{locale}}. # The default locale name is specified in F. # Locale naming follows POSIX conventions (i.e. language_country), so # the locale name for American english is {{en_us}}. # The information for each locale is stored in the F directory, # so you'll need to have to look in there to see what locales are # available. (As the default locale can be set in F, this # isn't as ugly as it first sounds.) # # Note: At the moment, a locale file simply contains a list of language # specific strings. Ultimately, it should be extended to # support localisation of date and time formats. # # The -k option is used to specify a {{look}}. # The default look library is specified in {{FILE:sdf.ini}}. # # The -s option can be used to specify a document {{style}}. # Typical values are: # # * {{document}} - a technical document # * {{memo}} - a memo # * {{fax}} - a facsimile # * {{minutes}} - minutes of a meeting. # # The -S option is used to specify the page size. # Values supported include: # # !block table # Name Width Height Comment # global 21.0cm 11.0in will fit on either A4 or letter # A3 29.7cm 42.0cm # A4 21.0cm 29.7cm # A5 14.8cm 21.0cm # B4 25.7cm 36.4cm # B5 17.6cm 25.0cm # letter 8.5in 11.0in # legal 8.5in 14.0in # tabloid 11.0in 17.0in # !endblock # # Additional page sizes can be configured in {{FILE:sdf.ini}}. # To specify a rotated version of a named page size, append an {{R}}. # For example, A4R implies a width of 29.7cm and a height of 21cm. # A custom page size can also be specified using the format: # # V: {{width}}x{{height}} # # where {{width}} and {{height}} are the respective sizes in points. # # The -c option is used to specify a configuration library. # # A list of modules to use can be specified via the -u option. # # The initial heading level to start on can be specified via # the -H option. This is useful if you want to preview how a # topic will be displayed without regenerating the complete document. # If a topic begins with a level 1 heading (e.g. H1) and you wish to # format it as a document (i.e. the level 1 text becomes the DOC_NAME # for {{MAC:build_title}}), use the -H option with a value of 0. # # The look of headings can also be adjusted. By default, H-style # headings are numbered, A-style headings are lettered and P-style # headings are plain. To force a particular style for all headings, # the -K option can be used. Sensible parameter values are H, A and P # although other values may work depending on what paragraph styles # are configured at your site. # # The -d option is used to specify the format driver. # Values supported include: # # * {{expand}} - format as expanded text (the default) # * {{mif}} - Maker Interchange Format # * {{pod}} - Plain Old Documentation (as used by [[Perl]]). # # Additional drivers can be configured in {{FILE:sdf.ini}}. # # The -y option can to used to specify a post-filter. # # The -z option can be used to specify a list of post-processing # actions you want to execute on each output file after it is # generated. The actions supported include: # # * {{ps}} - generate PostScript # * {{doc}} - generate a Frame (binary) file # * {{fvo}} - generate a Frame View-Only file # * {{txt}} - generate a text file # * {{rtf}} - generate an RTF file # * {{clean}} - delete the output file (must be last). # # Additional actions can be configured in {{FILE:sdf.ini}}. # By convention, the generated files are given the same names # as the action keywords. # # The -t option is used to specify the logical target format. # If none is specified, the default is the first post processing # action, if any. Otherwise, the default is the format driver name. # # The -v option enables verbose mode. This is useful for debugging # problems related to post processing. In particular, post processing # actions containing the pattern {{clean}} are skipped in verbose mode. # You can also switch off the post processing messages by using a # verbose value of -1. Values higher than 1 switch on additional # trace messages as follows: # # . 2 - show how names of files and libraries are resolved # . 3 - show the directories searched for libraries # . 4 - show the directories searched for modules # . 5 - show the directories searched for normal files. # # The -T option can be used to switch on # debug tracing. The parameter is a comma-separated list of name-value # pairs where each name is a {{tracing group}} and each value is the # level of tracing for that group. To get the trace output provided # by the -v option, one can use the {{user}} group like this: # # > sdf -Tuser=2 ... # # This is slightly different from the -v option in that intermediate # files are not implicitly kept. Additional tracing groups will be # added over time (probably one per output driver). # # The -w option is used to specify the width for text-based outputs. # # The -z, -D, -f and -I options are list options. i.e. multiple values # can be separated by commas and/or the options can be supplied # multiple times. # # >>Examples:: # # Convert {{FILE:mydoc.sdf}} to a technical document in mif format, # output is {{FILE:mydoc.mif}}: # # V: sdf -2mif mydoc.sdf # # Convert {{FILE:mydoc.sdf}} to online documentation in {{PRD:FrameViewer}} # format, output is {{FILE:mydoc.fvo}}: # # V: sdf -2fvo mydoc.sdf # # Convert {{FILE:mydoc.sdf}} to online documentation in HTML, # output is {{FILE:mydoc.html}}: # # V: sdf -2html mydoc.sdf # # The following command will build the reference documentation # for a SDF module in HTML: # # V: sdf -2html abc.sdm # # >>Limitations:: # Many of the default post processing (-z) actions only works on [[Unix]] as # [[FrameMaker]] for [[Windows]] does not support batch conversion. # # Topics mode has several limitations: # * only documents in the current directory can be converted # * all sub-topics must also be in the current directory. # # >>Resources:: # # >>Implementation:: # require "sdf/app.pl"; require "sdf/parse.pl"; ########## Initialisation ########## # define configuration %app_config = ( 'inifile', 'sdf.ini', 'libdir', 'sdf/home', ); # Table of format mappings %format_mappings = (); # routine for handling the 2 option sub MyToAlias { local($arg) = @_; my $alias = $format_mappings{$arg} || $arg; &AppMsg("app", "formatting using '$alias'") if $verbose; unshift(@ARGV, "+sdf2$alias"); } # define options push(@app_option, ( #'Name|Spec|Help', 'format;2|ROUTINE-MyToAlias;|the output format you want', 'variable;D|STRHASH|define variables', 'split_level;n|INT|heading level to autosplit into topics', 'flag|STRHASH|define flags (i.e. DOC_* variables)', 'include_path;I|STRLIST|search path for include files, templates, etc.', 'prefilter|STR;;table|pre-filter input file from each argument', 'parameters;a|STR|parameters for the pre-filter', 'plang;P|STR;;-|pre-filter as a programming language', 'line_numbers;N|INT;;1|number lines in pretty-printed source code', 'get_report|STR;;default|pre-filter using sdfget with the report specified', 'report|STR|report to run on the SDF to transform it before formatting', 'locale;L|STR|locale', 'look;k|STR|look library', 'style|STR|style of document', 'page_size;S|STR|page size for paper documents', 'config|STR|configuration library', 'uses|STRLIST|modules to use', 'head_level;H|INT|initial heading level', 'head_look;K|STR|heading look (H, A or P)', 'driver|STR;expand|format driver - default is expand', 'post_filter;y|STR|filter to post-filter the output with', 'post_process;z|STRLIST|list of post processing actions to do', 'target|STR|logical target format', 'verbose|INT;;1|verbose mode', 'trace_levels;T|STRHASH|debugging trace levels', 'width|INT|width for text-based outputs', 'library_path;Y|STRLIST|search path for libraries', )); # configuration tables %prefilter_for = (); %post_processing = (); %predefined_vars = (); # ini-file handler sub iniProcess { local($fname, *data) = @_; # local(); local($section, @pagesizes, @prefilters, @drivers, @conversions); for $section (sort keys %data) { if ($section eq 'Frame') { %values = &AppSectionValues($data{$section}); $sdf_fmext = $values{'fm_ext'}; delete $data{$section}; } elsif ($section eq 'PageSizes') { @pagesizes = &TableParse(split(/\n/, $data{$section})); &SdfLoadPageSizes(@pagesizes); delete $data{$section}; } elsif ($section eq 'PreFilters') { @prefilters = &TableParse(split(/\n/, $data{$section})); &LoadPreFilters(@prefilters); delete $data{$section}; } elsif ($section eq 'Drivers') { @drivers = &TableParse(split(/\n/, $data{$section})); &SdfLoadDrivers(@drivers); delete $data{$section}; } elsif ($section eq 'PostProcessing') { %post_processing = &AppSectionValues($data{$section}); delete $data{$section}; } elsif ($section eq 'Variables') { %predefined_vars = &AppSectionValues($data{$section}); delete $data{$section}; } elsif ($section eq 'FormatMappings') { %format_mappings = &AppSectionValues($data{$section}); delete $data{$section}; } elsif ($section eq 'Conversions') { @conversions = &TableParse(split(/\n/, $data{$section})); &NameLoadConversionRules(*conversions, $verbose); delete $data{$section}; } } } # Prefilter validation rules @_PREFILTER_RULES = &TableParse( 'Field Category', 'Name key', 'Aliases optional', ); # This routine loads the prefilters sub LoadPreFilters { local(@data) = @_; # local(); local(@fld, $rec, %value); local($name, $alias); # Validate the table &TableValidate(*data, *_PREFILTER_RULES); # Process the prefilter table @fld = &TableFields(shift(@data)); for $rec (@data) { %value = &TableRecSplit(*fld, $rec); $name = $value{'Name'}; $prefilter_for{$name} = $name; for $alias (split(/,/, $value{'Aliases'})) { $prefilter_for{$alias} = $name; } } } # handle options &AppInit('sdf_file ...', 'convert an sdf file to another format', 'SDF', 'iniProcess') || &AppExit(); # Initialise the tracing levels %app_trace_level = %trace_levels; $app_trace_level{"user"} = $verbose if $verbose > $app_trace_level{"user"}; # Initialise the SDF module to use the correct search paths @sdf_include_path = @include_path; @sdf_library_path = @library_path; $sdf_lib = $app_lib_dir; # Check the page size is defined or in the form width"x"height if ($page_size ne '') { unless ($sdf_pagesize{$page_size} || $page_size =~ /^[\d\.]+x[\d\.]+$/) { &AppExit("fatal", "page size '$page_size' not supported."); } } # Check the format driver is defined unless ($sdf_driver{$driver}) { &AppExit("fatal", "format driver '$driver' not supported."); } # Check the post processing actions are configured and define the # matching variables for $action (@post_process) { unless ($post_processing{$action}) { &AppExit("fatal", "post-processing '$action' not supported."); } $name = $action; $name =~ tr/a-z/A-Z/; $variable{"OPT_PP_$name"} = 1; } # Assign a default logical target, if necessary if ($target eq '') { $target = @post_process ? $post_process[0] : $driver; } # Make the predefined variables for $var (keys %predefined_vars) { $variable{$var} = $predefined_vars{$var}; } # Map flags to variables while (($flag, $value) = each %flag) { $flag =~ tr/a-z/A-Z/; $flag = "DOC_$flag"; $variable{$flag} = $value unless defined $variable{$flag}; } # When pretty-printing programming languages, 'listing' is the style used $style = 'listing' if $plang ne ''; # Map the key configuration options to variables $variable{'OPT_LOCALE'} = ($locale eq '.' ? '' : $locale) if $locale ne ''; $variable{'OPT_LOOK'} = ($look eq '.' ? '' : $look) if $look ne ''; $variable{'OPT_STYLE'} = ($style eq '.' ? '' : $style) if $style ne ''; $variable{'OPT_CONFIG'} = $config; $variable{'OPT_DRIVER'} = $driver; $variable{'OPT_TARGET'} = $target; $variable{'OPT_EXT'} = $out_ext; $variable{'OPT_NUMBER'} = $line_numbers; $variable{'OPT_REPORT'} = $report; $variable{'OPT_SPLIT_LEVEL'} = $split_level; $variable{'OPT_HEAD_LEVEL'} = $head_level; $variable{'OPT_HEAD_LOOK'} = $head_look; $variable{'OPT_PAGE_SIZE'} = $page_size if $page_size ne ''; $variable{'OPT_WIDTH'} = $width if $width ne ''; # Map other interesting things to variables. Note that we let the # user override these things on the command line if they want to. $variable{'SDF_VERSION'} = $app_product_version unless $variable{'SDF_VERSION'}; $variable{'SDF_HOME'} = $app_lib_dir unless $variable{'SDF_HOME'}; # When regression testing, make sure that version changes don't cause problems if ($variable{'SDF_TEST'}) { $variable{'SDF_VERSION'} = 'x.y'; } # When testing, '.' can be used to clear the look and/or style $look = '' if $look eq '.'; $style = '' if $style eq '.'; ########## Argument Processing ########## sub argProcess { local($ARGV) = @_; local($main_arg_err); local($msg_cursor, %msg_counts); local($new, @new); # If no output is nominated but post-processing is requested, # just do the post processing on the input files return 0 if @post_process && $out_ext eq ''; # Get the current message cursor $msg_cursor = &AppMsgNextIndex(); # Generate result @new = &GenerateDocument($ARGV); # Check for problems %msg_counts = &AppMsgCounts($msg_cursor); if ($msg_counts{'error'} || $msg_counts{'abort'} || $msg_counts{'fatal'} ) { return 1; } # Output result for $new (@new) { print "$new\n"; } return 0; } # This routine generates a document sub GenerateDocument { local($ARGV) = @_; local(@new); local($file_ext); local($filter, $module); local($lang); local($input_str); local($ok_sdf, @sdf_data); $file_ext = (&NameSplit($ARGV))[2]; # Handle programming language and sdfget pre-filtering if ($plang ne '') { $lang = $plang eq '-' ? $file_ext : $plang; $prefilter = "example; wide; pure; lang='$lang'"; } elsif ($get_report ne '') { $prefilter = "get; report='$get_report'"; } # Generate the SDF file if we're pre-filtering the input $filter = $prefilter ne '' ? $prefilter : $prefilter_for{$file_ext}; if ($filter ne '') { # When prefiltering pod, assume the main parameter if ($filter eq 'pod') { $filter .= "; main"; } $filter .= "; $parameters" if $parameters ne ''; @sdf_data = ( "!_bof_ '$ARGV'", "!include '$ARGV'; $filter", "!_eof_"); } # If we haven't built the SDF by now, fetch it from the file else { ($ok_sdf, @sdf_data) = &SdfFetch($ARGV); unless ($ok_sdf) { &AppMsg('abort', "error fetching sdf file '$ARGV'"); return (); } } # Generate and return the required format @new = &SdfConvert(*sdf_data, $driver, *uses, %variable); # Post filter the output, if requested if ($post_filter ne '') { &AppMsg("object", "'$post_filter' post filtering...") if $verbose >= 0; require "sdf/post_$post_filter.pl"; $fn = $post_filter . "_PostFilter"; @new = eval {&$fn(*new)}; &AppMsg('failed', $@) if $@; } # Return result return @new; } # This is called AFTER output streams have been closed for each argument sub argPostProcess { local($ARGV, $main_arg_err) = @_; # local(); local($action); # If an error occurred in the main processing routine or there # is nothing to do, just return return if $main_arg_err || scalar(@post_process) == 0; # Ensure the necessary variables are exported to the 'user' package # Note: If post-processing is the only thing requested, the output # extension is taken from the input filename $SDF_USER'short = (&NameSplit($ARGV))[1]; $SDF_USER'long = &NameJoin($out_dir, $SDF_USER'short, ''); $SDF_USER'out_ext = $out_ext eq '' ? (&NameSplit($ARGV))[2] : $out_ext; $SDF_USER'width = $SDF_USER'var{'OPT_WIDTH'}; $SDF_USER'title = $SDF_USER'var{'DOC_TITLE'}; $SDF_USER'title =~ s/['\\]/\\$&/g; $SDF_USER'project = $SDF_USER'var{'DOC_PROJECT'}; $SDF_USER'project =~ s/['\\]/\\$&/g; $SDF_USER'product = $SDF_USER'var{'DOC_PRODUCT'}; $SDF_USER'product =~ s/['\\]/\\$&/g; $SDF_USER'section = $SDF_USER'var{'DOC_SECTION'} || 1; # Do the post processing for $action (@post_process) { if (!defined($post_processing{$action})) { &AppExit("failed", "unknown special command '$action'"); } else { next if $verbose && $action =~ /clean/; &AppMsg("object", "'$action' post processing...") if $verbose >= 0; package SDF_USER; eval $'post_processing{$'action}; if ($@) { &'AppMsg('abort', "error in '$action' post processing: $@"); } } } } # switch back to the main package package main; ########## Main Program ########## &AppProcess('argProcess', 'argPostProcess', 'sdf'); &AppExit(); ses|STRLIST|modules to use', 'head_level;H|INT|initial heading level', 'head_look;K|STR|heading look (H, A or P)', 'driver|STR;expand|format driver - default is expand', 'post_filter;y|STR|filter to post-filter the output with', 'post_process;z|STRLIST|list of post processing actions to do', 'target|STR|logical target format', 'verbose|INT;;1|verbose mode', 'trace_levels;T|STRHASH|debugging trace levels', 'width|INT|width for text-based outputs', 'librsdf-2.001/bin/poddiff010075500042570001753000000016200647623231200142330ustar00iancmtr00000400000236#!/usr/local/bin/perl use Pod::Diff; use strict; my $USAGE = "usage: poddiff file1 file2\n" . " or poddiff file1 ... dir\n"; # Check the usage if (scalar(@ARGV) < 2) { print $USAGE; exit 1; } # Handle the directory case elsif (-d $ARGV[$#ARGV]) { my $dir = pop(@ARGV); my $file1; my $file2; my @diff; for $file1 (@ARGV) { $file2 = "$dir/$file1"; @diff = pod_diff_files($file1, $file2); print "$file1: " . scalar(@diff) . " paragraphs differ\n"; if (@diff) { print join("\n", @diff), "\n"; } } } # Handle the simple case elsif (scalar(@ARGV) == 2) { my @diff = POD::Diff::pod_diff_files(@ARGV); if (@diff) { print scalar(@diff) . " paragraphs differ\n"; print join("\n", @diff), "\n"; } } else { print $USAGE; exit 1; } # Print some statistics pod_diff_print_stats(\*STDOUT); sdf-2.001/doc/004075500042570001753000000000000672243774600127075ustar00iancmtr00000400000236sdf-2.001/doc/ref/004075500042570001753000000000000672243775200134605ustar00iancmtr00000400000236sdf-2.001/doc/ref/mdefault.html010064400042570001753000000035250672242533500161430ustar00iancmtr00000400000236 SDF 2.001: SDF Reference: default Macro

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog


6.8. default Macro

Interface

The general syntax is:

  !default name [value]

The arguments are:

Name Type Default Rule
name symbol    
value string 1  

See Understanding Macro Interfaces, if necessary.

Description

The default macro sets a variable if it does not already have a value.

Examples

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog

sdf-2.001/doc/ref/mclear.html010064400042570001753000000040140672242533000155720ustar00iancmtr00000400000236 SDF 2.001: SDF Reference: clear Macro

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog


6.6. clear Macro

Interface

The general syntax is:

  !clear [type]

The arguments are:

Name Type Default Rule
type string All <Left|Right|All>

See Understanding Macro Interfaces, if necessary.

Description

The clear macro resets text wrapping around a figure.

Examples

!import "mylogo"; align="right"
Some text.
!clear

Limitations & Future Directions

html is the only target which currently supports wrapping text around figures.

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog

sdf-2.001/doc/ref/macros/004075500042570001753000000000000672243775200147445ustar00iancmtr00000400000236sdf-2.001/doc/ref/macros/mperlapi.sdf010064400042570001753000000011370622022216000172240ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: perlapi Macro H2: Interface !macro_interface "perlapi" H2: Description The {{perlapi}} macro extracts the API of a Perl 4 library which follows SDF's coding conventions. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mclear.sdf010064400042570001753000000013220622022216200166540ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: clear Macro H2: Interface !macro_interface "clear" H2: Description The {{clear}} macro resets text wrapping around a figure. H2: Examples !block example !import "mylogo"; align="right" Some text. !clear !endblock H2: Limitations & Future Directions {{html}} is the only target which currently supports wrapping text around figures. sdf-2.001/doc/ref/macros/mend_top.sdf010064400042570001753000000011320622022216000172130ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: end_topic Macro H2: Interface !macro_interface "end_topic" H2: Description This macro marks the end of a topic. H2: Examples H2: Limitations & Future Directions Hopefully, this macro will disappear real soon now. sdf-2.001/doc/ref/macros/mmacro.sdf010064400042570001753000000010720622022216000166670ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: macro Macro H2: Interface !macro_interface "macro" H2: Description The {{macro}} macro marks the beginning of a user-defined macro. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mgetdoc.sdf010064400042570001753000000011430622022216000170320ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: getdoc Macro H2: Interface !macro_interface "getdoc" H2: Description The {{getdoc}} macro extracts embedded documentation from source code using the {{CMD:sdfget}} command. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mexport.sdf010064400042570001753000000013360622022216000171120ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: export Macro H2: Interface !macro_interface "export" H2: Description The {{export}} macro ensures that the target documentation system receives the value of the nominated variable each time it changes. If the variable is currently defined, the target system is immediately notified of its value. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/msubsect.sdf010064400042570001753000000016530635011350400172500ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 30-Aug-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: subsections Macro H2: Interface !macro_interface "subsections" H2: Description The {{subsections}} macro specifies the subsections in a topic. H2: Examples Typical usage is: E: H1: MyApp E: !subsections "Purpose,Usage,Description,Examples" In this case, the {{MAC:subsections}} macro changes the {{id}} generated for the headings listed to: E: MyApp - {{heading}} For HTML, it will also generate a line of jumps to the headings. H2: Limitations & Future Directions {{html}} is currently the only target for which a jump line is generated. sdf-2.001/doc/ref/macros/mblock.sdf010064400042570001753000000011510622022216000166560ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: block Macro H2: Interface !macro_interface "block" H2: Description The {{block}} macro marks the beginning of a "block" of text. The block is ended by the {{MAC:endblock}} macro. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mgetcli.sdf010064400042570001753000000011530622022216000170350ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: getcli Macro H2: Interface !macro_interface "getcli" H2: Description The {{getcli}} macro extracts the command-line interface for a script following SDF's command-line conventions. H2: Examples #H2: Limitations & Future Directions under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: getcli Macro H2: Interface !macro_interface "getcli" H2: Description The {{getcli}} macro extracts the command-line interface sdf-2.001/doc/ref/macros/mbuild_t.sdf010064400042570001753000000011300622022216000172030ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: build_title Macro H2: Interface !macro_interface "build_title" H2: Description The {{build_title}} macro create a title page or section for documents and papers. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mdefine.sdf010064400042570001753000000010540622022216000170200ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: define Macro H2: Interface !macro_interface "define" H2: Description The {{define}} macro sets a variable to a value. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/minit.sdf010064400042570001753000000011670622022216000165360ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: init Macro H2: Interface !macro_interface "init" H2: Description The {{init}} macro is used on the top line of a document to initialise variables before the configuration libraries are loaded. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mcontinu.sdf010064400042570001753000000025770635674110000172720ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 12-Feb-97 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: continued Macro H2: Interface !macro_interface "continued"; "id" H2: Description The {{continued}} macro continues a heading from a previous page, provided the target format is page-based, i.e. nothing is output for html or hlp formats. The first parameter is the heading style to repeat. The second parameter is the suffix to append the text from the repeated heading. The default suffix is ", E<2{>N:ContinuedE<2}>". H2: Examples A typical example is: !block example H2: Solving world peace H3: Procedure The steps are given below. ... !continued 'H2' !continued 'H3'; ' {{N:(Continued)}}' Some more procedure text. !endblock In the example above, the macros effectively produce: !block verbatim H2[notoc;noid;continued] Solving world peace, {{Continued}} H3[notoc;noid;continued] Procedure {{(N:Continued)}} !endblock Note: This macro does not cause a new page. Typically, a rule (i.e. event processing) is used to trigger new pages at the necessary paragraph styles. #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mclass.sdf010064400042570001753000000010520622022216000166710ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: class Macro H2: Interface !macro_interface "class" H2: Description The {{class}} macro declares a class of objects. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mdefault.sdf010064400042570001753000000011100622022216000172030ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: default Macro H2: Interface !macro_interface "default" H2: Description The {{default}} macro sets a variable if it does not already have a value. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mslide_d.sdf010064400042570001753000000011060622022216000171670ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: slide_down Macro H2: Interface !macro_interface "slide_down" H2: Description The {{slide_down}} macro moves subsequent headings down one level. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mimport.sdf010064400042570001753000000016620635016543600171250ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: import Macro H2: Interface !macro_interface "import" H2: Description The {{import}} macro imports a figure. If the filename is not given an extension, the extension is found using the search rules below. !block table When_generating The_search_order_is PostScript epsi, eps, wmf, mif, gif HTML jpeg, jpg, png, gif Windows Help bmp !endblock The {{title}} argument can be used to add a figure title. See {{Figures}} within the {{DOC:SDF User Guide}} for further details. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mon.sdf010064400042570001753000000017560632212052000162130ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: on Macro H2: Interface !macro_interface "on"; "id" H2: Description The {{on}} macro specifies a rule to execute on certain events. # Topics mode doesn't currently handle cross-document section jumps # so we need to explicitly specify the jump. :-( !if $var{'HTML_TOPICS_MODE'} || $var{'HTML_SUBTOPICS_MODE'} See {{A[jump=$var{'SDF_ROOT'}.'user/in_event.html'] Event Processing}} in the {{DOC:SDF User Guide}} for further details. !else See {{SECT[doc='SDF User Guide'] Event Processing}} in the {{DOC:SDF User Guide}} for further details. !endif H2: Examples To be completed ... #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/minsert.sdf010064400042570001753000000021740645304104600171100ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: insert Macro H2: Interface !macro_interface "insert" H2: Description The {{insert}} macro is used to insert the output of {{macro}} into an SDF document. {{missing}} determines the action if the macro isn't found: * {{ok}} - do nothing * {{warning}} - report a warning * {{error}} - report an error. Note: In early versions of SDF, this macro was used to call user-defined macros. In SDF 2.000 or later, user-defined macros can be called using the same syntax as built-in macros. H2: Examples !block example; lang='sdf' # Insert the text of macro XXX if it's defined !insert 'XXX' # Insert the text of macro XXX; output an error if it's not defined !insert 'XXX'; 'error' # Same as the previous example !XXX !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mif.sdf010064400042570001753000000010670622022216000161700ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: if Macro H2: Interface !macro_interface "if" H2: Description The {{if}} macro marks the beginning of a conditional text section. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/moff.sdf010064400042570001753000000017170632212052000163460ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: off Macro H2: Interface !macro_interface "off" H2: Description The {{off}} macro disables an event. # Topics mode doesn't currently handle cross-document section jumps # so we need to explicitly specify the jump. :-( !if $var{'HTML_TOPICS_MODE'} || $var{'HTML_SUBTOPICS_MODE'} See {{A[jump=$var{'SDF_ROOT'}.'user/in_event.html'] Event Processing}} in the {{DOC:SDF User Guide}} for further details. !else See {{SECT[doc='SDF User Guide'] Event Processing}} in the {{DOC:SDF User Guide}} for further details. !endif H2: Examples To be completed ... #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mslide_u.sdf010064400042570001753000000010760622022216000172160ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: slide_up Macro H2: Interface !macro_interface "slide_up" H2: Description The {{slide_up}} macro moves subsequent headings up one level. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mendif.sdf010064400042570001753000000010720622022216000166530ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: endif Macro H2: Interface !macro_interface "endif" H2: Description The {{endif}} macro marks the end of a conditional text section. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/muse.sdf010064400042570001753000000010410622022216000163560ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: use Macro H2: Interface !macro_interface "use" H2: Description The {{use}} macro loads a (library) module. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mendbloc.sdf010064400042570001753000000011530622022216000171740ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: endblock Macro H2: Interface !macro_interface "endblock" H2: Description The {{endblock}} macro marks the end of a "block" of text. The block is started by the {{MAC:block}} macro. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mcatalog.sdf010064400042570001753000000027760645640727400172420ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: catalog Macro H2: Interface !macro_interface "catalog" H2: Description The {{catalog}} macro build a catalog from objects already loaded. The {{class}} parameter specifies the class name. As it is defined as a symbol rather than a string type, the name is given without quotes and it is space-separated from the following parameter. The {{mask}} parameter can be used to filter the objects as shown below: !block table Mask Description empty string no filtering - display all objects cited display just the cited objects abc.* display the objects with (short) names matching the pattern, \ i.e. names beginning with abc xyz:abc display the objects where attribute {{xyz}} matches the \ pattern, i.e. {{xyz}} is exactly equal to {{abc}} !endblock Remaining parameters are passed through to the class filter. H2: Examples Display some interesting attributes of {{CLASS:references}} with a Status of 'Review': !block example !catalog references 'Status:Review'; compact; \ columns="PDF,2:Reference,DOC:Document,Version" !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mexecute.sdf010064400042570001753000000012470622022216000172340ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: execute Macro H2: Interface !macro_interface "execute" H2: Description The {{execute}} macro executes the nominated command and includes the output within the document. A filter may optionally be applied to the output before it is included. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/melse.sdf010064400042570001753000000010650622022216000165200ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: else Macro H2: Interface !macro_interface "else" H2: Description The {{else}} macro delimits sections within conditional text. H2: Examples #H2: Limitations & Future Directions an Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: else Macro H2: Interface !macro_interface "else" H2: Description The {{else}} macro delimits sections within conditional text.sdf-2.001/doc/ref/macros/melseif.sdf010064400042570001753000000011640622022216000170370ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: elseif Macro H2: Interface !macro_interface "elseif" H2: Description The {{elseif}} macro delimits sections within conditional text. It is identical in operation to the {{MAC:elsif}} macro. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/moutput.sdf010064400042570001753000000016370622022216200171370ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: output Macro H2: Interface !macro_interface "output" H2: Description The {{output}} macro dynamically changes the output file being used. It can be used in the following ways: ^ output "filename" + output ">filename" + output "-" The first form changes the output file to be filename. The second form appends the output onto the filename given. The third form closes the (current) output file, if any. H2: Examples To be completed... H2: Limitations & Future Directions {{html}} is the only target which currently supports this macro. sdf-2.001/doc/ref/macros/mscript.sdf010064400042570001753000000010650622022216000170740ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: script Macro H2: Interface !macro_interface "script" H2: Description The {{script}} macro executes a single line of Perl code. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mjumps.sdf010064400042570001753000000013720661461775300167560ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1998, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 25-Oct-98 ianc SDF 2.000beta1 # ----------------------------------------------------------------------- # H1: jumps Macro H2: Interface !macro_interface "jumps" H2: Description The {{jumps}} macro generates lines of jumps to headings. H2: Examples Typical usage is: E: !jumps "Purpose,Usage,,Description,Examples" This will create two jump lines: the first has {{Purpose}} and {{Usage}}; the second has {{Description}} and {{Examples}}. #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mline.sdf010064400042570001753000000011260622022216000165150ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: line Macro H2: Interface !macro_interface "line" H2: Description The line macro can be used to change the line number output within error and warning messages. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/minherit.sdf010064400042570001753000000012420622022216000172270ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: inherit Macro H2: Interface !macro_interface "inherit" H2: Description The {{inherit}} macro is used to inherit configuration information from a library. Typically, a library inherits from another library and then adds some new things. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mendmacr.sdf010064400042570001753000000010750622022216000172020ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: endmacro Macro H2: Interface !macro_interface "endmacro" H2: Description The {{endmacro}} macro marks the end of a user-defined macro. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mundef.sdf010064400042570001753000000010430622022216000166650ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: undef Macro H2: Interface !macro_interface "undef" H2: Description The {{undef}} macro undefines a variable. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/melsif.sdf010064400042570001753000000011620622022216000166700ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: elsif Macro H2: Interface !macro_interface "elsif" H2: Description The {{elsif}} macro delimits sections within conditional text. It is identical in operation to the {{MAC:elseif}} macro. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mmessage.sdf010064400042570001753000000011040622022216000172060ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: message Macro H2: Interface !macro_interface "message" H2: Description The {{message}} macro can be used to output messages during execution. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mgetcode.sdf010064400042570001753000000011060622022216000171760ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: getcode Macro H2: Interface !macro_interface "getcode" H2: Description The {{getcode}} macro extracts the "non-documentation" from source code. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/minclude.sdf010064400042570001753000000011110622022216000172030ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: include Macro H2: Interface !macro_interface "include" H2: Description The {{include}} macro is used to include another file into an SDF document. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/macros/mrestric.sdf010064400042570001753000000017160647527130400172660ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: restrict Macro H2: Interface !macro_interface "restrict" H2: Description The {{restrict}} macro declares a restricted family of variables. If a variable begins with a restricted prefix, then it must be declared via the {{FILT:define}} filter. This feature aims to catch errors caused by authors using a bad variable name. For example, if an author types E: !define DOC_NAMe "My Document" but meant to type E: !define DOC_NAME "My Document" then an error will be raised as DOC_NAMe is an unknown variable within the DOC family. H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/fcomment.html010064400042570001753000000030530672242517200161450ustar00iancmtr00000400000236 SDF 2.001: SDF Reference: comment Filter

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog


5.9. comment Filter

Interface

The general syntax is:

  !block comment[; parameters]
  ...
  !endblock

See Understanding Filter Interfaces, if necessary.

Description

The comment filter is used to temporarily ignore a block of text.

Examples

!block comment
Ignore me
!endblock

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog

sdf-2.001/doc/ref/fabout.html010064400042570001753000000045030672242515300156150ustar00iancmtr00000400000236 SDF 2.001: SDF Reference: about Filter

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog


5.2. about Filter

Interface

The general syntax is:

  !block about
  ...
  !endblock

See Understanding Filter Interfaces, if necessary.

Description

The about filter is used when including a topic as an "about" section within a document. Typically, this implies:

  • the headings are converted to plain headings and slid down one level
  • the headings (except those initially at level 1) are removed from the table of contents.

Examples

A typical book might look like this:

!init OPT_STYLE="manual"

!define DOC_NAME "A Sample Book"
!build_title

!include "myabout.sdf"; about
!include "chapter1.sdf"
!include "chapter2.sdf"
!include "chapter3.sdf"
!include "appendx1.sdf"; appendix

A typical about topic looks like this:

H1: About this manual

H2: Purpose

This manual provides information on ...

H2: Scope

This manual contains information on ...

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog

sdf-2.001/doc/ref/mgetcli.html010064400042570001753000000027500672242536300157660ustar00iancmtr00000400000236 SDF 2.001: SDF Reference: getcli Macro

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog


6.19. getcli Macro

Interface

The general syntax is:

  !getcli

See Understanding Macro Interfaces, if necessary.

Description

The getcli macro extracts the command-line interface for a script following SDF's command-line conventions.

Examples

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog

sdf-2.001/doc/ref/filters/004075500042570001753000000000000672243774700151345ustar00iancmtr00000400000236sdf-2.001/doc/ref/filters/fsection.sdf010064400042570001753000000017060645236431400174320ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: sections Filter H2: Interface !filter_interface "sections" H2: Description The {{sections}} filter is used to create section jumps for html and hlp outputs: for these formats, the text of each paragraph (excluding punctuation) is assumed to be the title of a section within this document. For other outputs, the text is unchanged. H2: Examples !block example; lang='sdf' There are lots of new things in this version including: !block sections . Topics mode . HTML headers and footers !endblock Further details are given below. !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fappendi.sdf010064400042570001753000000016340645234334400174060ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: appendix Filter H2: Interface !filter_interface "appendix" H2: Description The {{appendix}} filter is used when including a topic as an "appendix" section within a document, i.e. normal headings are converted to appendix headings. H2: Examples A typical book might look like this: !block example; lang='sdf' !init OPT_STYLE="manual" !define DOC_NAME "A Sample Book" !build_title !include "chapter1.sdf" !include "chapter2.sdf" !include "chapter3.sdf" !include "appendx1.sdf"; appendix !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fquote.sdf010064400042570001753000000013150622022216200171020ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: quote Filter H2: Interface !filter_interface "quote" H2: Description The {{quote}} filter is used to format a quotation. This typically implies: * for [[PostScript]], the text is italics and indented from both margins * for [[HTML]], the text is given an appropriate style. #H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fget.sdf010075500042570001753000000011530672210610600165350ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1999, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 24-May-99 ianc SDF 2.001 # ----------------------------------------------------------------------- # H1: get Filter H2: Interface !filter_interface "get" H2: Description The {{get}} filter is used to extract embedded documentation. The parameters map to the options for {{CMD:sdfget}}. #H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/flangdef.sdf010064400042570001753000000013600632212045200173470ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: langdefs Filter H2: Interface !filter_interface "langdefs" H2: Description The {{langdefs}} filter is used to configure programming language properties used by SDF's pretty-printing support. The contents is one or more {{CMD:vgrind}} definitions. H2: Examples See {{FILE:langdefs.sdm}} within SDF's {{FILE:stdlib}} directory. #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fend.sdf010064400042570001753000000017270645234404000165310ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: end Filter H2: Interface !filter_interface "end" H2: Description The {{end}} filter is used to add a section of SDF onto the end of the document. This is particularly useful in configuration files when you want to: * load a "exit" configuration module * provide defaults for variables not provided by authors within a document. When several sections are added to the end using this macro, the sections are processed in a first-in-last-out order. H2: Examples !block example; lang='sdf' !block end Line: N[align=Center] END OF DOCUMENT !endblock !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/ftopics.sdf010064400042570001753000000032140645236352000172610ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: topics Filter H2: Interface !filter_interface "topics" H2: Description The {{topics}} filter is used to include a set of sub-topics into a document. For [[PostScript]], this implies that the heading levels on topics included as sub-topics are adjusted accordingly. For [[HTML]] and Windows help files, this implies that hypertext jumps are inserted to the topics. This filter expects a table of data in {{FMT:TBL}} format. The only field typically provided is {{Topic}} - the name of the file containing the topic, excluding the {{.sdf}} extension. The other fields are used by SDF internally during the generation of HTML topics. The {{intro}} parameter can be used to specify SDF text to be output before the hypertext jumps. This text is not output for formats where the topics are simply included, e.g. PostScript. The {{noslide}} parameter stops the heading levels of the topics being slid down. The {{data}} parameter is used to specify that the table is topics data and no output should be generated. This parameter is used by SDF internally during the generation of HTML topics. H2: Examples !block example; lang='sdf' The subroutines are documented below. !block topics; intro='H2: Subroutines' Topic mysub1 mysub2 !endblock !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fnote.sdf010064400042570001753000000021370635016607000167260ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: note Filter H2: Interface !filter_interface "note" H2: Description The {{note}} filter is used to specify a note. The {{label}} parameter can be used to specify a label. The default label is "Note:". H2: Examples !block example !block note; label='Example:' And some text inside a multi-line note !endblock !endblock The result is: !block note; label='Example:' And some text inside a multi-line note !endblock If you want the label to have a line to itself, leave the first line blank like this: !block example !block note And some more text inside another multi-line note !endblock !endblock The result is: !block note And some more text inside another multi-line note !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fbox.sdf010064400042570001753000000016070635016671000165530ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: box Filter H2: Interface !filter_interface "box" H2: Description The {{box}} filter is used to box a region of text. The {{lines}} parameter can be used to treat each line as a line within a paragraph - without this, the contents is treated as normal SDF. The other parameters have the same meanings as they do for the {{FILT:table}} filter. #H2: Examples H2: Limitations & Future Directions Some of the output drivers (e.g. the MIF driver) do not support nested tables, so tables within the box may be ignored. sdf-2.001/doc/ref/filters/fpod.sdf010064400042570001753000000021170645235004000165340ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 24-May-97 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: pod Filter H2: Interface !filter_interface "pod" H2: Description The {{pod}} filter is used to nest POD text within an SDF document. The {{main}} parameter is used to specify that the first paragraph after "=head1 NAME" is the document name. This parameter is used internally by the {{CMD:sdf}} program when it needs to convert a POD document to another format. H2: Examples Some examples are: !block example; lang='sdf' # Insert some pod !block pod A normal POD paragraph. And some verbatim text. !endblock # Get pod from a file !include "perlre.pod"; pod # Get pod from standard output !execute "getpod 'hello.c'"; pod !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fdatestr.sdf010064400042570001753000000023310661402010700174140ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1998, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 23-Oct-98 ianc SDF 2.001 # ----------------------------------------------------------------------- # H1: datestrings Filter H2: Interface !filter_interface "datestrings" H2: Description The {{datestrings}} filter can be used to change the strings used within a date. The fields within the table are: * {{Symbol}} - the matching symbol name (without the $) from the {{SUBR:FormatTime}} subroutine * {{Values}} - a Perl string containing a whitespace-separated list of values. H2: Examples !block verbatim !block datestrings Symbol Values month "January February March April May June July August September October November December" smonth "Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec" weekday "Monday Tuesday Wednesday Thursday Friday Saturday Sunday" sweekday "Mon Tue Wed Thu Fri Sat Sun" ampm "am pm" AMPM "AM PM" !endblock !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fsdf.sdf010064400042570001753000000015350622022216000165230ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: sdf Filter H2: Interface !filter_interface "sdf" H2: Description The {{sdf}} filter can be used to apply an arbitrary set of paragraph and/or phrase attributes to a section of text. H2: Examples To add change bars to a section of text, the sdf filter can be used in combination with the {{changed}} attribute as follows: !block example; lang='sdf' !block sdf; changed This text has been changed. And so has this. !endblock !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/faddress.sdf010064400042570001753000000015300622022216200173710ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: address Filter H2: Interface !filter_interface "address" H2: Description The {{address}} filter is used to format an address. This typically implies: * for [[PostScript]], the paragraphs have no space between them * for [[HTML]], the paragraphs are given ADDRESS tags. H2: Examples A typical letter starts like this: !block example; lang='sdf' !block address Mr I.M. Lucky 13 Horseshoe Drive Brisbane Q 4001 !endblock !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fverbati.sdf010064400042570001753000000026630645231733000174210ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: verbatim Filter H2: Interface !filter_interface "verbatim" H2: Description The {{verbatim}} filter is used to specify a section of fixed-width text. Unlike the {{FILT:verbatim}} filter, embedded SDF symbols (like E<2{>) are treated like normal text. The {{skipheader}} parameter is useful when an external file is being included as an example, but you do not want the header comment in the example. The {{lang}} parameter, if any, is used to determine the commenting conventions. If no language is specified, comments are assumed to start with a # and be terminated by the end of line. The {{wide}} parameter can be used to ensure that at least 80 characters are output on a line before it is wrapped. The {{listitem}} parameter can be used to specify that this block of text is part of a list. The value is the logical indent of the list (e.g. 1, 2, etc.). H2: Examples !block example; lang='sdf' # Include myfile.c but exclude the copyright, revision history, etc. !include "myfile.c"; verbatim; skipheader; lang='c' !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fscript.sdf010064400042570001753000000022000622022216000172410ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: script Filter H2: Interface !filter_interface "script" H2: Description The {{script}} filter can be used to embed arbitrary Perl source code within an SDF document. This is useful for many things including: * declaring Perl subroutines implementing SDF filters and macros * accessing databases * updating log files. H2: Examples !block example; lang='sdf' !block script printf STDERR "Hello world!\n"; !endblock !endblock H2: Limitations & Future Directions As arbitrary sections of [[Perl]] can be included and executed, the code can potentially cause harm. At the moment, the ability to update external files from within an SDF document is seen as a {{feature}}. However, a version of SDF which restricts the embedded Perl to "safe" operations would be nice. sdf-2.001/doc/ref/filters/fdefault.sdf010064400042570001753000000021660622022216000173740ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: default Filter H2: Interface !filter_interface "default" H2: Description The {{default}} filter is a convenient way of calling the {{MAC:default}} macro for several variables. The {{family}} parameter is often used to specify a common prefix. The {{export}} parameter can be used to export the variables to the target document system. See the {{MAC:export}} macro for further details on variable exporting. H2: Examples !block example; lang='sdf' !block default Name Value COMPANY_NAME ACME Mining COMPANY_PHONE 1234 5678 !endblock !endblock A simpler version is: !block example; lang='sdf' !block default; family="COMPANY" Name Value NAME ACME Mining PHONE 1234 5678 !endblock !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fascii_g.sdf010064400042570001753000000011340622022216200173420ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: ascii_graphic Filter H2: Interface !filter_interface "ascii_graphic" H2: Description The {{ascii_graphic}} filter is used to specify a section of text as a diagram. #H2: Examples #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fnameval.sdf010064400042570001753000000017430645234554200174140ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 03-Jun-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: namevalues Filter H2: Interface !filter_interface "namevalues" H2: Description The {{namevalues}} filter is used to format a table of name-value pairs. Each name is output in bold. For PostScript output, the names are placed in the sidehead. H2: Examples !block example; lang='sdf' !block namevalues Name Value Description: Find the maximum of two numbers Module: general Author: Joe Bloggs !endblock !endblock The result is: !block namevalues Name Value Description: Find the maximum of two numbers Module: general Author: Joe Bloggs !endblock sdf-2.001/doc/ref/filters/ffront.sdf010064400042570001753000000013160645207527200171150ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: front Filter H2: Interface !filter_interface "front" H2: Description The {{front}} filter includes text as is. It is provided for backwards compatibility with older versions of SDF when the "front" section of a FrameMaker book needed to be placed into a separate SDF file. H2: Examples None. #H2: Limitations & Future Directions ------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: front Filter H2: Interface !filter_interface "front" H2: Description The {{front}} filter includes text as is. It is provided sdf-2.001/doc/ref/filters/fplain.sdf010064400042570001753000000016120645234334600170670ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: plain Filter H2: Interface !filter_interface "plain" H2: Description The {{plain}} filter is used when including a topic as an "plain" section within a document, i.e. normal headings are converted to plain headings. H2: Examples A typical book might look like this: !block example; lang='sdf' !init OPT_STYLE="manual" !define DOC_NAME "A Sample Book" !build_title !include "chapter1.sdf" !include "chapter2.sdf" !include "chapter3.sdf" !include "glossary.sdf"; plain !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fsimple.sdf010064400042570001753000000024050645236411400172520ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 01-May-97 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: simple Filter H2: Interface !block example !block {{B:simple}} [;{{parameters}}] ... !endblock !endblock The parameters are: !block table Name Description pre Perl code to execute before the block exec executed for each line with $line containing the text line post Perl code to execute after the block !endblock H2: Description The {{simple}} filter is typically used as a building block for other filters. It provides a simple way of specifying the before (pre), per-line (exec) and after (post) actions. Note: As creating new filters is not something that the average SDF users does, this filter is really provided to make life easier for advanced SDF users and SDF administrators. H2: Examples E:!on filter "testcases";; \ E: $name='simple'; \ E: $params.=';pre="!testcaseStart"'; \ E: $params.=';post="!testcaseEnd"' #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fcomment.sdf010064400042570001753000000012160622022216000174050ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: comment Filter H2: Interface !filter_interface "comment" H2: Description The {{comment}} filter is used to temporarily ignore a block of text. H2: Examples !block example; lang='sdf' !block comment Ignore me !endblock !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fabstrac.sdf010064400042570001753000000021030645234317400173760ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: abstract Filter H2: Interface !filter_interface "abstract" H2: Description The {{abstract}} filter is used to specify an abstract for a technical paper. This typically implies: * for [[PostScript]], the text is italics and indented from both margins * for [[HTML]], the text is given an appropriate heading. H2: Examples A typical paper starts like this: !block example; lang='sdf' !init OPT_STYLE="paper" !define DOC_NAME "Internet Management Tools" !define DOC_AUTHOR "I. M. Wise" !build_title !block abstract The internet is out of control. This paper ... # more paragraphs go here !endblock H1: Introduction # The interesting stuff goes here !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fexample.sdf010064400042570001753000000037010647527143200174210ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: example Filter H2: Interface !filter_interface "example" H2: Description The {{example}} filter is used to specify a section of fixed-width text. Unlike the {{FILT:verbatim}} filter, embedded SDF symbols (like E<2{>) are relevant. The {{skipheader}} parameter is useful when an external file is being included as an example, but you do not want the header comment in the example. The {{lang}} parameter, if any, is used to determine the commenting conventions. If no language is specified, comments are assumed to start with a # and be terminated by the end of line. The {{lang}} parameter can be used to pretty-print programming languages. In practice, this means: * comments are output in italics * keywords are output in bold. Note: The {{FILT:langdefs}} filter is used to configure the information the pretty-printing feature needs to know. A large number of languages are predefined in the {{FILE:stdlib/langdefs.sdm}} file. The {{wide}} parameter can be used to ensure that at least 80 characters are output on a line before it is wrapped. The {{listitem}} parameter can be used to specify that this block of text is part of a list. The value is the logical indent of the list (e.g. 1, 2, etc.). The {{pure}} parameter can be used to escape special SDF symbols (like E<2{>) embedded within the text. H2: Examples !block example; lang='sdf' # Include myfile.c but exclude the copyright, revision history, etc. !include "myfile.c"; example; skipheader; lang='c' # Pretty-print the same file !include "myfile.c"; example; wide; lang='c' !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/ftable.sdf010064400042570001753000000075460645714702400170670ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: table Filter H2: Interface !filter_interface "table" H2: Description The {{table}} filter specifies a table in {{FMT:TBL}} format. A brief description of each parameter is given below. A tutorial-style introduction to SDF's table features is also provided in the {{DOC:SDF User Guide}}. !block table Parameter Description align alignment of table: one of Left, Center, Right, Inner, Outer bgcolor background colour for a table (HTML only) bmargin default bottom margin for table cells (MIF only) cellpadding padding size for table cells (HTML only) cellspacing spacing size between table cells (HTML only) colaligns a comma-separated list of horizontal alignments \ values (Left, Center, Right) for columns; \ alternatively, a single word containing the letters L, C and R coltags a comma-separated list of phrase styles to apply to columns colvaligns a comma-separated list of vertical alignments \ values (Top, Middle, Bottom, Baseline) for columns; \ alternatively, a single word containing the letters T, M, B and L delete a comma-separated list of columns to delete footings the number of footing rows at the end of the table format a comma-separated list of column width specifications; \ alternatively, a single number where each digit represents \ 10% of the space available to the table groups pattern of group-style rows (default is /:$/) headings the number of heading rows at the top of the table landscape display the table in landscape mode (MIF only) listitem the list indent level (e.g. 1) of this table lmargin default left margin for table cells (MIF only) narrow if set, the table will only be as wide as required; \ otherwise the table will span the available space niceheadings set to 0 to disable _ to space conversion in headings nocalcs set to 0 to disable calculation processing within a table noheadings suppress headings in output objects alias for coltags (coltags is preferred) oncell Perl code to execute for each cell (internal use only!) parseline column headings parsing line (if not the first row in the text) placement vertical placement of table: one of Float, Pagetop, Columntop, \ Lefttop, Righttop (MIF only) rmargin default right margin for table cells (MIF only) select a comma-separated list of columns to display sort a comma-separated list of columns to sort the data rows by style overall look of the table tags alias for coltags (coltags is preferred) title table caption tmargin default top margin for table cells (MIF only) type alias for style (style is preferred) where an expression to filter the data rows with wide table straddles the side head area of the page wrap the number of data rows to display in a physical row !endblock H2: Examples A typical table is: !block example; lang='sdf' !block table; format=55; style="grid"; groups; title="Diary" Time_of_day Appointment Morning: 10:00 Dentist 12:00 Lunch with friends Afternoon: 15:00 Meeting on SDF !endblock !endblock The result is: !block table; format=55; style="grid"; groups; title="Diary" Time_of_day Appointment Morning: 10:00 Dentist 12:00 Lunch with friends Afternoon: 15:00 Meeting on SDF !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fnofill.sdf010064400042570001753000000020230633203111000172200ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 01-May-97 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: nofill Filter H2: Interface !filter_interface "nofill" H2: Description The {{nofill}} filter is used to format a set of lines, i.e. lines are separated by newline characters. Note: The {{FILT:address}} filter may be a better choice that nofill in certain cases. Unlike nofill, address is mapped to ADDRESS tags when HTML is generated. (It's then up to the browser to decide how the address is formatted.) H2: Examples !block example; lang='sdf' !block nofill Mr I.M. Lucky B.Sc. (Computing) B.Fun. (Eating) !endblock !endblock The output is: !block nofill Mr I.M. Lucky B.Sc. (Computing) B.Fun. (Eating) !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fhlp_hea.sdf010064400042570001753000000012170645234420000173530ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: hlp_header Filter H2: Interface !filter_interface "hlp_header" H2: Description The {{hlp_header}} filter is used to define a table of jumps within the non-scrolling region of a Windows help topic. #H2: Examples #To be completed. #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fchanged.sdf010064400042570001753000000014470645234353600173640ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: changed Filter H2: Interface !filter_interface "changed" H2: Description The {{changed}} filter is used to mark a section of text as changed. H2: Examples To add change bars to a section of text: !block example; lang='sdf' !block changed This text has been changed. And so has this. !endblock !endblock H2: Limitations & Future Directions At the moment, this filter only works when generating FrameMaker documents. sdf-2.001/doc/ref/filters/finline.sdf010064400042570001753000000022230636063172200172350ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: inline Filter H2: Interface !filter_interface "inline" H2: Description The {{inline}} filter is used to pass a section of text directly to a target documentation system. The {{target}} parameter is used to specify which target system the nominated text is to be passed to. The default target is {{html}}. The {{expand}} parameter can be used to request expansion of SDF expressions (enclosed in E<2[> and E<2]>) within the text. H2: Examples To embed [[HTML]] within an SDF document: !block example; lang='sdf' !block inline add arbitrary HTML here ... !endblock !endblock SDF expressions can be expand like this: !block example; lang='sdf' !define VERB "is" ... !block inline; expand

This HTML [[VERB]] expanded. !endblock !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/ftitle.sdf010064400042570001753000000023270645236701200171050ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: title Filter H2: Interface !filter_interface "title" H2: Description The {{title}} filter is used to build the title block for memos, faxes, etc. The {{type}} parameter can be used to override the document type. For PostScript output, the value is displayed in a box above the rest of the title. The {{toc}} parameter is used to request a table of contents. The value is the level of headings to include in the contents. The {{format}} attribute is used to fine tune the layout of the columns within the table for format where a table is used (e.g. plain text). H2: Examples !block example; lang='sdf' !block title Name Value Date: [[DATE:DOC_MODIFIED]] To: Joe Bloggs, Sue Brown, Maree Jones Copy: David Smith From: Neil Armstrong Subject: Solar System Information Ref. No: XY.002/GUI/96 !endblock !endblock sdf-2.001/doc/ref/filters/fdefine.sdf010064400042570001753000000021600622022216000171740ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: define Filter H2: Interface !filter_interface "define" H2: Description The {{define}} filter is a convenient way of calling the {{MAC:define}} macro for several variables. The {{family}} parameter is often used to specify a common prefix. The {{export}} parameter can be used to export the variables to the target document system. See the {{MAC:export}} macro for further details on variable exporting. H2: Examples !block example; lang='sdf' !block define Name Value COMPANY_NAME ACME Mining COMPANY_PHONE 1234 5678 !endblock !endblock A simpler version is: !block example; lang='sdf' !block define; family="COMPANY" Name Value NAME ACME Mining PHONE 1234 5678 !endblock !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fhlp_win.sdf010064400042570001753000000012000645234423600174140ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: hlp_window Filter H2: Interface !filter_interface "hlp_window" H2: Description The {{hlp_window}} filter is used to define the contents of a popup window for [[Windows]] help files. #H2: Examples #To be completed. #H2: Limitations & Future Directions sdf-2.001/doc/ref/filters/fabout.sdf010064400042570001753000000024010645207341400170670ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 16-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: about Filter H2: Interface !filter_interface "about" H2: Description The {{about}} filter is used when including a topic as an "about" section within a document. Typically, this implies: * the headings are converted to plain headings and slid down one level * the headings (except those initially at level 1) are removed from the table of contents. H2: Examples A typical book might look like this: !block example; lang='sdf' !init OPT_STYLE="manual" !define DOC_NAME "A Sample Book" !build_title !include "myabout.sdf"; about !include "chapter1.sdf" !include "chapter2.sdf" !include "chapter3.sdf" !include "appendx1.sdf"; appendix !endblock A typical about topic looks like this: !block example; lang='sdf' H1: About this manual H2: Purpose This manual provides information on ... H2: Scope This manual contains information on ... !endblock #H2: Limitations & Future Directions sdf-2.001/doc/ref/sdfcli.sdf010064400042570001753000000000750630252073000154000ustar00iancmtr00000400000236# Extract the documentation from the script !getdoc "sdfcli" sdf-2.001/doc/ref/cproduct.html010064400042570001753000000043360672242510400161600ustar00iancmtr00000400000236 SDF 2.001: SDF Reference: products Class

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog


1.3. products Class

Interface

The general syntax is:

  !block products[; parameters]
  table of objects
  !endblock

The object attributes are:

Field Category Rule
Name mandatory  
Jump optional  

See Understanding Class Interfaces, if necessary.

Description

The products filter is used to declare and/or format objects in the products class. The attributes supported are:

Attribute Description
Name the product name
Jump the product URL, if any

Examples

See the objects.sdm file within SDF's stdlib directory.

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog

sdf-2.001/doc/ref/in_prog.sdf010064400042570001753000000037110647625432600156120ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 29-Feb-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: Programs H2: Overview The programs available are summarised below. !block table; tags="CMD" Name Purpose sdf convert [[SDF]] files to other formats sdfapi extract the {{Application Programming Interface}} from source code sdfbatch generate [[FrameMaker]] batch files sdfcli extract the {{Command Line Interface}} from a utility sdfget extract documentation embedded in source code sdftest execute SDF regression tests sdngen build an SDF tuning module from a FrameMaker template #fm2ps convert FrameMaker files to PostScript (a wrapper for {{CMD:sdfbatch}}) #pod2sdf convert POD to SDF #poddiff compare POD files and report differences prn2ps convert Windows PostScript to Unix PostScript !endblock {{CMD:sdf}} is typically invoked as follows: E: sdf -2{{format}} [options] files Supported {{format}} values include the following: !block table Format Description ps a [[PostScript]] document html a [[HTML]] document hlp [[Microsoft]] Windows help input files fvo a {{PRD:FrameViewer}} file txt a plain text document rtf an [[RTF]] document book a book ([[PostScript]]) !endblock Further details on the programs are provided below. # Add the script directory to the search path !path_append "../../bin" # Include the subsections, placing each at the top of a page (or after a line) !if $var{'OPT_TARGET'} eq 'txt' !on paragraph 'H2'; h2top; &PrependText("Line:") !else !on paragraph 'H2'; h2top; $attr{'top'} = 1 !endif !block topics Topic sdf sdfapi sdfbatch sdfcli sdfget sdftest sdngen prn2ps !endblock !off paragraph h2top sdf-2.001/doc/ref/fsdf.html010064400042570001753000000034000672242525300152530ustar00iancmtr00000400000236 SDF 2.001: SDF Reference: sdf Filter

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog


5.28. sdf Filter

Interface

The general syntax is:

  !block sdf[; parameters]
  ...
  !endblock

See Understanding Filter Interfaces, if necessary.

Description

The sdf filter can be used to apply an arbitrary set of paragraph and/or phrase attributes to a section of text.

Examples

To add change bars to a section of text, the sdf filter can be used in combination with the changed attribute as follows:

!block sdf; changed
This text has been changed.

And so has this.
!endblock

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog

sdf-2.001/doc/ref/sdfget.sdf010064400042570001753000000000750630252072600154150ustar00iancmtr00000400000236# Extract the documentation from the script !getdoc "sdfget" sdf-2.001/doc/ref/sdngen.sdf010064400042570001753000000000750647021620400154160ustar00iancmtr00000400000236# Extract the documentation from the script !getdoc "sdngen" sdf-2.001/doc/ref/sprepend.sdf010064400042570001753000000013330635011350400157520ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 29-Feb-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: PrependText H2: Purpose {{S:PrependText}} is used within a paragraph event handler to prepend [[SDF]] before a paragraph. H2: Interface E: &PrependText(@sdf) H3: Description The argument is the list of [[SDF]] paragraphs to prepend. H2: Examples To prepend a line before each level 1 heading: E: !on paragraph 'H1';; &AppendText('Line:') sdf-2.001/doc/ref/sfindfil.html010064400042570001753000000057040672242565500161460ustar00iancmtr00000400000236 SDF 2.001: SDF Reference: FindFile

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog


12.3. FindFile

Purpose

This routine is used to search for include files, imported objects, configuration modules and templates.

Interface

  $fullname = &FindFile($filename, $image);

Description

If filename is not found, fullname should be an empty string. If the file is found, the pathname of the file is returned, otherwise the empty string is returned. If image is true, a target-specific set of extensions is searched for, complete with implicit image format conversion.

Examples

The default implementation is:

sub FindFile {
    local($filename, $image) = @_;
    local($fullname);

    # Get the list of directories to search
    use Cwd;
    my @dirs = ('.');
    my $dir = $var{'DOC_DIR'};
    push(@dirs, $dir) if $dir ne cwd();
    push(@dirs, @include_path, "$'sdf_lib/stdlib", $'sdf_lib);

    # Do the search
    if ($image) {
        my $context = $var{'OPT_TARGET'};
        my @exts = @{$'SDF_IMAGE_EXTS{$context} || $'SDF_IMAGE_EXTS{'ps'}};
        return &'NameFindOrGenerate($filename, \@dirs, \@exts, $context);
    }
    else {
        return &'NameFind($filename, @dirs);
    }
}

In order to tightly integrate SDF with certain development environments, it is occasionally necessary to override this routine in a configuration module. For example:

!block script
sub FindFile {
    local($filename, $image) = @_;
    local($fullname);

    # Search using our SCM
    $fullname = &'SearchSCM($filename, $image);

    # Return result
    return $fullname;
}
!endblock

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog

sdf-2.001/doc/ref/in_ostyl.html010064400042570001753000000110730672242550600161770ustar00iancmtr00000400000236 SDF 2.001: SDF Reference: Phrase Styles

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog


10. Phrase Styles

The phrase styles available are summarised below.

Tag Description Sample Output
Emphasis:    
1 1st level emphasis (default) emphasis 1
2 2nd level emphasis emphasis 2
3 3rd level emphasis emphasis 3
Formatting:    
N normal some normal text
I italic some italic text
B bold some bold text
U underline some underline text
EX example some example text
Types:    
EMAIL email address ianc@mincom.com
F (or FILE) Filename myfile.sdf
SECT Section Paragraphs
URL Uniform Resource Locator http://www.mincom.com
Classes:    
DOC document title SDF User Guide
REF reference (document code) MTR-SDF-0002
ORG organisation Mincom
PRD product MIMS
Specials:    
E (or CHAR) escape (i.e. special character) ©
S spaces are non-breaking section 2.1
IMPORT name of a figure to import
URLs:    
http    
ftp    
telnet    
news    
gopher    
wais    
https    
snews    

Note: When emphasising text, it is generally better to use an emphasis style rather than a formatting style as the best way of doing so depends on the output format.

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog

> SDF 2.001: SDF Reference: Phrase Styles

Contents | Parent Topic | SDF 2.001: SDF Reference: hlp_header Filter

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog


5.17. hlp_header Filter

Interface

The general syntax is:

  !block hlp_header
  table
  !endblock

The table fields are:

Field Category Rule
Text key  
Kind optional <popup|jump>

See Understanding Filter Interfaces, if necessary.

Description

The hlp_header filter is used to define a table of jumps within the non-scrolling region of a Windows help topic.

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog

sdf-2.001/doc/ref/fscript.html010064400042570001753000000043150672242525000160060ustar00iancmtr00000400000236 SDF 2.001: SDF Reference: script Filter

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog


5.27. script Filter

Interface

The general syntax is:

  !block script
  ...
  !endblock

See Understanding Filter Interfaces, if necessary.

Description

The script filter can be used to embed arbitrary Perl source code within an SDF document. This is useful for many things including:

  • declaring Perl subroutines implementing SDF filters and macros
  • accessing databases
  • updating log files.

Examples

!block script
printf STDERR "Hello world!\n";
!endblock

Limitations & Future Directions

As arbitrary sections of Perl can be included and executed, the code can potentially cause harm. At the moment, the ability to update external files from within an SDF document is seen as a feature. However, a version of SDF which restricts the embedded Perl to "safe" operations would be nice.

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog

sdf-2.001/doc/ref/prn2ps.sdf010064400042570001753000000000750647626535200154020ustar00iancmtr00000400000236# Extract the documentation from the script !getdoc "prn2ps" sdf-2.001/doc/ref/ffront.html010064400042570001753000000031570672242521300156340ustar00iancmtr00000400000236 SDF 2.001: SDF Reference: front Filter

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog


5.15. front Filter

Interface

The general syntax is:

  !block front
  ...
  !endblock

See Understanding Filter Interfaces, if necessary.

Description

The front filter includes text as is. It is provided for backwards compatibility with older versions of SDF when the "front" section of a FrameMaker book needed to be placed into a separate SDF file.

Examples

None.

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog

sdf-2.001/doc/ref/gl_cli.sdf010064400042570001753000000202700635011350400153640ustar00iancmtr00000400000236# $Id$ # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 29-Feb-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # H1: Command Line Guidelines H2: Overview H3: General Usage Utilities have the following general usage: E: utility [options] arguments Typically, arguments is a set of filenames. If more than one file is specified, each filename is echoed to standard error as it is processed. Options can either be: * {{short style}} - these begin with a '-' character, or * {{long-style}} - these begin with the character sequence '--'. To obtain a concise summary of a utility's usage, execute it without any parameters. For example: E:$ hoopy E:usage : hoopy [-h[help]] [-o[out_ext]] [-l[log_ext]] [-t thing,..] file ... E:purpose: do lots of hoopy things to files E:version: 1.000 E:$ _ H3: Exit Codes The exit code returned to the operating system is dependent on the severity of any errors encountered during execution. The pre-defined exit codes are linked to message types as summarised below. !block table; format=226 Code Message Description 0 n/a everything succeeded 8 warning a possible problem was identified 16 error an error was found 24 abort processing could not continue on a file 32 fatal the application terminated abnormally 64 failed an internal error occurred !endblock H3: Arguments The set of options is implicitly terminated by the first argument. i.e. the first symbol which does not begin with either '-' or '--'. To specify an argument which would otherwise be treated as an option, it is sometimes necessary to explicitly terminate the options using the '--' symbol. Unless stated otherwise for a particular utility, '+' can be used to specify that standard input contains a list of arguments. This feature is particularly useful for passing complex arguments to scripts on systems with poor support for command line quoting. If the arguments are files, '-' can be used to indicate standard input. H3: Providing Default Options Default options for a utility can be specified in an environment variable of the form: E: {{name}}OPTS For example, if {{CMD:hoopy}} supported a -R option for specifying a directory to search for report files in, then the user may wish to define this directory in an environment variable so that they do not need to specify it each time. This could be done by adding the following to their {{.profile}}: E: HOOPYOPTS=-R/home/me/etc/reports E: export HOOPYOPTS H2: Options H3: Option Types Several types of options are supported as outlined in the table below. !block table Option_type Usage_message_format parameter-less [-x] parameter-required [-x thing] parameter-optional [-x[thing]] !endblock For parameter-optional options, the option parameter typically defaults to a particular value if the option is supplied without a parameter. For example, the extension of output files can be specified using the -o option. The default value of this parameter-optional option is 'out'. The series of examples below illustrates this. ^ To send output to standard output: E: hoopy *.dat + To send output to .out files: E: hoopy -o *.dat + To send output to .new files: E: hoopy -onew *.dat As for arguments, '-' can be specified to indicate standard input for options expecting a filename. H3: List Options Some options have {{list parameters}}. These options can be specified several times and/or multiple list elements can be separated with commas. For example, the following are all equivalent: E: hoopy -ta,b,c *.dat E: hoopy -ta -tb,c *.dat E: hoopy -ta,b -tc *.dat E: hoopy -ta -tb -tc *.dat In addition to simple lists, lists of name-value pairs are also supported. In this case, the name and value are separated by a '=' or ':' character. Note: on MS-DOS and OS/2, '=' causes problems so ':' must be used. If only the name is given, the value is assumed to be 1. For example, the following are equivalent: E: mycmd -ftbl_dir=../tables -fverbose=1 *.dat E: mycmd -ftbl_dir=../tables -fverbose *.dat E: mycmd -ftbl_dir:../tables -fverbose *.dat Ordering is not important for name-value lists but may be important for normal lists. In either case, within a usage message, list options are indicated as follows: E: [-t thing,..] H3: Option Styles There are two parameter styles: {{short}} and {{long}}. Short style is typically used on the command line. Long style is useful to improve readability in shell scripts. In short style: * options are specified by a single character * a set of parameter-less options can be clustered * between the option character and the parameter: - whitespace is optional for a parameter-required option - whitespace is {{not}} permitted for a parameter-optional option In long style: * the name can be abbreviated provided it is still unique * a '=' or ':' is used to separate the option name from the parameter Examples are: E: hoopy --out *.dat and E: hoopy --out=new *.dat H3: Option Naming Conventions Long option names should be selected for maximum readability. In general, the short name should be the first letter of the long name. For list options which specify a set of directories to search in: * the long name should end in '_path' * the short name should be a capital letter If applicable, the capital letter used should be taken from the related option. For example, if the -r option is used to specify a report file, the -R option should be the list of directories to search for the report in. H2: Commonly Used Options H3: Overview There are 3 options available for most utilities: * -o[out_ext] * -l[log_ext] * -h[help] H3: Redirecting Standard Output and Standard Error By default, generated output goes to standard output. To direct output to a file per input file, use the -o option to specify an extension for output files. If the -o option is specified without a parameter, an extension of {{out}} is assumed. Likewise, error messages go to standard error by default. Use the -l option to create a log file per input file. If the -l option is specified without a parameter, an extension of {{log}} is assumed. For a small number of scripts, there is never a need for output or error files per argument. In this case, the -o and -l options are not available. H3: Obtaining Help The -h option provides help and is always available. To obtain a concise description of each option, use the help option with no parameter. For example: !block example {{2:$}} sdfget -h usage : sdfget [-h[help]] [-o[out_ext]] [-l[log_ext]] [-g get_rule] [-r[rpt_file]] [-i] file ... purpose: extract documentation embedded in source code version: 2.000 (SDF 2.000beta9) options: -h, --help display help on options -o, --out_ext output file extension -l, --log_ext log file extension -g, --get_rule rule to use to get documentation -r, --rpt_file report file -i, --inverse only output lines not extracted !endblock H3: Obtaining Help on a Given Option Detailed help on a given option can be obtained by specifying the option code as a parameter to the -h option. For example: !block example {{2:$}} sdfget -hg usage : sdfget [-h[help]] [-o[out_ext]] [-l[log_ext]] [-g get_rule] [-r[rpt_file]] [-i] file ... purpose: extract documentation embedded in source code version: 2.000 (SDF 2.000beta9) Detailed help on option: -g,--get_rule Attribute Value Help rule to use to get documentation Type STR Parameter yes Initial perl Legal table, perl, cpp, c, eiffel, fortran !endblock H3: Obtaining Special Help The help option can also be used to obtain other useful information by specifying a special keyword as the parameter. The keywords supported are: * {{.parts}} - display name & version of components (and exit) * {{.time}} - display execution time (when exiting) * {{.calltree}} - display the internal sequence of subroutines leading to utility exit This type of information is useful when developing scripts but is rarely needed by end-users. sdf-2.001/doc/ref/reasdf.html010064400042570001753000000043460672242507600156120ustar00iancmtr00000400000236 SDF 2.001: SDF Reference: About This Manual

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog


About This Manual

Purpose

This manual is a reference for SDF - a documentation system for software developers.

Scope

This manual contains detailed reference material on most SDF features.

The following documents may also be of interest:

Amendments

Suggested enhancements and corrections to SDF and its documentation can be forwarded to sdf-bugs@mincom.com.

Note: This manual documents version 2.001 of SDF.

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog

sdf-2.001/doc/ref/sdfget.html010064400042570001753000000216420672242561400156160ustar00iancmtr00000400000236 SDF 2.001: SDF Reference: sdfget - Documentation Extraction Utility

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog


11.6. sdfget - Documentation Extraction Utility

Purpose

sdfget extracts documentation embedded in source code.

Usage

usage  : sdfget [-h[help]] [-o[out_ext]]
         [-l[log_ext]] [-O[out_dir]]
         [-f formatting_filename] [-g[get_rule]]
         [-r[rpt_file]] [-s scope] [-i]
         [-v[verbose]] file ...
purpose: extract documentation embedded in source code
version: 2.000    (SDF 2.001)

The options are:

Option Description
-h display help on options
-o output file extension
-l log file extension
-O output to input file's (or explicit) directory
-f filename to use when formatting the output
-g rule to use to get documentation
-r report file
-s scope of documentation to be extracted
-i only output lines not extracted
-v verbose mode

Description

The -h option provides help. If it is specified without a parameter, a brief description of each option is displayed. To display the attributes for an option, specify the option letter as a parameter.

By default, generated output goes to standard output. To direct output to a file per input file, use the -o option to specify an extension for output files. If the -o option is specified without a parameter, an extension of out is assumed.

Likewise, error messages go to standard error by default. Use the -l option to create a log file per input file. If the -l option is specified without a parameter, an extension of log is assumed.

By default, generated output and log files are created in the current directory. Use the -O option to specify an explicit output directory. If the -O option is specified without a parameter, the input file's directory is used.

The -f option can be used to specify a filename to use when formatting the output. This is useful when the text is coming from the standard input stream.

The get-rule nominates the formatting of the embedded documentation to be extracted. All currently defined get-rules assume the documentation is in comment blocks in one of the following formats:

 >>section_title1::
 text of section 1, line 1
 text of section 1, line ..

 >>section_title2::
 text of section 2, line 1
 text of section 2, line ..
 >>END::

 >>section_title3:: text of section 3

The first form is most commonly used. In this format, the text in a section extends until the end of the current "comment block" or the start of the next section, whichever comes first. The second form (i.e. explicitly specifying where the section ends) is useful if you wish to add some normal comments (i.e. non-documentation) which you do not want extracted. If the text is short, the third form can be used. Regardless of the format, if a section is found which is already defined, the text of the section is concatenated onto the existing text. This permits the documentation for each entity to be specified immediately above where it is defined in the source code.

The -g option specifies the get-rule to use. The available get-rules differ on the prefix expected at the front of each line as shown below.

Rule Prefix
perl #
cpp //
c * or /*
fortran c (with 5 preceding spaces)
eiffel --
bat rem

Within C code, a trailing space is required after the characters above. For other languages, a trailing space is optional. Within FORTRAN code, the "c" character must be preceded by exactly 5 spaces. For other languages, zero or more whitespace characters are permitted before the characters above.

For example, embedded documentation within C code looks like:

 /* >>Purpose::
  * This library provides a high level interface
  * to commonly used network services.
  */

If the -g option is not specified, perl is the default get-rule. If the -g option is specified without a parameter, the extension in lowercase of the filename (or the formatting filename if the text is coming from standard input) is used to guess the get_rule as shown below.

Rule Extensions
cpp cpp, c++, cc, hpp, hpp, h, java, idl
c c
fortran fortran, for, f77, f
eiffel eiffel, ada
bat bat, cmd

A report filename can be specified using the -r option. If the name doesn't include an extension, sdg is assumed. Reports provide a mechanism for:

  • selectively extracting sections, and
  • rudimentary reformatting (e.g. to SDF)

If no report is specified, all sections are output in the following format:

 section_title1
 section_text1

 section_title2
 section_text2

If -r is specified on its own, default.sdg is assumed. This report selects the set of sections (within the SDF documentation standards) which form the user documentation and formats them into SDF. Details on the report format are specified below. Reports are searched for in the current directory, then in the stdlib directory within SDF's library directory.

The -s option can be used to specify the scope of the documentation to be extracted. (This is an experimental feature and may change so most users should avoid using it.)

The -i option outputs only those lines which the get-rule did not match. This option is useful for extracting non-documentation from a file to give just the code.

Note: The -r option is ignored if -i is specified.

The -v option enables verbose mode. This is useful for seeing which rule is being used for each file.

Examples

To extract the user documentation from a SDF application written in C++ (xyz, say) and save it into xyz.sdf:

      sdfget -gcpp -r -osdf xyz.cpp

Limitations and future directions

It would be nicer if the get-rule was always guessed from the filename extension but changing the default from perl could break existing scripts. Therefore, get-rule guessing must be explicitly enabled by specifging the -g option without a parameter.

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog

on embedded in source code.

Usage

usage  : sdfget sdf-2.001/doc/ref/corganis.html010064400042570001753000000045020672242510200161330ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: organisations Class










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










1.2. organisations Class




Interface


The general syntax is:


  !block organisations[; parameters]
  table of objects
  !endblock



The object attributes are:






Field


Category


Rule






Name


mandatory


 






Long


optional


 






Jump


optional


 







See Understanding Class Interfaces, if necessary.




Description


The organisations filter is used to declare and/or format objects in the organisations class. The attributes supported are:






Attribute


Description






Name


the organisation name






Jump


the organisation URL, if any









Examples


See the objects.sdm file within SDF's stdlib directory.








Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








sdf-2.001/doc/ref/fmt_sdg.html010064400042570001753000000060560672242513700157670ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: SDG Format










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










4.3. SDG Format




Purpose


SDG files are used to format information extracted from source code by sdfget.




Description


An SDG is a table of Key-Format pairs. For example:


     Key     Format
     -       "Key\t\tDescription\n"
     *       sprintf("%-15.15s\t%s\n", $key, $data)



The first line specifies the layout of the table and is required. An item is only printed if it has a description. The Key field can be one of the following:


    

  • an item name

  • a minus (-) character, indicating free text

  • an asterix (*) character, indicating all remaining items


The Format field is a Perl expression. $key and $data are used to indicate the key and description of the current item respectively. Other available symbols are:


    

  • $dir - directory component of current file

  • $base - base component of current file

  • $ext - extension component of current file

  • $short - base & extension components of current file




Examples


The SDG file used to format topics within the SDF documentation is:


Key             Format
-               "!use 'sdgmacs'\n!SDG_BEGIN\n"
Title           "H1[id=\"$short\"] $short - $data\n\n"
Purpose         "H2: $key\n\n$data\n\n"
Interface       "H2: $key\n\n$data\n\n"
-               "!SDG_DESCRIPTION_PRE\n"
Description     "H2: $key\n\n$data\n\n"
-               "!SDG_DESCRIPTION_POST\n"
Notes           "H2: $key\n\n$data\n\n"
Examples        "H2: $key\n\n$data\n\n"
Limitations     "H2: Limitations and future directions\n\n$data\n\n"
See_also        "H2: See also\n\n$data\n\n"
Authors         "H2: $key\n\n$data\n\n"
-               "!SDG_END\n"









Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








sdf-2.001/doc/ref/fmt_ini.html010064400042570001753000000034330672242513500157630ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: INI Format










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










4.2. INI Format




Purpose


INI files are used to store simple configuration information for scripts.




Description


An INI file contains of a series of sections. Each section begins with a header enclosed in '[' and ']'. Comment lines begin with ';' or '#' as the first non-whitespace character. Blank lines before a section or at the end of a section are ignored.




Examples


A sample file is:


[Drivers]
Format  Library     Subroutine  Book
mif     sdf2mif.pl  MifFormat   MifBook
raw     sdf2raw.pl  RawFormat

[PostProcessing]
ps     = &SdfBatch("-pfile")
doc    = &SdfBatch("-sdoc -Sd")









Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








D>









Contents | Parent Topic | 






SDF 2.001: SDF Reference: references Class










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










1.4. references Class




Interface


The general syntax is:


  !block references[; parameters]
  table of objects
  !endblock



The object attributes are:






Field


Category


Rule






Reference


mandatory


 






Document


optional


 






Jump


optional


 






Version


optional


 






Status


optional


 







See Understanding Class Interfaces, if necessary.




Description


The references filter is used to declare a set of references and matching documents. It can also be used to build a table of references within a document.


The attributes supported are:






Attribute


Description






Reference


the document code






Document


the document name






Version


the document version






Status


the document status






Jump


the URL, if any









Examples


See the sdf.sdm and document.reg files within SDF's sdf directory.








Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








sdf-2.001/doc/ref/mslide_u.html010064400042570001753000000026770672242544700161560ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: slide_up Macro










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










6.39. slide_up Macro




Interface


The general syntax is:


  !slide_up



See Understanding Macro Interfaces, if necessary.




Description


The slide_up macro moves subsequent headings up one level.




Examples








Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








sdf-2.001/doc/ref/minit.html010064400042570001753000000034550672242540500154620ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: init Macro










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










6.26. init Macro




Interface


The general syntax is:


  !init [vars]



The arguments are:






Name


Type


Default


Rule






vars


rest


_NULL_


 







See Understanding Macro Interfaces, if necessary.




Description


The init macro is used on the top line of a document to initialise variables before the configuration libraries are loaded.




Examples








Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








sdf-2.001/doc/ref/in_var.sdf010064400042570001753000000020250661416520500154170ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
H1: Variables

H2: Overview

The categories of predefined variables are:

^ Conversion variables
+ Document variables
+ File variables
+ Miscellaneous variables.

Date-time variables are in units of {{seconds since January 1, 1970}}.
To format a time, use the {{SUBR:FormatTime}} subroutine.

Further details on each group of variables are provided below.

# Include the subsections, placing each at the top of a page (or after a line)
!if $var{'OPT_TARGET'} eq 'txt'
    !on paragraph 'H2'; h2top; &PrependText("Line:")
!else
    !on paragraph 'H2'; h2top; $attr{'top'} = 1
!endif
!block topics
Topic
var_conv
var_doc
var_file
var_misc
!endblock
!off paragraph h2top
sdf-2.001/doc/ref/ftitle.html010064400042570001753000000050650672242527400156340ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: title Filter










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










5.32. title Filter




Interface


The general syntax is:


  !block title[; parameters]
  ...
  !endblock



The parameters are:






Name


Type


Rule






type


string


 






toc


integer


 






format


string


 







See Understanding Filter Interfaces, if necessary.




Description


The title filter is used to build the title block for memos, faxes, etc.


The type parameter can be used to override the document type. For PostScript output, the value is displayed in a box above the rest of the title.


The toc parameter is used to request a table of contents. The value is the level of headings to include in the contents.


The format attribute is used to fine tune the layout of the columns within the table for format where a table is used (e.g. plain text).




Examples


!block title
Name        Value
Date:       [[DATE:DOC_MODIFIED]]
To:         Joe Bloggs, Sue Brown, Maree Jones
Copy:       David Smith
From:       Neil Armstrong
Subject:    Solar System Information
Ref. No:    XY.002/GUI/96
!endblock









Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








sdf-2.001/doc/ref/fpod.html010064400042570001753000000045340672242524400152720ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: pod Filter










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










5.25. pod Filter




Interface


The general syntax is:


  !block pod[; parameters]
  ...
  !endblock



The parameters are:






Name


Type


Rule






main


boolean


 







See Understanding Filter Interfaces, if necessary.




Description


The pod filter is used to nest POD text within an SDF document.


The main parameter is used to specify that the first paragraph after "=head1 NAME" is the document name. This parameter is used internally by the sdf program when it needs to convert a POD document to another format.




Examples


Some examples are:


    # Insert some pod
    !block pod
    A normal POD paragraph.

        And some verbatim text.
    !endblock

    # Get pod from a file
    !include "perlre.pod"; pod

    # Get pod from standard output
    !execute "getpod 'hello.c'"; pod









Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








sdf-2.001/doc/ref/cterms.html010064400042570001753000000053770672242511200156370ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: terms Class










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










1.5. terms Class




Interface


The general syntax is:


  !block terms[; parameters]
  table of objects
  !endblock



The object attributes are:






Field


Category


Rule






Term


mandatory


 






Definition


optional


 






Jump


optional


 







See Understanding Class Interfaces, if necessary.




Description


The terms filter is used to declare and/or format objects in the terms class. The attributes supported are:






Attribute


Description






Term


the term name






Definition


the explanation for the term









Examples


A configuration file may have the following declaration of terms:


  !block terms; data
  Term     Definition
  SDF      Simple Document Format
  SQL      Structured Query Language
  !endblock



These can then be inserted into a document as follows:


  !block terms
  Term     Definition
  SDF
  SQL
  WWW      World Wide Web
  !endblock



Note that the definition for a term already declared will be inserted if none is provided. Furthermore, new terms (like WWW above) can be inserted and added to the configured ones.








Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








sdf-2.001/doc/ref/in_class.sdf010064400042570001753000000025230645237110400157340ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
H1: Classes

H2: Overview

The classes available are summarised below.

!block table; tags="CLASS"
Name            Purpose
references      references/documents
terms           terms/definitions
organisations   organisations
products        products
!endblock

Further details on these are provided below.

# Define the help to be placed after each class interface
!macro CLASS_INTERFACE_END
See {{SECT:Understanding Class Interfaces}}, if necessary.
!endmacro

# Include the subsections, placing each at the top of a page (or after a line)
!if $var{'HTML_TOPICS_MODE'} || $var{'HTML_SUBTOPICS_MODE'}
    # do nothing
!elsif $var{'OPT_TARGET'} eq 'html' || $var{'OPT_TARGET'} eq 'txt'
    !on paragraph 'H2'; h2top; &PrependText("Line:")
!else
    !on paragraph 'H2'; h2top; $attr{'top'} = 1
!endif
!block topics
Topic
classes/corganis
classes/cproduct
classes/creferen
classes/cterms
!endblock

!if !($var{'HTML_TOPICS_MODE'} || $var{'HTML_SUBTOPICS_MODE'})
!off paragraph h2top
!endif
sdf-2.001/doc/ref/sdfapi.html010064400042570001753000000125750672242555600156220ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: sdfapi - API Extraction Utility










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










11.3. sdfapi - API Extraction Utility




Purpose


sdfapi extracts Application Programming Interface information from (Perl) source code.




Usage


usage  : sdfapi [-h[help]] [-o[out_ext]]
         [-l[log_ext]] [-O[out_dir]] [-f fmt_tag]
         [-p[pattern]] [-s sym_type,..] [-j]
         file ...
purpose: extract the API from a (perl) library
version: 2.000    (SDF 2.001)



The options are:






Option


Description






-h


display help on options






-o


output file extension






-l


log file extension






-O


output to input file's (or explicit) directory






-f


output format tag






-p


only symbols matching pattern






-s


only symbols of these types






-j


add SDF-style hypertext jumps from each symbol









Description


The -h option provides help. If it is specified without a parameter, a brief description of each option is displayed. To display the attributes for an option, specify the option letter as a parameter.


By default, generated output goes to standard output. To direct output to a file per input file, use the -o option to specify an extension for output files. If the -o option is specified without a parameter, an extension of out is assumed.


Likewise, error messages go to standard error by default. Use the -l option to create a log file per input file. If the -l option is specified without a parameter, an extension of log is assumed.


By default, generated output and log files are created in the current directory. Use the -O option to specify an explicit output directory. If the -O option is specified without a parameter, the input file's directory is used.


The format of the output can be controlled using the -f option. Supported formats are std and concise. The default is std. std format is:


require "abc.pl";

$myvar = ...

$result =
&myfunc($myparams);



concise format has fewer blank lines and uses 1 line per symbol.


A comma-separated list of symbol types to output can be specified using the -s option. Supported symbol types are:


    

  • sub - subroutines

  • var - variables


The default is to extract all symbols.


The -p option is used to extract only a subset of the symbols. If not supplied, the pattern is symbols beginning with a letter. If supplied without an option, the pattern defaults to all symbols. If perl libraries use the coding convention that symbols beginning with underscore are private, then -p_ can be used to extract the private symbols.


The -j option can be used to request SDF-style hypertext jumps be added for each symbol. The jump target is lib_sym where:


    

  • lib is the library name

  • sym is the symbol name.




Limitations and future directions


The only language currently supported is Perl.


It would be useful to extract messages from the scripts too. This would require a new utility called sdfmsg say, which searched through the source (including libraries) for AppMsg and AppExit calls.


Internally, it may be better to implement formats via routines. This would give better control over output. e.g. it would be up to the routine to decide if it wanted to output the 'require' header.








Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








ption


Description




-h


display help on sdf-2.001/doc/ref/fhlp_win.html010064400042570001753000000030050672242522200161340ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: hlp_window Filter










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










5.18. hlp_window Filter




Interface


The general syntax is:


  !block hlp_window
  ...
  !endblock



See Understanding Filter Interfaces, if necessary.




Description


The hlp_window filter is used to define the contents of a popup window for Windows help files.








Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








sdf-2.001/doc/ref/mblock.html010064400042570001753000000036420672242531600156100ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: block Macro










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










6.2. block Macro




Interface


The general syntax is:


  !block filter [; params]



The arguments are:






Name


Type


Default


Rule






filter


filter


 


 






params


rest


_NULL_


 







See Understanding Macro Interfaces, if necessary.




Description


The block macro marks the beginning of a "block" of text. The block is ended by the endblock macro.




Examples








Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








sdf-2.001/doc/ref/var_conv.sdf010064400042570001753000000026020622022216000157420ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Conversion Variables

H2: Purpose

These variables control the conversion process.

H2: Interface

!block table; groups; format=325
Name                Type        Purpose
Init-only:
OPT_CONFIG          string      the configuration library
OPT_LOOK            string      the look library
OPT_STYLE           string      the type of a document
OPT_TARGET          string      target format
OPT_NUMBER          integer     line numbering frequency (when pretty-printing programming languages)
Processing:
DEFAULT_TABLE_STYLE string      default style for tables (initially {{columns}})
DEFAULT_TAB_SIZE    integer     default tab size (initially 8)
!endblock

H2: Description

The {{init-only}} variables can only be set via {{CMD:sdf}}'s -D option or
via the {{MAC:init}} macro on the top line of a file.

The {{processing}} variables control the processing of [[SDF]] text
before it is passed to a format driver for conversion.

{{DEFAULT_TAB_SIZE}} is used when tabs are converted to spaces
within [[SDF]] files.

!end_topic
sdf-2.001/doc/ref/mendmacr.html010064400042570001753000000026720672242535500161340ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: endmacro Macro










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










6.16. endmacro Macro




Interface


The general syntax is:


  !endmacro



See Understanding Macro Interfaces, if necessary.




Description


The endmacro macro marks the end of a user-defined macro.




Examples








Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








tml">Contents | Parent Topic | 






SDF 2.001: SDF Reference: table Filter










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










5.31. table Filter




Interface


The general syntax is:


  !block table[; parameters]
  ...
  !endblock



The parameters are:






Name


Type


Rule






align


string


 






bgcolor


string


 






bmargin


integer


 






cellpadding


integer


 






cellspacing


integer


 






colaligns


string


 






coltags


string


 






colvaligns


string


 






delete


string


 






footings


integer


 






format


string


 






groups


string


 






headings


integer


 






keepindents


boolean


 






landscape


string


 






listitem


integer


 






lmargin


integer


 






narrow


boolean


 






niceheadings


boolean


 






nocalcs


boolean


 






noheadings


boolean


 






objects


string


 






oncell


string


 






parseline


string


 






placement


string


 






rmargin


integer


 






select


string


 






sort


string


 






style


string


 






tags


string


 






title


string


 






tmargin


integer


 






type


string


 






where


string


 






wide


boolean


 






wrap


integer


 







See Understanding Filter Interfaces, if necessary.




Description


The table filter specifies a table in TBL format. A brief description of each parameter is given below. A tutorial-style introduction to SDF's table features is also provided in the SDF User Guide.






Parameter


Description






align


alignment of table: one of Left, Center, Right, Inner, Outer






bgcolor


background colour for a table (HTML only)






bmargin


default bottom margin for table cells (MIF only)






cellpadding


padding size for table cells (HTML only)






cellspacing


spacing size between table cells (HTML only)






colaligns


a comma-separated list of horizontal alignments values (Left, Center, Right) for columns; alternatively, a single word containing the letters L, C and R






coltags


a comma-separated list of phrase styles to apply to columns






colvaligns


a comma-separated list of vertical alignments values (Top, Middle, Bottom, Baseline) for columns; alternatively, a single word containing the letters T, M, B and L






delete


a comma-separated list of columns to delete






footings


the number of footing rows at the end of the table






format


a comma-separated list of column width specifications; alternatively, a single number where each digit represents 10% of the space available to the table






groups


pattern of group-style rows (default is /:$/)






headings


the number of heading rows at the top of the table






landscape


display the table in landscape mode (MIF only)






listitem


the list indent level (e.g. 1) of this table






lmargin


default left margin for table cells (MIF only)






narrow


if set, the table will only be as wide as required; otherwise the table will span the available space






niceheadings


set to 0 to disable _ to space conversion in headings






nocalcs


set to 0 to disable calculation processing within a table






noheadings


suppress headings in output






objects


alias for coltags (coltags is preferred)






oncell


Perl code to execute for each cell (internal use only!)






parseline


column headings parsing line (if not the first row in the text)






placement


vertical placement of table: one of Float, Pagetop, Columntop, Lefttop, Righttop (MIF only)






rmargin


default right margin for table cells (MIF only)






select


a comma-separated list of columns to display






sort


a comma-separated list of columns to sort the data rows by






style


overall look of the table






tags


alias for coltags (coltags is preferred)






title


table caption






tmargin


default top margin for table cells (MIF only)






type


alias for style (style is preferred)






where


an expression to filter the data rows with






wide


table straddles the side head area of the page






wrap


the number of data rows to display in a physical row









Examples


A typical table is:


!block table; format=55; style="grid"; groups; title="Diary"
Time_of_day     Appointment
Morning:
10:00           Dentist
12:00           Lunch with friends
Afternoon:
15:00           Meeting on SDF
!endblock



The result is:



Diary



Time of day


Appointment






Morning:


 






10:00


Dentist






12:00


Lunch with friends






Afternoon:


 






15:00


Meeting on SDF













Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








sdf-2.001/doc/ref/fdefine.html010064400042570001753000000053760672242520300157420ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: define Filter










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










5.12. define Filter




Interface


The general syntax is:


  !block define[; parameters]
  table
  !endblock



The parameters are:






Name


Type


Rule






family


string


<\w+>






export


boolean


 







The table fields are:






Field


Category


Rule






Name


key


<\w+>






Value


optional


 







See Understanding Filter Interfaces, if necessary.




Description


The define filter is a convenient way of calling the define macro for several variables.


The family parameter is often used to specify a common prefix.


The export parameter can be used to export the variables to the target document system. See the export macro for further details on variable exporting.




Examples


!block define
Name            Value
COMPANY_NAME    ACME Mining
COMPANY_PHONE   1234 5678
!endblock



A simpler version is:


!block define; family="COMPANY"
Name    Value
NAME    ACME Mining
PHONE   1234 5678
!endblock









Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








sdf-2.001/doc/ref/sdngen.html010064400042570001753000000116010672242563600156160ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: sdngen - SDF Tuning File Generator










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










11.8. sdngen - SDF Tuning File Generator




Purpose


sdngen extracts SDF template information from a FrameMaker template.




Usage


usage  : sdngen [-h[help]] [-o[out_ext]]
         [-l[log_ext]] [-O[out_dir]] [-p para_root]
         [-f font_root] [-t tbl_root]
         [-e existing_template] file ...
purpose: generate an SDF template from a Frame one
version: 2.000    (SDF 2.001)



The options are:






Option


Description






-h


display help on options






-o


output file extension






-l


log file extension






-O


output to input file's (or explicit) directory






-p


default parent for a paragraph format






-f


default parent for a font format






-t


default parent for a table format






-e


existing template file









Description


The -h option provides help. If it is specified without a parameter, a brief description of each option is displayed. To display the attributes for an option, specify the option letter as a parameter.


By default, generated output goes to standard output. To direct output to a file per input file, use the -o option to specify an extension for output files. If the -o option is specified without a parameter, an extension of out is assumed.


Likewise, error messages go to standard error by default. Use the -l option to create a log file per input file. If the -l option is specified without a parameter, an extension of log is assumed.


By default, generated output and log files are created in the current directory. Use the -O option to specify an explicit output directory. If the -O option is specified without a parameter, the input file's directory is used.


The -p option can be used to specify the root paragraph format from which others are derived. The default paragraph root is Body.


The -f option can be used to specify the root font (i.e. phrase) format from which others are derived. The default font root is Emphasis.


The -t option can be used to specify the root table format from which others are derived. The default table root is Format A.


As formats often appear in families (e.g. Heading1, Heading2, etc.), sdngen will use the (alphabetically) previous format as the parent if it makes a better parent (i.e. there are less differences) than the default one.


If a template already exists, it can be specified using the -e option. In this case, sdngen will get as much information as it can from that file including:


    

  • the root format for each type

  • the order of formats within a type

  • the parent for each format.


Within each type, formats which are unknown in the existing template are output after those that are known.




Examples


To generate an SDF tuning file file:


     sdngen -osdn mytemplate.mif



This will create a template file called mytemplate.sdn.








Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








sdf-2.001/doc/ref/mundef.html010064400042570001753000000033240672242545500156200ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: undef Macro










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










6.41. undef Macro




Interface


The general syntax is:


  !undef name



The arguments are:






Name


Type


Default


Rule






name


symbol


 


 







See Understanding Macro Interfaces, if necessary.




Description


The undef macro undefines a variable.




Examples








Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








sdf-2.001/doc/ref/minsert.html010064400042570001753000000050740672242541000160160ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: insert Macro










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










6.27. insert Macro




Interface


The general syntax is:


  !insert macro [; missing]



The arguments are:






Name


Type


Default


Rule






macro


string


 


 






missing


string


ok


<ok|error|warning>







See Understanding Macro Interfaces, if necessary.




Description


The insert macro is used to insert the output of macro into an SDF document. missing determines the action if the macro isn't found:


    

  • ok - do nothing

  • warning - report a warning

  • error - report an error.



Note: In early versions of SDF, this macro was used to call user-defined macros. In SDF 2.000 or later, user-defined macros can be called using the same syntax as built-in macros.





Examples


# Insert the text of macro XXX if it's defined
!insert 'XXX'

# Insert the text of macro XXX; output an error if it's not defined
!insert 'XXX'; 'error'

# Same as the previous example
!XXX









Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








sdf-2.001/doc/ref/mexport.html010064400042570001753000000036260672242536200160420ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: export Macro










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










6.18. export Macro




Interface


The general syntax is:


  !export name



The arguments are:






Name


Type


Default


Rule






name


symbol


 


 







See Understanding Macro Interfaces, if necessary.




Description


The export macro ensures that the target documentation system receives the value of the nominated variable each time it changes. If the variable is currently defined, the target system is immediately notified of its value.




Examples








Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








sdf-2.001/doc/ref/fbox.html010064400042570001753000000050240672242516600152760ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: box Filter










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










5.7. box Filter




Interface


The general syntax is:


  !block box[; parameters]
  ...
  !endblock



The parameters are:






Name


Type


Rule






align


string


 






listitem


integer


 






narrow


boolean


 






wide


boolean


 






lines


boolean


 






bgcolor


string


 






fill


integer


 







See Understanding Filter Interfaces, if necessary.




Description


The box filter is used to box a region of text. The lines parameter can be used to treat each line as a line within a paragraph - without this, the contents is treated as normal SDF.


The other parameters have the same meanings as they do for the table filter.




Limitations & Future Directions


Some of the output drivers (e.g. the MIF driver) do not support nested tables, so tables within the box may be ignored.








Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








 Topic | Next Topic 
Home | Catalog










5.7. box Filter




Interface


The general syntax is:


  !block box[; parameters]
  ...
  !endblock



The parameters are:






Name


Typesdf-2.001/doc/ref/melse.html010064400042570001753000000026560672242534100154500ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: else Macro










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










6.10. else Macro




Interface


The general syntax is:


  !else



See Understanding Macro Interfaces, if necessary.




Description


The else macro delimits sections within conditional text.




Examples








Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








sdf-2.001/doc/ref/melsif.html010064400042570001753000000035100672242534600156150ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: elsif Macro










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










6.12. elsif Macro




Interface


The general syntax is:


  !elsif value



The arguments are:






Name


Type


Default


Rule






value


condition


 


 







See Understanding Macro Interfaces, if necessary.




Description


The elsif macro delimits sections within conditional text. It is identical in operation to the elseif macro.




Examples








Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








sdf-2.001/doc/ref/var_file.sdf010064400042570001753000000017420661222265100157320ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: File Information Variables

H2: Purpose

These variables provide information on the file [[SDF]] is
currently processing.

H2: Interface

!block table; format=325
Name            Type        Purpose
FILE_PATH       string      current pathname (e.g. {{/doc/sdf/mydoc.sdf}})
FILE_DIR        string      directory of current filename (e.g. {{/doc/sdf}})
FILE_BASE       string      base component of current filename (e.g. {{mydoc}})
FILE_EXT        string      extension of current filename (e.g. {{sdf}})
FILE_MODIFIED   datetime    time when this file was last modified
!endblock

#H2: Description

!end_topic

sdf-2.001/doc/ref/classes/004075500042570001753000000000000672243774000151125ustar00iancmtr00000400000236sdf-2.001/doc/ref/classes/corganis.sdf010064400042570001753000000015370645236237200174160ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 16-May-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: organisations Class

H2: Interface

!class_interface "organisations"

H2: Description

The {{organisations}} filter is used to declare and/or format objects in
the {{organisations}} class. The attributes supported are:

!block table
Attribute       Description
Name            the organisation name
Jump            the organisation URL, if any
!endblock

H2: Examples

See the {{FILE:objects.sdm}} file within SDF's {{FILE:stdlib}}
directory.

#H2: Limitations & Future Directions
sdf-2.001/doc/ref/classes/creferen.sdf010064400042570001753000000020010645237044400173640ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 16-May-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: references Class

H2: Interface

!class_interface "references"

H2: Description

The {{references}} filter is used to declare a set of
references and matching documents. It can also be used to
build a table of references within a document.

The attributes supported are:

!block table
Attribute       Description
Reference       the document code
Document        the document name
Version         the document version
Status          the document status
Jump            the URL, if any
!endblock

H2: Examples

See the {{FILE:sdf.sdm}} and {{FILE:document.reg}} files within SDF's
{{FILE:sdf}} directory.

#H2: Limitations & Future Directions
sdf-2.001/doc/ref/classes/cproduct.sdf010064400042570001753000000015010645236302400174160ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 16-May-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: products Class

H2: Interface

!class_interface "products"

H2: Description

The {{products}} filter is used to declare and/or format objects in
the {{products}} class. The attributes supported are:

!block table
Attribute       Description
Name            the product name
Jump            the product URL, if any
!endblock

H2: Examples

See the {{FILE:objects.sdm}} file within SDF's {{FILE:stdlib}}
directory.

#H2: Limitations & Future Directions
sdf-2.001/doc/ref/classes/cterms.sdf010064400042570001753000000024120647527267200171070ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 16-May-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: terms Class

H2: Interface

!class_interface "terms"

H2: Description

The {{terms}} filter is used to declare and/or format objects in
the {{terms}} class. The attributes supported are:

!block table
Attribute       Description
Term            the term name
Definition      the explanation for the term
!endblock

H2: Examples

A configuration file may have
the following declaration of terms:

E:  !block terms; data
E:  Term     Definition
E:  SDF      Simple Document Format
E:  SQL      Structured Query Language
E:  !endblock

These can then be inserted into a document as follows:

E:  !block terms
E:  Term     Definition
E:  SDF
E:  SQL
E:  WWW      World Wide Web
E:  !endblock

Note that the definition for a term already declared will be inserted
if none is provided. Furthermore, new terms (like WWW above) can be
inserted and added to the configured ones.

#H2: Limitations & Future Directions
sdf-2.001/doc/ref/reasdf.sdf010064400042570001753000000013430630476377200154200ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: About This Manual

H2: Purpose

This manual is a reference for [[SDF]] - a documentation
system for software developers.

H2: Scope

This manual contains detailed reference material on most SDF features.

The following documents may also be of interest:

* [[SDF_DOC_WP]]
* [[SDF_DOC_UG]]
* [[SDF_DOC_QR]]
* [[SDF_DOC_GG]].

H2: Amendments

!SDF_AMENDMENTS
sdf-2.001/doc/ref/sdfapi.sdf010064400042570001753000000000750630252073000154020ustar00iancmtr00000400000236# Extract the documentation from the script
!getdoc "sdfapi"
sdf-2.001/doc/ref/sprepend.html010064400042570001753000000032150672242566600161650ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: PrependText










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










12.5. PrependText




Purpose


PrependText is used within a paragraph event handler to prepend SDF before a paragraph.




Interface


  &PrependText(@sdf)



12.5..1. Description


The argument is the list of SDF paragraphs to prepend.




Examples


To prepend a line before each level 1 heading:


  !on paragraph 'H1';; &AppendText('Line:')









Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








sdf-2.001/doc/ref/in_fmt.sdf010064400042570001753000000021270640471134600154200ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
H1: File Formats

H2: Overview

The file formats used are summarised below.

!block table; tags="FMT"
Name      Purpose
INI       defines initialisation data
SDG       defines formatting rules for {{CMD:sdfget}}
TBL       defines a table
!endblock

Further details on these are provided below.

Note: {{sdm}}, {{sds}} and {{sdn}} files are normal [[SDF]] files used for
normal modules, style modules and tuning modules respectively.

# Include the subsections, placing each at the top of a page (or after a line)
!if $var{'OPT_TARGET'} eq 'txt'
    !on paragraph 'H2'; h2top; &PrependText("Line:")
!else
    !on paragraph 'H2'; h2top; $attr{'top'} = 1
!endif
!block topics
Topic
fmt_ini
fmt_sdg
fmt_tbl
!endblock
!off paragraph h2top
sdf-2.001/doc/ref/sappendt.sdf010064400042570001753000000013200635011350400157440ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: AppendText

H2: Purpose

{{S:AppendText}} is used within a paragraph event handler to
add [[SDF]] after a paragraph.

H2: Interface

E:  &AppendText(@sdf)

H3: Description

The argument is the list of [[SDF]] paragraphs to append.

H2: Examples

To append a line after each level 1 heading:

E:  !on paragraph 'H1';; &AppendText('Line:')
sdf-2.001/doc/ref/mgetcode.html010064400042570001753000000037110672242536600161320ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: getcode Macro










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










6.20. getcode Macro




Interface


The general syntax is:


  !getcode filename [; filter] [; params]



The arguments are:






Name


Type


Default


Rule






filename


string


 


 






filter


filter


_NULL_


 






params


rest


_NULL_


 







See Understanding Macro Interfaces, if necessary.




Description


The getcode macro extracts the "non-documentation" from source code.




Examples








Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








sdf-2.001/doc/ref/in_macif.html010064400042570001753000000123350672242573000161050ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: Understanding Macro Interfaces










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog










C. Understanding Macro Interfaces




C.1. Overview


General Syntax


The general syntax for using this macro is shown first, including the order of the arguments, if any.


Arguments


If a macro has one or more arguments, these are listed in a table containing the following columns:


    

  • Name - the argument name

  • Type - the argument type

  • Default - the default value, if any

  • Rule - the pattern, if any, used to validate the value.


Argument Types


The supported set of argument types are:






Type


Description






Common:


 






string


a string






integer


an integer






boolean


either 1 or 0






Special:


 






symbol


a symbolic name






filter


a filter name






rest


the rest of the arguments






eventid


an event tag






condition


a logical expression







The special types are needed for some of SDF's built-in macros including define, include, on and if - they are rarely needed for normal macros.


Default Values


For default values within argument tables:


    

  • the empty string means there is no default

  • the symbol _NULL_ means the default is the empty string.




C.2. Rules


Rule Types


If you wish, arguments can be validated using a rule. Rules are either:



Patterns


A pattern is a Perl regular expression which the argument value is matched against. Patterns are enclosed in angle brackets to differentiate them from normal Perl expressions. Typical patterns are given in the table below.






Pattern


Explanation






<\w+>


one or more characters in A-Z, a-z, 0-9 and '_'






<\d{4}>


a 4 digit number






<on|off>


a string which is either "on" or "off"






<XMIT-.*>


a string which begins with "XMIT-"







General Perl Expressions


More complex rules are required when:


    

  • the regular expression does not apply to the whole value

  • the regular expression is case-insensitive.


In these cases, a general Perl expression can be used as the rule. Within the expression, $_ is the value of the argument. Examples are:






Expression


Explanation






/\d/


a digit exists somewhere in the string






/^(on|off)$/i


value is either "on" or "off" (case insensitive)








Note: A pattern is simply a short-hand notation for the general Perl expression below:


        /^(pattern)$/



Pattern notation is provided as it makes rules easier to read and write. (Pattern-style validation typically covers 80% or more of validation rules so improving the readability of patterns has a large impact on the overall readability.)










Contents | Parent Topic | Previous Topic | Next Topic 
Home | Catalog








he default value, if any

  • Rule - the pattern, if any, used to validate the value.

    Argument Types
    

    The supported set of argument types are:
    

    

    

Type









SDF 2.001: SDF Reference: Conversion Variables




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    13.2. Conversion Variables
    

    

    Purpose
    

    These variables control the conversion process.
    

    

    Interface
    

    

    

Name


Type


Purpose


    

    

Init-only:


 


 


    

    

OPT_CONFIG


string


the configuration library


    

    

OPT_LOOK


string


the look library


    

    

OPT_STYLE


string


the type of a document


    

    

OPT_TARGET


string


target format


    

    

OPT_NUMBER


integer


line numbering frequency (when pretty-printing programming languages)


    

    

Processing:


 


 


    

    

DEFAULT_TABLE_STYLE


string


default style for tables (initially columns)


    

    

DEFAULT_TAB_SIZE


integer


default tab size (initially 8)


    

    


    

    Description
    

    The init-only variables can only be set via sdf's -D option or via the init macro on the top line of a file.
    

    The processing variables control the processing of SDF text before it is passed to a format driver for conversion.
    

    DEFAULT_TAB_SIZE is used when tabs are converted to spaces within SDF files.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/moutput.html010064400042570001753000000044010672242543300160500ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: output Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.34. output Macro
    

    

    Interface
    

    The general syntax is:
    

      !output outfile

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

outfile


string


 


 


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The output macro dynamically changes the output file being used. It can be used in the following ways:
    

      

    1. output "filename"

    2. output ">filename"

    3. output "-"
    

    The first form changes the output file to be filename. The second form appends the output onto the filename given. The third form closes the (current) output file, if any.
    

    

    Examples
    

    To be completed...
    

    

    Limitations & Future Directions
    

    html is the only target which currently supports this macro.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/in_var.html010064400042570001753000000033210672242571000156070ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: Miscellaneous Variables




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    13. Variables
    

    

    13.1. Overview
    

    The categories of predefined variables are:
    

      

    1. Conversion variables

    2. Document variables

    3. File variables

    4. Miscellaneous variables.
    

    Date-time variables are in units of seconds since January 1, 1970. To format a time, use the FormatTime subroutine.
    

    Further details on each group of variables are provided below.
    

    Conversion Variables
    

    Document Variables
    

    File Information Variables
    

    Miscellaneous Variables
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf. -->


SDF 2.001: SDF Reference: Miscellaneous Variables




    

    

    

    Contents | Parent Topic | sdf-2.001/doc/ref/in_filif.html010064400042570001753000000071310672242572300161170ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: Understanding Filter Interfaces




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    B. Understanding Filter Interfaces
    

    

    B.1. Overview
    

    General Syntax
    

    The general syntax for using each filter is shown first. By convention, the filter is shown using the block and endblock macros, although filters can also be used with other macros, including include and execute.
    

    Parameters
    

    If a filter has one or more optional parameters, these are listed in a table containing the following columns:
    

      

    • Name - the parameter name

    • Type - the parameter type

    • Rule - the pattern, if any, used to validate the value.
    

    Parameter Types and Rules
    

    Parameter types and rules follow the same conventions as macro argument types and rules. Refer to Understanding Macro Interfaces for details.
    

    

    B.2. Data Tables
    

    Table Fields
    

    Providing data to a filter via a table is a common idiom in SDF as using tables makes it easy to add additional columns later on.
    

    If a filter expects a table of data in TBL format, the fields in the table of data are listed in a table containing the following columns:
    

      

    • Field - the field name

    • Category - key, mandatory or optional

    • Rule - the pattern, if any, used to validate the value.
    

    Table Field Categories
    

    The supported table field categories are explained below.
    

    

    

Category


Description


    

    

key


a unique value must be provided for each row


    

    

mandatory


a value must be provided for each row


    

    

optional


a value is optional


    

    


    Validating Table Fields
    

    As validating table fields can reduce performance quite a bit, the sdf program doesn't validate them by default. To enable table field validation, use the -v option like this:
    

      sdf -v99 ...

    

    Typically, this is only needed when a filter isn't working as you'd expect.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/moff.html010064400042570001753000000037540672242542600152760ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: off Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.32. off Macro
    

    

    Interface
    

    The general syntax is:
    

      !off type id

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

type


symbol


 


<paragraph|phrase|macro|filter|table>


    

    

id


eventid


 


<\w+>


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The off macro disables an event.
    

    See Event Processing in the SDF User Guide for further details.
    

    

    Examples
    

    To be completed ...
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/in_filt.sdf010075500042570001753000000063750672210516400156020ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
H1: Filters

H2: Overview

The filters available are summarised below.

!block table; tags="FILT"; groups
Name            Purpose
General:
table           tabular data
note            a note
quote           a quotation
abstract        the abstract for a paper
title           title block for a memo, fax or minutes
Line based:
example         fixed-width text (e.g. source code)
verbatim        fixed-width text, ignoring embedded symbols
ascii_graphic   fixed-width text, wide enough for ASCII graphics
nofill          a set of lines
address         an address
Components:
front           front section of a document
about           about section of a document
appendix        change headings to appendix style
plain           change headings to plain style
Formatting:
box             surround a region of text with a box
changed         mark a block of text as changed
sections        paragraphs are sections
namevalues      format a set of name-value pairs (e.g. as used in a title block)
sdf             apply arbitrary phrase attributes to text
pod             embedded POD
File processing:
comment         ignore text
topics          include a set of sub-topics
inline          embed text into target format (e.g. [[HTML]])
script          execute text as a [[Perl]] script
end             process text at the end
get             extract embedded documentation
Configuration:
langdefs        define vgrind-like language definitions
define          define a block of variables
default         provide defaults for a block of variables
simple          generic filter for building others
datestrings     define strings used within dates
Help:
hlp_header      table of jumps at the top of a help topic
hlp_window      contents of a help popup window
!endblock

Further details on these are provided below.

# Define the help to be placed after each filter interface
!macro FILTER_INTERFACE_END
See {{SECT:Understanding Filter Interfaces}}, if necessary.
!endmacro

# Include the subsections, placing each at the top of a page (or after a line)
!if $var{'HTML_TOPICS_MODE'} || $var{'HTML_SUBTOPICS_MODE'}
    # do nothing
!elsif $var{'OPT_TARGET'} eq 'html' || $var{'OPT_TARGET'} eq 'txt'
    !on paragraph 'H2'; h2top; &PrependText("Line:")
!else
    !on paragraph 'H2'; h2top; $attr{'top'} = 1
!endif
!block topics
Topic
filters/fabout
filters/fabstrac
filters/faddress
filters/fappendi
filters/fascii_g
filters/fbox
filters/fchanged
filters/fcomment
filters/fdatestr
filters/fdefault
filters/fdefine
filters/fend
filters/fexample
filters/ffront
filters/fget
filters/fhlp_hea
filters/fhlp_win
filters/finline
filters/flangdef
filters/fnameval
filters/fnofill
filters/fnote
filters/fplain
filters/fpod
filters/fquote
filters/fscript
filters/fsdf
filters/fsection
filters/fsimple 
filters/ftable
filters/ftitle
filters/ftopics
filters/fverbati
!endblock

!if !($var{'HTML_TOPICS_MODE'} || $var{'HTML_SUBTOPICS_MODE'})
!off paragraph h2top
!endif
re sections
namevalues      format a set of name-value pairs (e.g. as used in a title block)
sdf             apply arbitrary phrase attributes to text
pod             embedded POD
File processing:
comment         ignore text
topics          include a set of ssdf-2.001/doc/ref/fmt_tbl.sdf010064400042570001753000000065320622022216000155620ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: TBL Format

H2: Purpose

{{TBL}} format is a text-based format for storing tabular data.

H2: Overview

The basic rules are:

* blank lines and comment lines are ignored,
* the first data line specifies the record format,
* each remaining data line specifies a single record.

Comment lines begin with # as the first non-whitespace character.

H2: Record Formats

For a given table, all records have the same format.
The record format is either:

* {{delimited}} - fields are separated by a special character, or
* {{fixed-width}} - fields are defined by column positions.

An example of delimited format is given below.

!block example
# A simple TBL example
Name:Age:Phone:Addr
Bill:42:397 1234:14 Smith St, New Farm
Sarah:37:892 4321:105 Brown St, Chelmer
Joe:44:365 7890:6 Royal Av, Buranda
!endblock

An example of fixed-width format is given below.

!block example
# A simple TBL example
Name    Age     Phone           Addr
Bill    42      397 1234        14 Smith St, New Farm
Sarah   37      892 4321        105 Brown St, Chelmer
Joe     44      365 7890        6 Royal Av, Buranda
!endblock

Note: Tabs in fixed-width records are assumed to be 8 spaces wide.

H2: Input Format Specification

The first data line is called the {{input format specification}}.
It specifies:

* the name and order of the fields in each record
* the record format - delimited or fixed-width

Field names can contain:

* alphanumeric characters (A-Z, a-z, 0-9)
* the underscore character (_)

If the first character after the first field name is a space or tab,
the format is assumed to be {{fixed width}}. Otherwise, the format is
{{delimited}} with fields separated by the special character found.

H2: Multi-line Fields

Generally, each data line specifies a single record.
However, if the last field begins with the sequence '<<',
then it is a multi-line field terminated by the first line
beginning with '>>'. Multi-line fields are supported by both
record formats.

Within a multi-line field, blank lines and lines starting
with # are treated as part of that field. i.e. it is not
possible to embed a comment line within a multi-line field.

An example of a table containing multi-line fields is given below.

!block example
# A simple TBL example with multi-line fields
Name    Age     Phone           Addr
Bill    42      397 1234        <<
14 Smith St
New Farm QLD 4005
>>
Sarah   37      892 4321        <<
105 Brown St
Chelmer QLD 4068
>>
Joe     44      365 7890        <<
6 Royal Av
Buranda QLD 4102
>>
!endblock

H2: Special Characters in Fields

For delimited fields:

^ If a field contains the delimiter character or the double quote character,
  it must be enclosed in double quotes.
+ A double quote character within a field is represented by two double quotes.
+ Leading whitespace is kept.
+ Trailing whitespace is kept.

For fixed-width fields:

^ Leading whitespace is kept.
+ Trailing whitespace is removed.

Note: Multi-line fields are enclosed by the << and >> symbols so none
of the rules above apply to them.

!end_topic
sdf-2.001/doc/ref/mmacro.html010064400042570001753000000033550672242542000156140ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: macro Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.30. macro Macro
    

    

    Interface
    

    The general syntax is:
    

      !macro name

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

name


symbol


 


 


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The macro macro marks the beginning of a user-defined macro.
    

    

    Examples
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/var_doc.sdf010064400042570001753000000026640645716555200156010ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Document Variables

H2: Purpose

These variables are related to the document [[SDF]] is
currently processing.

H2: Interface

!block table; groups; format=325
Name                Type        Purpose
Control:
DOC_TOC             integer     table of contents level
DOC_TWO_SIDES       boolean     build a two-sided document
Book controls:
DOC_LOF             boolean     build a list of figures
DOC_LOT             boolean     build a list of tables
DOC_IX              boolean     build an index
Information:
DOC_PATH            string      the full pathname of the current document
DOC_DIR             string      the directory of the current document
DOC_BASE            string      the base (filename) of the current document
DOC_EXT             string      the extension of the current document
DOC_SHORT           string      the base and extension of the current document
DOC_START           datetime    the time document conversion started
DOC_MODIFIED        datetime    the most recent modification time of files visited so far
!endblock

#H2: Description


!end_topic
sdf-2.001/doc/ref/msubsect.html010064400042570001753000000050560672242545300161710ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: subsections Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.40. subsections Macro
    

    

    Interface
    

    The general syntax is:
    

      !subsections labels [; prefix] [; layout]

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

labels


string


 


 


    

    

prefix


string


Topic


<Topic|Noprefix|noprefix>


    

    

layout


string


Left


<Left|Center|Right|None|left|center|right|none>


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The subsections macro specifies the subsections in a topic.
    

    

    Examples
    

    Typical usage is:
    

       H1: MyApp
   !subsections "Purpose,Usage,Description,Examples"

    

    In this case, the subsections macro changes the id generated for the headings listed to:
    

       MyApp - heading

    

    For HTML, it will also generate a line of jumps to the headings.
    

    

    Limitations & Future Directions
    

    html is currently the only target for which a jump line is generated.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/mrestric.html010064400042570001753000000043330672242544000161650ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: restrict Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.36. restrict Macro
    

    

    Interface
    

    The general syntax is:
    

      !restrict name

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

name


string


 


 


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The restrict macro declares a restricted family of variables. If a variable begins with a restricted prefix, then it must be declared via the define filter.
    

    This feature aims to catch errors caused by authors using a bad variable name. For example, if an author types
    

       !define DOC_NAMe "My Document"

    

    but meant to type
    

       !define DOC_NAME "My Document"

    

    then an error will be raised as DOC_NAMe is an unknown variable within the DOC family.
    

    

    Examples
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/sdf.sdf010064400042570001753000000000720630252072600147120ustar00iancmtr00000400000236# Extract the documentation from the script
!getdoc "sdf"
sdf-2.001/doc/ref/fdefault.html010064400042570001753000000054140672242520000161220ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: default Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.11. default Filter
    

    

    Interface
    

    The general syntax is:
    

      !block default[; parameters]
  table
  !endblock

    

    The parameters are:
    

    

    

Name


Type


Rule


    

    

family


string


<\w+>


    

    

export


boolean


 


    

    


    The table fields are:
    

    

    

Field


Category


Rule


    

    

Name


key


<\w+>


    

    

Value


optional


 


    

    


    See Understanding Filter Interfaces, if necessary.
    

    

    Description
    

    The default filter is a convenient way of calling the default macro for several variables.
    

    The family parameter is often used to specify a common prefix.
    

    The export parameter can be used to export the variables to the target document system. See the export macro for further details on variable exporting.
    

    

    Examples
    

    !block default
Name            Value
COMPANY_NAME    ACME Mining
COMPANY_PHONE   1234 5678
!endblock

    

    A simpler version is:
    

    !block default; family="COMPANY"
Name    Value
NAME    ACME Mining
PHONE   1234 5678
!endblock

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



nterface

    The general syntax is:
    

      !block default[; parameters]
  table
  !endblock

    

    The parameters are:
    
SDF 2.001: SDF Reference: slide_down Macro
    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    6.38. slide_down Macro
    

    

    Interface
    

    The general syntax is:
    

      !slide_down

    

    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The slide_down macro moves subsequent headings down one level.
    

    

    Examples
    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    
sdf-2.001/doc/ref/sdfbatch.sdf010064400042570001753000000000770630252073000157140ustar00iancmtr00000400000236# Extract the documentation from the script
!getdoc "sdfbatch"
sdf-2.001/doc/ref/mscript.html010064400042570001753000000033550672242544300160240ustar00iancmtr00000400000236SDF 2.001: SDF Reference: script Macro
    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    6.37. script Macro
    

    

    Interface
    

    The general syntax is:
    

      !script code

    

    The arguments are:
    

    

    

Name
sdf-2.001/doc/ref/faddress.html010064400042570001753000000035130672242515700161340ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: address Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.4. address Filter
    

    

    Interface
    

    The general syntax is:
    

      !block address
  ...
  !endblock

    

    See Understanding Filter Interfaces, if necessary.
    

    

    Description
    

    The address filter is used to format an address. This typically implies:
    

      

    • for PostScript, the paragraphs have no space between them

    • for HTML, the paragraphs are given ADDRESS tags.
    

    

    Examples
    

    A typical letter starts like this:
    

    !block address
Mr I.M. Lucky
13 Horseshoe Drive
Brisbane Q 4001
!endblock

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/in_pstyl.html010064400042570001753000000070720672242547200162060ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: Paragraph Styles




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    8. Paragraph Styles
    

    The paragraph styles available are summarised below.
    

    

    

Name


Purpose


    

    

Headings:


 


    

    

Hn


normal heading at level n (1..6)


    

    

An


appendix heading at level n (1..6)


    

    

Pn


plain heading at level n (1..6)


    

    

Lists:


 


    

    

Ln


plain list item or paragraph at level n (1..6)


    

    

LFn


first entry in an ordered list at level n (1..6)


    

    

LNn


next entry in an ordered list at level n (1..6)


    

    

LUn


unordered list item at level n (1..6)


    

    

Notes:


 


    

    

Note


a single paragraph note


    

    

NB


start of a multi-paragraph note


    

    

NE


end of a multi-paragraph note


    

    

Miscellaneous:


 


    

    

E


example text (i.e. fixed width)


    

    

V


verbatim text (i.e. fixed width, ignore escapes)


    

    

E80


wide example text


    

    

Line


horizontal line


    

    

N


normal text


    

    

NV


name-value pair (i.e. hanging indent)


    

    

PB


page break


    

    

Sign


signature for a memo, etc.


    

    


    The following special styles are also available.
    

    

    

Symbol


Purpose


    

    

>


verbatim text


    

    

* .. ******


unordered list item at level 1..6


    

    

- .. -----


unordered list item at level 2..6


    

    

^ .. ^^^^^^


first entry in an ordered list at level 1..6


    

    

+ .. ++++++


next entry in an ordered list at level 1..6


    

    

. .. ......


plain list item or paragraph at level 1..6


    

    


    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/flangdef.html010064400042570001753000000032230672242522600161020ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: langdefs Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.20. langdefs Filter
    

    

    Interface
    

    The general syntax is:
    

      !block langdefs
  ...
  !endblock

    

    See Understanding Filter Interfaces, if necessary.
    

    

    Description
    

    The langdefs filter is used to configure programming language properties used by SDF's pretty-printing support. The contents is one or more vgrind definitions.
    

    

    Examples
    

    See langdefs.sdm within SDF's stdlib directory.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



. SDF is freely
     available from http://www.mincom.com/mtr/sdf. -->


SDF 2.001: SDF Reference: langdefs Filter




    

    

    

    Contents | Parent Topic | >Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
H1: Phrase Styles

The phrase styles available are summarised below.

!block table; groups
Tag         Description                     Sample_Output
Emphasis:
1           1st level emphasis (default)    {{1:emphasis 1}}
2           2nd level emphasis              {{2:emphasis 2}}
3           3rd level emphasis              {{3:emphasis 3}}
Formatting:
N           normal                          {{N:some normal text}}
I           italic                          {{I:some italic text}}
B           bold                            {{B:some bold text}}
U           underline                       {{U:some underline text}}
EX          example                         {{EX:some example text}}
Types:
EMAIL       email address                   {{EMAIL:ianc@mincom.com}}
F (or FILE) Filename                        {{FILE:myfile.sdf}}
SECT        Section                         {{SECT:Paragraphs}}
URL         Uniform Resource Locator        {{URL:http://www.mincom.com}}
Classes:
DOC         document title                  {{DOC:SDF User Guide}}
REF         reference (document code)       {{REF:MTR-SDF-0002}}
ORG         organisation                    {{ORG:Mincom}}
PRD         product                         {{PRD:MIMS}}
Specials:
E (or CHAR) escape (i.e. special character) E
S           spaces are non-breaking         {{S:section 2.1}}
IMPORT      name of a figure to import      {{IMPORT:key}}
URLs:
http
ftp
telnet
news
gopher
wais
https
snews
!endblock

Note: When emphasising text, it is generally better to
use an emphasis style rather than a formatting style as the best way of
doing so depends on the output format.
sdf-2.001/doc/ref/fnote.html010064400042570001753000000046370672242523700154630ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: note Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.23. note Filter
    

    

    Interface
    

    The general syntax is:
    

      !block note[; parameters]
  ...
  !endblock

    

    The parameters are:
    

    

    

Name


Type


Rule


    

    

label


string


 


    

    


    See Understanding Filter Interfaces, if necessary.
    

    

    Description
    

    The note filter is used to specify a note. The label parameter can be used to specify a label. The default label is "Note:".
    

    

    Examples
    

    !block note; label='Example:'
And some text inside

a multi-line note
!endblock

    

    The result is:
    

    
Example:And some text inside
    

    a multi-line note
    

    

    If you want the label to have a line to itself, leave the first line blank like this:
    

    !block note

And some more text inside

another multi-line note
!endblock

    

    The result is:
    

    
Note: 
    

    And some more text inside
    

    another multi-line note
    

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/in_fmt.html010064400042570001753000000040740672242514300156130ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: TBL Format




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    4. File Formats
    

    

    4.1. Overview
    

    The file formats used are summarised below.
    

    

    

Name


Purpose


    

    

INI


defines initialisation data


    

    

SDG


defines formatting rules for sdfget


    

    

TBL


defines a table


    

    


    Further details on these are provided below.
    

    
Note: sdm, sds and sdn files are normal SDF files used for normal modules, style modules and tuning modules respectively.

    

    INI Format
    

    SDG Format
    

    TBL Format
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/mimport.html010064400042570001753000000046320672242537500160350ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: import Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.23. import Macro
    

    

    Interface
    

    The general syntax is:
    

      !import filename [; params]

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

filename


string


 


 


    

    

params


rest


_NULL_


 


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The import macro imports a figure. If the filename is not given an extension, the extension is found using the search rules below.
    

    

    

When generating


The search order is


    

    

PostScript


epsi, eps, wmf, mif, gif


    

    

HTML


jpeg, jpg, png, gif


    

    

Windows Help


bmp


    

    


    The title argument can be used to add a figure title.
    

    See Figures within the SDF User Guide for further details.
    

    

    Examples
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/in_oattr.sdf010064400042570001753000000021370622022216000157470ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
H1: Phrase Attributes

The phrase attributes available are summarised below.

!block table; tags="OATTR"; groups
Name            Purpose
Formatting:
family          font family
size            font size
color           text colour
bold            enable bold
italics         enable italics
underline       enable underline
changed         enable change bars
Objects:
expand          replace an object name with its longer form
shrink          replace an object name with its shorter form
Hypertext:
id              define a hypertext target
jump            define a hypertext jump (i.e. URL)
Indexes:
index           define an index entry
index_type      specify the index type
Help specific:
hlp.popup       jump to a popup window
!endblock
sdf-2.001/doc/ref/mline.html010064400042570001753000000037060672242541600154470ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: line Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.29. line Macro
    

    

    Interface
    

    The general syntax is:
    

      !line lineno [; filename] [; context]

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

lineno


integer


 


 


    

    

filename


string


_NULL_


 


    

    

context


string


line


 


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The line macro can be used to change the line number output within error and warning messages.
    

    

    Examples
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/fabstrac.html010064400042570001753000000042240672242515500161240ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: abstract Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.3. abstract Filter
    

    

    Interface
    

    The general syntax is:
    

      !block abstract
  ...
  !endblock

    

    See Understanding Filter Interfaces, if necessary.
    

    

    Description
    

    The abstract filter is used to specify an abstract for a technical paper. This typically implies:
    

      

    • for PostScript, the text is italics and indented from both margins

    • for HTML, the text is given an appropriate heading.
    

    

    Examples
    

    A typical paper starts like this:
    

    !init OPT_STYLE="paper"
!define DOC_NAME "Internet Management Tools"
!define DOC_AUTHOR "I. M. Wise"
!build_title

!block abstract
The internet is out of control. This paper ...

# more paragraphs go here

!endblock

H1: Introduction

# The interesting stuff goes here

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/fnameval.html010064400042570001753000000051320672242523200161230ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: namevalues Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.21. namevalues Filter
    

    

    Interface
    

    The general syntax is:
    

      !block namevalues[; parameters]
  table
  !endblock

    

    The parameters are:
    

    

    

Name


Type


Rule


    

    

format


string


 


    

    


    The table fields are:
    

    

    

Field


Category


Rule


    

    

Name


optional


 


    

    

Value


optional


 


    

    


    See Understanding Filter Interfaces, if necessary.
    

    

    Description
    

    The namevalues filter is used to format a table of name-value pairs. Each name is output in bold. For PostScript output, the names are placed in the sidehead.
    

    

    Examples
    

    !block namevalues
Name            Value
Description:    Find the maximum of two numbers
Module:         general
Author:         Joe Bloggs
!endblock

    

    The result is:
    

    

    

Description:


Find the maximum of two numbers


    

    

Module:


general


    

    

Author:


Joe Bloggs


    

    


    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/sfindfil.sdf010064400042570001753000000036710637723560400157560ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: FindFile

H2: Purpose

This routine is used to search for include files, imported objects,
configuration modules and templates.

H2: Interface

E:  $fullname = &FindFile($filename, $image);

H2: Description

If {{filename}} is not found, {{fullname}} should be an empty string.
If the file is found, the pathname of the file is returned,
otherwise the empty string is returned. If {{image}} is true,
a target-specific set of extensions is searched for,
complete with implicit image format conversion.

H2: Examples

The default implementation is:

!block example; wide; lang="Perl"
sub FindFile {
    local($filename, $image) = @_;
    local($fullname);

    # Get the list of directories to search
    use Cwd;
    my @dirs = ('.');
    my $dir = $var{'DOC_DIR'};
    push(@dirs, $dir) if $dir ne cwd();
    push(@dirs, @include_path, "$'sdf_lib/stdlib", $'sdf_lib);

    # Do the search
    if ($image) {
        my $context = $var{'OPT_TARGET'};
        my @exts = @{$'SDF_IMAGE_EXTS{$context} || $'SDF_IMAGE_EXTS{'ps'}};
        return &'NameFindOrGenerate($filename, \@dirs, \@exts, $context);
    }
    else {
        return &'NameFind($filename, @dirs);
    }
}
!endblock

In order to tightly integrate [[SDF]] with certain development
environments, it is occasionally necessary to override this routine
in a configuration module. For example:

!block example
!block script
sub FindFile {
    local($filename, $image) = @_;
    local($fullname);

    # Search using our SCM
    $fullname = &'SearchSCM($filename, $image);

    # Return result
    return $fullname;
}
!endblock
!endblock

sdf-2.001/doc/ref/fsection.html010064400042570001753000000035150672242525400161530ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: sections Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.29. sections Filter
    

    

    Interface
    

    The general syntax is:
    

      !block sections
  ...
  !endblock

    

    See Understanding Filter Interfaces, if necessary.
    

    

    Description
    

    The sections filter is used to create section jumps for html and hlp outputs: for these formats, the text of each paragraph (excluding punctuation) is assumed to be the title of a section within this document. For other outputs, the text is unchanged.
    

    

    Examples
    

    
There are lots of new things in this version including:

!block sections
. Topics mode
. HTML headers and footers
!endblock

Further details are given below.

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/in_macif.sdf010064400042570001753000000057620645220753000157170ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Understanding Macro Interfaces

H2: Overview

H3: General Syntax

The general syntax for using this macro is shown first, including
the order of the arguments, if any.

H3: Arguments

If a macro has one or more arguments, these are listed
in a table containing the following columns:

* {{Name}} - the argument name
* {{Type}} - the argument type
* {{Default}} - the default value, if any
* {{Rule}} - the pattern, if any, used to validate the value.

H3: Argument Types

The supported set of argument types are:

!block table; groups
Type            Description
Common:
string          a string
integer         an integer
boolean         either 1 or 0
Special:
symbol          a symbolic name
filter          a filter name
rest            the rest of the arguments
eventid         an event tag
condition       a logical expression
!endblock

The special types are needed for some of SDF's built-in
macros including {{MAC:define}}, {{MAC:include}}, {{MAC:on}}
and {{MAC:if}} - they are rarely needed for normal macros.

H3: Default Values

For default values within argument tables:

* the empty string means there is no default
* the symbol _NULL_ means the default is the empty string.

H2: Rules

H3: Rule Types

If you wish, arguments can be validated using a rule.
Rules are either:

!block sections
* Patterns
* General Perl Expressions.
!endblock

H3: Patterns

A {{pattern}} is a Perl regular expression which the argument
value is matched against. Patterns are enclosed in angle brackets
to differentiate them from normal Perl expressions.
Typical patterns are given in the table below.

!block table
Pattern     Explanation
<\w+>       one or more characters in A-Z, a-z, 0-9 and '_'
<\d{4}>     a 4 digit number
    a string which is either "on" or "off"
   a string which begins with "XMIT-"
!endblock

H3: General Perl Expressions

More complex rules are required when:

* the regular expression does not apply to the whole value
* the regular expression is case-insensitive.

In these cases, a general Perl expression can be used as the rule.
Within the expression, $_ is the value of the argument.
Examples are:

!block table
Expression      Explanation
/\d/            a digit exists somewhere in the string
/^(on|off)$/i   value is either "on" or "off" (case insensitive)
!endblock

!block note
A pattern is simply a short-hand notation for the general
Perl expression below:

E:	/^(pattern)$/

Pattern notation is provided as it makes rules easier
to read and write. (Pattern-style validation typically covers
80% or more of validation rules so improving the readability of
patterns has a large impact on the overall readability.)
!endblock
l _NULL_ meanssdf-2.001/doc/ref/sappendt.html010064400042570001753000000032010672242565200161510ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: AppendText




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    12.2. AppendText
    

    

    Purpose
    

    AppendText is used within a paragraph event handler to add SDF after a paragraph.
    

    

    Interface
    

      &AppendText(@sdf)

    

    12.2..1. Description
    

    The argument is the list of SDF paragraphs to append.
    

    

    Examples
    

    To append a line after each level 1 heading:
    

      !on paragraph 'H1';; &AppendText('Line:')

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/prn2ps.html010064400042570001753000000075700672242564500155760ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: prn2ps - PostScript Conversion Utility




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    11.9. prn2ps - PostScript Conversion Utility
    

    

    Purpose
    

    prn2ps converts Windows PostScript to Unix PostScript. The input to this program is typically generated by printing to a PostScript printer connected to the FILE: logical device. The output can be converted to Encapsulated PostScript using GhostScript's p2epsi program.
    

    

    Usage
    

    usage  : prn2ps [-h[help]] [-o[out_ext]]
         [-l[log_ext]] [-O[out_dir]] prn_file ...
purpose: convert Windows PostScript to Unix PostScript
version: 2.000    (SDF 2.001)

    

    The options are:
    

    

    

Option


Description


    

    

-h


display help on options


    

    

-o


output file extension


    

    

-l


log file extension


    

    

-O


output to input file's (or explicit) directory


    

    


    

    Description
    

    The -h option provides help. If it is specified without a parameter, a brief description of each option is displayed. To display the attributes for an option, specify the option letter as a parameter.
    

    By default, generated output goes to standard output. To direct output to a file per input file, use the -o option to specify an extension for output files. If the -o option is specified without a parameter, an extension of out is assumed.
    

    Likewise, error messages go to standard error by default. Use the -l option to create a log file per input file. If the -l option is specified without a parameter, an extension of log is assumed.
    

    By default, generated output and log files are created in the current directory. Use the -O option to specify an explicit output directory. If the -O option is specified without a parameter, the input file's directory is used.
    

    For each input file, the output is generated by:
    

      

    • deleting the PageSize information

    • deleting the control-D at the end of the file.
    

    

    Examples
    

    To generate an Encapsulated PostScript file from Windows PostScript:
    

      prn2ps -ops myfig.prn
  ps2epsi myfig.ps

    

    

    Limitations and future directions
    

    If ps2epsi doesn't like the output, you may need to use another printer driver to generate the input. On Windows NT 4.0, the Canon PS-IPU Color Laser Copier v52.3 driver works most of the time.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/mendif.html010064400042570001753000000026700672242535300156040ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: endif Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.15. endif Macro
    

    

    Interface
    

    The general syntax is:
    

      !endif

    

    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The endif macro marks the end of a conditional text section.
    

    

    Examples
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



ml">Contents | Parent Topic | 






SDF 2.001: SDF Reference: Miscellaneous Variables




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    13.5. Miscellaneous Variables
    

    

    Purpose
    

    These variables are generally useful.
    

    

    Interface
    

    

    

Name


Type


Purpose


    

    

Characters:


 


 


    

    

c


string


copyright character


    

    

tm


string


trademark character


    

    

rtm


string


registered trademark character


    

    

nbsp


string


non-breaking space


    

    

Environment:


 


 


    

    

SDF_VERSION


string


product version string (e.g. 2.000 beta1)


    

    

SDF_HOME


string


library/configuration directory


    

    

Expression formats:


 


 


    

    

FORMAT_UPPER


string


convert a string to uppercase


    

    

FORMAT_LOWER


string


convert a string to lowercase


    

    

FORMAT_FULL


string


format to a complete date-time format


    

    

FORMAT_TIME


string


format to a time only


    

    

FORMAT_DATE


string


format to a date only


    

    

FORMAT_CONCISE


string


format to a concise date only


    

    

FORMAT_YEAR


string


format to a 4-digit year


    

    


    

    Description
    

    The character variables are the preferred way of including the respective symbols. A format-specific configuration file can override the default definitions of these symbols.
    

    The environment variables can be used to find out which version of SDF is executing and where it is installed.
    

    The expression format variables define bits of Perl code to format variables or expressions. They can be defined in a configuration file - your system adminstrator may wish to configure date formatting to suit local conventions.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/fplain.html010064400042570001753000000036570672242524100156150ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: plain Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.24. plain Filter
    

    

    Interface
    

    The general syntax is:
    

      !block plain
  ...
  !endblock

    

    See Understanding Filter Interfaces, if necessary.
    

    

    Description
    

    The plain filter is used when including a topic as an "plain" section within a document, i.e. normal headings are converted to plain headings.
    

    

    Examples
    

    A typical book might look like this:
    

    !init OPT_STYLE="manual"

!define DOC_NAME "A Sample Book"
!build_title

!include "chapter1.sdf"
!include "chapter2.sdf"
!include "chapter3.sdf"
!include "glossary.sdf"; plain

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/var_doc.html010064400042570001753000000057440672242567700157750ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: Document Variables




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    13.3. Document Variables
    

    

    Purpose
    

    These variables are related to the document SDF is currently processing.
    

    

    Interface
    

    

    

Name


Type


Purpose


    

    

Control:


 


 


    

    

DOC_TOC


integer


table of contents level


    

    

DOC_TWO_SIDES


boolean


build a two-sided document


    

    

Book controls:


 


 


    

    

DOC_LOF


boolean


build a list of figures


    

    

DOC_LOT


boolean


build a list of tables


    

    

DOC_IX


boolean


build an index


    

    

Information:


 


 


    

    

DOC_PATH


string


the full pathname of the current document


    

    

DOC_DIR


string


the directory of the current document


    

    

DOC_BASE


string


the base (filename) of the current document


    

    

DOC_EXT


string


the extension of the current document


    

    

DOC_SHORT


string


the base and extension of the current document


    

    

DOC_START


datetime


the time document conversion started


    

    

DOC_MODIFIED


datetime


the most recent modification time of files visited so far


    

    


    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



" BORDER>

    




























    

    

Name


Type


Default


Rule


    

    

code


rest


 


 


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The script macro executes a single line of Perl code.
    

    

    Examples
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/melseif.html010064400042570001753000000035020672242534400157610ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: elseif Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.11. elseif Macro
    

    

    Interface
    

    The general syntax is:
    

      !elseif value

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

value


condition


 


 


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The elseif macro delimits sections within conditional text. It is identical in operation to the elsif macro.
    

    

    Examples
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/mif.html010064400042570001753000000033560672242537300151210ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: if Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.22. if Macro
    

    

    Interface
    

    The general syntax is:
    

      !if value

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

value


condition


 


 


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The if macro marks the beginning of a conditional text section.
    

    

    Examples
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/fend.html010064400042570001753000000035760672242520500152600ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: end Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.13. end Filter
    

    

    Interface
    

    The general syntax is:
    

      !block end
  ...
  !endblock

    

    See Understanding Filter Interfaces, if necessary.
    

    

    Description
    

    The end filter is used to add a section of SDF onto the end of the document. This is particularly useful in configuration files when you want to:
    

      

    • load a "exit" configuration module

    • provide defaults for variables not provided by authors within a document.
    

    When several sections are added to the end using this macro, the sections are processed in a first-in-last-out order.
    

    

    Examples
    

    !block end
Line:
N[align=Center] END OF DOCUMENT
!endblock

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/in_oattr.html010064400042570001753000000053470672242547700161740ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: Phrase Attributes




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    9. Phrase Attributes
    

    The phrase attributes available are summarised below.
    

    

    

Name


Purpose


    

    

Formatting:


 


    

    

family


font family


    

    

size


font size


    

    

color


text colour


    

    

bold


enable bold


    

    

italics


enable italics


    

    

underline


enable underline


    

    

changed


enable change bars


    

    

Objects:


 


    

    

expand


replace an object name with its longer form


    

    

shrink


replace an object name with its shorter form


    

    

Hypertext:


 


    

    

id


define a hypertext target


    

    

jump


define a hypertext jump (i.e. URL)


    

    

Indexes:


 


    

    

index


define an index entry


    

    

index_type


specify the index type


    

    

Help specific:


 


    

    

hlp.popup


jump to a popup window


    

    


    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/in_mac.sdf010064400042570001753000000077420661462006700154040ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
H1: Macros

H2: Overview

The macros available are summarised below.

!block table; tags="MAC"; groups
Name                Purpose
General:
build_title         build a title page
block               begin a block of text
endblock            end a block of text
include             include another file
execute             include output from a command
Variables:
init                initialise variables (before loading configuration files)
define              set a variable
default             set a variable (if not already set)
undef               clear a variable
export              export a variable to the format driver (and/or mark it for later exporting)
restrict            declare a restricted family of variables
Figures:
import              import an external object (e.g. figure)
clear               reset text wrapping around a figure
Libraries:
inherit             inherit entities from a library
use                 load a library module
Macros:
macro               begin a macro definition
endmacro            end a macro definition
insert              call a macro
Classes:
class               define a class of objects
catalog             build a catalog from objects already loaded
Conditional text:
if                  begin conditional text
elsif               begin a conditional section
else                begin alternative section
endif               end conditional text
elseif              same as elsif
Event processing:
on                  specify processing for an event
off                 disable processing previously specified
File processing:
output              dynamically change the output file used
script              execute a line of [[Perl]]
message             output a message during execution
line                change message parameters
slide_down          decrease heading levels (e.g. H2 -> H3)
slide_up            increase heading levels (e.g. H2 -> H1)
Extraction:
getdoc              extract documentation embedded in source code
getcode             extract source code (i.e. non-documentation) from a file
getcli              extract command-line interface information
perlapi             extract API information from a [[Perl]] library
Miscellaneous:
jumps               generates lines of jumps
subsections         specify the subsections for a topic
continued           continue a heading from a previous page
end_topic           mark the end of a topic
!endblock

Further details on these are provided below.

# Define the help to be placed after each macro interface
!macro MACRO_INTERFACE_END
See {{SECT:Understanding Macro Interfaces}}, if necessary.
!endmacro

# Include the subsections, placing each at the top of a page (or after a line)
!if $var{'HTML_TOPICS_MODE'} || $var{'HTML_SUBTOPICS_MODE'}
    # do nothing
!elsif $var{'OPT_TARGET'} eq 'html' || $var{'OPT_TARGET'} eq 'txt'
    !on paragraph 'H2'; h2top; &PrependText("Line:")
!else
    !on paragraph 'H2'; h2top; $attr{'top'} = 1
!endif
!block topics
Topic
macros/mblock
macros/mbuild_t
macros/mcatalog
macros/mclass
macros/mclear
macros/mcontinu
macros/mdefault
macros/mdefine
macros/melse
macros/melseif
macros/melsif
macros/mend_top
macros/mendbloc
macros/mendif
macros/mendmacr
macros/mexecute
macros/mexport
macros/mgetcli
macros/mgetcode
macros/mgetdoc
macros/mif
macros/mimport
macros/minclude
macros/minherit
macros/minit
macros/minsert
macros/mjumps
macros/mline
macros/mmacro
macros/mmessage
macros/moff
macros/mon
macros/moutput
macros/mperlapi
macros/mrestric
macros/mscript
macros/mslide_d
macros/mslide_u
macros/msubsect
macros/mundef
macros/muse
!endblock

!if !($var{'HTML_TOPICS_MODE'} || $var{'HTML_SUBTOPICS_MODE'})
!off paragraph h2top
!endif
script              execute a sdf-2.001/doc/ref/sformatt.html010064400042570001753000000101550672242566300162020ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: FormatTime




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    12.4. FormatTime
    

    

    Purpose
    

    This routine is used to format a date-time quantity into a human readable form.
    

    

    Interface
    

      $result = &FormatTime($fmt, $var);

    

    

    Description
    

    The first parameter is either a format string or the name of a variable containing a format string. The second parameter is the name of the variable to be formatted. The variable's value is a number of seconds since January 1, 1970.
    

    The building blocks used in the format strings are given below.
    

    

    

Symbol


Description


Example


    

    

$day


day number in month


6 or 22


    

    

$day0


day number in month zero-padded


06 or 22


    

    

$month


month name


January


    

    

$smonth


abbreviated month name


Jan


    

    

$monthnum


month number (1..12)


6 or 12


    

    

$monthnum0


month number zero-padded (01..12)


06 or 12


    

    

$year


year


1995


    

    

$syear


abbreviated year


95


    

    

$weekday


weekday name


Monday


    

    

$sweekday


abbreviated weekday name


Mon


    

    

$hour


hour (1..24)


6 or 14


    

    

$hour0


hour zero-padded (01..24)


06 or 14


    

    

$shour


hour (1..12)


6 or 12


    

    

$shour0


hour zero-padded (01..12)


06 or 12


    

    

$ampm


am or pm


am


    

    

$AMPM


AM or PM


PM


    

    

$minute


minute (0..59)


0 or 42


    

    

$minute0


minute zero-padded (00..59)


00 or 42


    

    

$second


second (0..59)


0 or 42


    

    

$second0


second zero-padded (00..59)


00 or 42


    

    


    Commonly used formats are defined in the variables given below.
    

    

    

Variable


Value


    

    

FMT_FULL


$day $month $year, $hour:$minute0.$second0


    

    

FMT_TIME


$hour:$minute0.$second0


    

    

FMT_DATE


$day $month $year


    

    

FMT_CONCISE


$day0-$smonth-$syear


    

    


    

    Examples
    

    To format the 'last modified' date-time for a document:
    

       &FormatTime('FMT_FULL', 'DOC_MODIFIED')

    

    To format the year when conversion started (for copyright reasons, say):
    

       &FormatTime('$year', 'DOC_START')

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/minclude.html010064400042570001753000000037040672242540000161320ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: include Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.24. include Macro
    

    

    Interface
    

    The general syntax is:
    

      !include filename [; filter] [; params]

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

filename


string


 


 


    

    

filter


filter


_NULL_


 


    

    

params


rest


_NULL_


 


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The include macro is used to include another file into an SDF document.
    

    

    Examples
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/mmessage.html010064400042570001753000000035610672242542300161410ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: message Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.31. message Macro
    

    

    Interface
    

    The general syntax is:
    

      !message text [; type]

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

text


string


 


 


    

    

type


string


Object


<Object|Warning|Error|warning|error>


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The message macro can be used to output messages during execution.
    

    

    Examples
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/fverbati.html010064400042570001753000000055600672242530300161400ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: verbatim Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.34. verbatim Filter
    

    

    Interface
    

    The general syntax is:
    

      !block verbatim[; parameters]
  ...
  !endblock

    

    The parameters are:
    

    

    

Name


Type


Rule


    

    

skipheader


boolean


 


    

    

lang


string


 


    

    

wide


boolean


 


    

    

listitem


integer


 


    

    


    See Understanding Filter Interfaces, if necessary.
    

    

    Description
    

    The verbatim filter is used to specify a section of fixed-width text. Unlike the verbatim filter, embedded SDF symbols (like {{) are treated like normal text.
    

    The skipheader parameter is useful when an external file is being included as an example, but you do not want the header comment in the example. The lang parameter, if any, is used to determine the commenting conventions. If no language is specified, comments are assumed to start with a # and be terminated by the end of line.
    

    The wide parameter can be used to ensure that at least 80 characters are output on a line before it is wrapped.
    

    The listitem parameter can be used to specify that this block of text is part of a list. The value is the logical indent of the list (e.g. 1, 2, etc.).
    

    

    Examples
    

    
# Include myfile.c but exclude the copyright, revision history, etc.
!include "myfile.c"; verbatim; skipheader; lang='c'

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/gl_cli.html010064400042570001753000000247710672242573600156060ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: Command Line Guidelines




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    D. Command Line Guidelines
    

    

    D.1. Overview
    

    General Usage
    

    Utilities have the following general usage:
    

       utility [options] arguments

    

    Typically, arguments is a set of filenames. If more than one file is specified,  each filename is echoed to standard error as it is processed.
    

    Options can either be:
    

      

    • short style - these begin with a '-' character, or

    • long-style - these begin with the character sequence '--'.
    

    To obtain a concise summary of a utility's usage, execute it without any parameters. For example:
    

    $ hoopy
usage  : hoopy [-h[help]] [-o[out_ext]] [-l[log_ext]] [-t thing,..] file ...
purpose: do lots of hoopy things to files
version: 1.000
$ _

    

    Exit Codes
    

    The exit code returned to the operating system is dependent on the severity of any errors encountered during execution. The  pre-defined exit codes are linked to message types as summarised below.
    

    

    

Code


Message


Description


    

    

0


n/a


everything succeeded


    

    

8


warning


a possible problem was identified


    

    

16


error


an error was found


    

    

24


abort


processing could not continue on a file


    

    

32


fatal


the application terminated abnormally


    

    

64


failed


an internal error occurred


    

    


    Arguments
    

    The set of options is implicitly terminated by the first argument. i.e. the first symbol which does not begin with either '-' or '--'. To specify an argument which would otherwise be treated as an option, it is sometimes necessary to explicitly terminate the options using the '--' symbol.
    

    Unless stated otherwise for a particular utility, '+' can be used to specify that standard input contains a list of arguments. This feature is particularly useful for passing complex arguments to scripts on systems with poor support for command line quoting.
    

    If the arguments are files, '-' can be used to indicate standard input.
    

    Providing Default Options
    

    Default options for a utility can be specified in an environment variable of the form:
    

       nameOPTS

    

    For example, if hoopy supported a -R option for specifying a directory to search for report files in, then the user may wish to define this directory in an environment variable so that they do not need to specify it each time. This could be done by adding the following to their .profile:
    

       HOOPYOPTS=-R/home/me/etc/reports
   export HOOPYOPTS

    

    

    D.2. Options
    

    Option Types
    

    Several types of options are supported as outlined in the table below.
    

    

    

Option type


Usage message format


    

    

parameter-less


[-x]


    

    

parameter-required


[-x thing]


    

    

parameter-optional


[-x[thing]]


    

    


    For parameter-optional options, the option parameter typically defaults to a particular value if the option is supplied without a parameter. For example, the extension of output files can be specified using the -o option. The default value of this parameter-optional option is 'out'. The series of examples below illustrates this.
    

      

    1. To send output to standard output:
    

       hoopy *.dat

    

      

    1. To send output to .out files:
    

       hoopy -o *.dat

    

      

    1. To send output to .new files:
    

       hoopy -onew *.dat

    

    As for arguments, '-' can be specified to indicate standard input for options expecting a filename.
    

    List Options
    

    Some options have list parameters. These options can be specified several times and/or multiple list elements can be separated with commas. For example, the following are all equivalent:
    

       hoopy -ta,b,c *.dat
   hoopy -ta -tb,c *.dat
   hoopy -ta,b -tc *.dat
   hoopy -ta -tb -tc *.dat

    

    In addition to simple lists, lists of name-value pairs are also supported. In this case, the name and value are separated by a '=' or ':' character.
    

    
Note: on MS-DOS and OS/2, '=' causes problems so ':' must be used.

    

    If only the name is given, the value is assumed to be 1. For example, the following are equivalent:
    

       mycmd -ftbl_dir=../tables -fverbose=1 *.dat
   mycmd -ftbl_dir=../tables -fverbose *.dat
   mycmd -ftbl_dir:../tables -fverbose *.dat

    

    Ordering is not important for name-value lists but may be important for normal lists. In either case, within a usage message, list options are indicated as follows:
    

       [-t thing,..]

    

    Option Styles
    

    There are two parameter styles: short and long. Short style is typically used on the command line. Long style is useful to improve readability in shell scripts.
    

    In short style:
    

      

    • options are specified by a single character

    • a set of parameter-less options can be clustered

    • between the option character and the parameter:
        

      • whitespace is optional for a parameter-required option

      • whitespace is not permitted for a parameter-optional option
    

    In long style:
    

      

    • the name can be abbreviated provided it is still unique

    • a '=' or ':' is used to separate the option name from the parameter
    

    Examples are:
    

       hoopy --out *.dat

    

    and
    

       hoopy --out=new *.dat

    

    Option Naming Conventions
    

    Long option names should be selected for maximum readability. In general, the short name should be the first letter of the long name.
    

    For list options which specify a set of directories to search in:
    

      

    • the long name should end in '_path'

    • the short name should be a capital letter
    

    If applicable, the capital letter used should be taken from the related option. For example, if the -r option is used to specify a report file, the -R option should be the list of directories to search for the report in.
    

    

    D.3. Commonly Used Options
    

    Overview
    

    There are 3 options available for most utilities:
    

      

    • -o[out_ext]

    • -l[log_ext]

    • -h[help]
    

    Redirecting Standard Output and Standard Error
    

    By default, generated output goes to standard output. To direct output to a file per input file, use the -o option to specify an extension for output files. If the -o option is specified without a parameter, an extension of out is assumed. Likewise, error messages go to standard error by default. Use the -l option to create a log file per input file. If the -l option is specified without a parameter, an extension of log is assumed.
    

    For a small number of scripts, there is never a need for output or error files per argument. In this case, the -o and -l options are not available.
    

    Obtaining Help
    

    The -h option provides help and is always available. To obtain a concise description of each option, use the help option with no parameter. For example:
    

    $ sdfget -h
usage  : sdfget [-h[help]] [-o[out_ext]] [-l[log_ext]] [-g get_rule] [-r[rpt_file]] [-i] file ...
purpose: extract documentation embedded in source code
version: 2.000    (SDF 2.000beta9)
options:
-h, --help            display help on options
-o, --out_ext         output file extension
-l, --log_ext         log file extension
-g, --get_rule        rule to use to get documentation
-r, --rpt_file        report file
-i, --inverse         only output lines not extracted

    

    Obtaining Help on a Given Option
    

    Detailed help on a given option can be obtained by specifying the option code as a parameter to the -h option. For example:
    

    $ sdfget -hg
usage  : sdfget [-h[help]] [-o[out_ext]] [-l[log_ext]] [-g get_rule] [-r[rpt_file]] [-i] file ...
purpose: extract documentation embedded in source code
version: 2.000    (SDF 2.000beta9)
Detailed help on option: -g,--get_rule

Attribute  Value
Help       rule to use to get documentation
Type       STR
Parameter  yes
Initial    perl
Legal      table, perl, cpp, c, eiffel, fortran

    

    Obtaining Special Help
    

    The help option can also be used to obtain other useful information by specifying a special keyword as the parameter. The keywords supported are:
    

      

    • .parts - display name & version of components (and exit)

    • .time - display execution time (when exiting)

    • .calltree - display the internal sequence of subroutines leading to utility exit
    

    This type of information is useful when developing scripts but is rarely needed by end-users.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/in_dstyl.sdf010064400042570001753000000023530645232746600160030ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Document Styles

The document styles available are summarised below.

!block table; groups
Style           Purpose
General:
document        a normal document
manual          a manual
paper           a technical paper
Administration:
admin           generic administration document
fax             a fascimile
memo            a memorandum
newslttr        a newsletter
minutes         minutes of a meeting
Miscellaneous:
listing         a source code listing
!endblock

For HTML output, the general styles are all the same.
For PostScript output, they typically differ as follows:

* {{document}} - single-sided, busy cover page,
  busy headers/footers, table of contents

* {{manual}} - double-sided, simple cover page,
  simple header/footers, table of contents

* {{paper}} - single-sided, no cover page (just a centered title),
  simple header/footers, no table of contents.
sdf-2.001/doc/ref/in_esc.html010064400042570001753000000202570672242513200155760ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: Escape Characters




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    3. Escape Characters
    

    The escape characters available are summarised below. Escape characters are entered in paragraphs using either the E or CHAR phrase styles.
    

    

    

Symbol


Description


Output


    

    

Syntax related:


 


 


    

    

lt


less-than


<


    

    

gt


greater-than


>


    

    

2{


double left brace


{{


    

    

2}


double right brace


}}


    

    

2[


double left bracket


[[


    

    

2]


double right bracket


]]


    

    

Special symbols:


 


 


    

    

amp


ampersand


&


    

    

bullet


bullet


.


    

    

c


copyright


© 


    

    

cent


cent


¢ 


    

    

dagger


dagger


^


    

    

doubledagger


double dagger


#


    

    

emdash


em-dash


--


    

    

endash


en-dash


-


    

    

emspace


em-space


  


    

    

enspace


en-space


  


    

    

lbrace


left brace


{


    

    

lbracket


left bracket


[


    

    

nbdash


non-breaking hyphen


-


    

    

nbspace


non-breaking space


  


    

    

nl


newline



    
    		

    

    

pound


pound


£ 


    

    

quot


double quote


"


    

    

r


registered trademark


® 


    

    

rbrace


right brace


}


    

    

rbracket


right bracket


]


    

    

tab


tab


	 


    

    

tm


trademark


™ 


    

    

yen


yen


¥ 


    

    

International:


 


 


    

    

Aacute


capital A, acute accent


Á


    

    

aacute


small a, acute accent


á


    

    

Acirc


capital A, circumflex accent


Â


    

    

acirc


small a, circumflex accent


â


    

    

AElig


capital AE diphthong (ligature)


Æ


    

    

aelig


small ae diphthong (ligature)


æ


    

    

Agrave


capital A, grave accent


À


    

    

agrave


small a, grave accent


à


    

    

Aring


capital A, ring


Å


    

    

aring


small a, ring


å


    

    

Atilde


capital A, tilde


Ã


    

    

atilde


small a, tilde


ã


    

    

Auml


capital A, dieresis or umlaut mark


Ä


    

    

auml


small a, dieresis or umlaut mark


ä


    

    

Ccedil


capital C, cedilla


Ç


    

    

ccedil


small c, cedilla


ç


    

    

Eacute


capital E, acute accent


É


    

    

eacute


small e, acute accent


é


    

    

Ecirc


capital E, circumflex accent


Ê


    

    

ecirc


small e, circumflex accent


ê


    

    

Egrave


capital E, grave accent


È


    

    

egrave


small e, grave accent


è


    

    

Euml


capital E, dieresis or umlaut mark


Ë


    

    

euml


small e, dieresis or umlaut mark


ë


    

    

Iacute


capital I, acute accent


Í


    

    

iacute


small i, acute accent


í


    

    

Icirc


capital I, circumflex accent


Î


    

    

icirc


small i, circumflex accent


î


    

    

Igrave


capital I, grave accent


Ì


    

    

igrave


small i, grave accent


ì


    

    

Iuml


capital I, dieresis or umlaut mark


Ï


    

    

iuml


small i, dieresis or umlaut mark


ï


    

    

Ntilde


capital N, tilde


Ñ


    

    

ntilde


small n, tilde


ñ


    

    

Oacute


capital O, acute accent


Ó


    

    

oacute


small o, acute accent


ó


    

    

Ocirc


capital O, circumflex accent


Ô


    

    

ocirc


small o, circumflex accent


ô


    

    

Ograve


capital O, grave accent


Ò


    

    

ograve


small o, grave accent


ò


    

    

Oslash


capital O, slash


Ø


    

    

oslash


small o, slash


ø


    

    

Otilde


capital O, tilde


Õ


    

    

otilde


small o, tilde


õ


    

    

Ouml


capital O, dieresis or umlaut mark


Ö


    

    

ouml


small o, dieresis or umlaut mark


ö


    

    

Uacute


capital U, acute accent


Ú


    

    

uacute


small u, acute accent


ú


    

    

Ucirc


capital U, circumflex accent


Û


    

    

ucirc


small u, circumflex accent


û


    

    

Ugrave


capital U, grave accent


Ù


    

    

ugrave


small u, grave accent


ù


    

    

Uuml


capital U, dieresis or umlaut mark


Ü


    

    

uuml


small u, dieresis or umlaut mark


ü


    

    

yuml


small y, dieresis or umlaut mark


ÿ


    

    


    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/re_sdf.html010064400042570001753000000040520672242573600156050ustar00iancmtr00000400000236






SDF 2.001: SDF Reference




    

    

    Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    SDF Reference
    

    MTR-SDF-0004.001 (Final)
    

    Ian Clatworthy
    

    25 May 1999
    

    

    

    

    

    Table of Contents
    


    

    

    

    Previous Topic | Next Topic 
    Home | Catalog
    

    

    



 2.0//EN">






SDF 2.001: SDF Reference




    

    

    Previous Topic | Next Topic 
    Home | Catalosdf-2.001/doc/ref/mdefine.html010064400042570001753000000034640672242533700157550ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: define Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.9. define Macro
    

    

    Interface
    

    The general syntax is:
    

      !define name [value]

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

name


symbol


 


 


    

    

value


string


1


 


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The define macro sets a variable to a value.
    

    

    Examples
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/in_pstyl.sdf010064400042570001753000000035010645716325200160070ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
H1: Paragraph Styles

The paragraph styles available are summarised below.

!block table; tags="PSTYLE"; groups
Name            Purpose
Headings:
Hn              normal heading at level {{n}} (1..6)
An              appendix heading at level {{n}} (1..6)
Pn              plain heading at level {{n}} (1..6)
Lists:
Ln              plain list item or paragraph at level {{n}} (1..6)
LFn             first entry in an ordered list at level {{n}} (1..6)
LNn             next entry in an ordered list at level {{n}} (1..6)
LUn             unordered list item at level {{n}} (1..6)
Notes:
Note            a single paragraph note
NB              start of a multi-paragraph note
NE              end of a multi-paragraph note
Miscellaneous:
E               example text (i.e. fixed width)
V               verbatim text (i.e. fixed width, ignore escapes)
E80             wide example text
Line            horizontal line
N               normal text
NV              name-value pair (i.e. hanging indent)
PB              page break
Sign            signature for a memo, etc.
!endblock

The following special styles are also available.

!block table
Symbol          Purpose
>               verbatim text
* .. ******     unordered list item at level 1..6
- .. -----      unordered list item at level 2..6
^ .. ^^^^^^     first entry in an ordered list at level 1..6
+ .. ++++++     next entry in an ordered list at level 1..6
. .. ......     plain list item or paragraph at level 1..6
!endblock
sdf-2.001/doc/ref/sdfbatch.html010064400042570001753000000170040672242557100161170ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: sdfbatch - Batch Processing Utility




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    11.4. sdfbatch - Batch Processing Utility
    

    

    Purpose
    

    sdfbatch is a preprocessor for fmbatch, FrameMaker's command-line driven batch processing utility.
    

    

    Usage
    

    usage  : sdfbatch [+alias] [-h[help]] [-f fmt_file]
         [-F fmt_what] [-u] [-p[print_doc]]
         [-P paper_size] [-s[save_ext]]
         [-S save_fmt] [-n] [-t timeout]
         frame_file ...
purpose: generate fmbatch input file
version: 2.000    (SDF 2.001)

    

    The options are:
    

    

    

Option


Description


    

    

-h


display help on options


    

    

-f


formats file


    

    

-F


formats to import


    

    

-u


update documents


    

    

-p


print documents


    

    

-P


paper size name


    

    

-s


save extension


    

    

-S


save file format


    

    

-n


output the batch file (instead of calling fmbatch)


    

    

-t


timeout for printer driver to generate ps


    

    


    The aliases are:
    

    

    

Alias


Description


    

    

fm2ps


convert Frame files to PostScript


    

    


    

    Description
    

    Given a set of FrameMaker documents, sdfbatch can be used to:
    

      

    • change the formatting of the documents (ala Use Formats From)

    • update the documents (i.e. cross-references, etc.)

    • print the documents

    • save the documents in a nominated file format
    

    The -h option provides help. If it is specified without a parameter, a brief description of each option is displayed. To display the attributes for an option, specify the option letter as a parameter.
    

    To change formatting, use the -f option to specify the file to import the formats from. The -F option can be used to specify what formats are imported. The argument to the -F option is a set of the characters in the table below.
    

    

    

Character


Meaning


    

    

p


Paragraph formats


    

    

f


Font formats


    

    

l


Page layouts


    

    

c


Cross references


    

    

v


Variables


    

    

r


Reference page contents


    

    

t


Table formats


    

    

x


Conditional text


    

    

k


Color


    

    

m


math


    

    

B


Preserve manual page breaks


    

    

O


Preserve other formatting overrides


    

    


    By default, all formats are imported.
    

    To update documents, use the -u option.
    

     To print documents, use the -p option. If a parameter is not provided, the file will be printed to the default printer. To print to a PostScript file, specify the "file" keyword as the parameter. Alternatively, the parameter is the name of a print settings file.
    

     When generating a PostScript file, the paper size can be specified using the -P option. The default value is global. The paper size name is actually mapped to a print settings file called paper_size.fmver in the stdlib library directory. fmver is typically either fm4 or fm5, depending on which version of FrameMaker you are using.
    

    To save documents, use the -s option. By default, this saves each file. To change the extension, supply an argument to the -s option.
    

    To specify a different format, use the -S option. Possible values are:
    

      

    • m - MIF

    • a - line-oriented ASCII

    • t - paragraph-oriented ASCII

    • d - Frame document

    • l - View-Only Frame document

    • - - file's current format [default]
    

    Take care with the file extension - any existing files will be replaced without warning.
    

    The -n option causes the generated fmbatch file to be output. i.e. fmbatch is not called. This option is useful for debugging.
    

    The -t option enables the user to tune the time-out used when waiting for the print driver to generate a PostScript file. The default value is 300 seconds (i.e. 5 minutes).
    

    A combination of the f, u, p and s options can be supplied if more that one operation is required per file. For example, you may wish to import formats and then save the resultant file. For each file, the operations are always done in the following order:
    

      

    1. formatting

    2. updating

    3. printing

    4. saving
    

     
    
Note: Not all of the values documented for the -F and -S options may be supported in Frame versions before 4.0 and additional values may be supported in future versions. As such, the values supplied to these options are simply embedded in the generated sdfbatch file. i.e. no checking is done on the value. This behaviour is considered a feature.

    

    

    Examples
    

    To format and print a set of files:
    

            sdfbatch -fmyfmts.doc -p *.doc

    

    To convert mif files to binary files:
    

            sdfbatch -sdoc -Sd *.mif

    

    To copy Frame variables from a file to a set of files:
    

            sdfbatch -fvariable.mif -Fv -s *.doc

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



lumns" BORDER>

    

Character


Meaning


    

    

p


Paragraph formats


    

    

f


Font formats


    

    

l


Page layouts


    

    

c


Cross references


    

    

v


Variables


    

    

r


Reference page contents


    

    

t


Table formats


    

    

x


Conditional texsdf-2.001/doc/ref/in_pattr.sdf010064400042570001753000000033230622022216000157460ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
H1: Paragraph Attributes

The paragraph attributes available are summarised below.
{{SECT:Phrase Attributes}} can also be used as paragraph attributes.

!block table; tags="PATTR"; groups
Name                Purpose
Margins:
left                left margin indent (in points)
first               first line indent (in points)
right               right margin indent (in points)
align               either Full, Left, Right or Center
Positioning:
top                 either Page (the default), Column, LPage or RPage
sp_before           space before this paragraph
sp_after            space after this paragraph
keep_prev           keep this paragraph with the previous one
keep_next           keep this paragraph with the next one
Miscellaneous:
label               prefix label (e.g. Note:)
obj                 define this paragraph as an object with a given tag
noevents            disable event processing for this object
nopb                disable the implicit page break, if any
notoc               remove this heading from the table of contents
Help specific:
hlp.context         context in the HPJ file
hlp.topic           topic in the HPJ file
hlp.header          include this paragraph in the non-scrolling region
hlp.window          paragraph is part of the contents in a popup window
hlp.endwindow       paragraph is the last one in a popup window
!endblock
sdf-2.001/doc/ref/var_misc.sdf010064400042570001753000000036220647456701200157560ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Miscellaneous Variables

H2: Purpose

These variables are generally useful.

H2: Interface

!block table; groups; format=325
Name                Type        Purpose
Characters:
c                   string      copyright character
tm                  string      trademark character
rtm                 string      registered trademark character
nbsp                string      non-breaking space
Environment:
SDF_VERSION         string      product version string (e.g. 2.000 beta1)
SDF_HOME            string      library/configuration directory
Expression formats:
FORMAT_UPPER        string      convert a string to uppercase
FORMAT_LOWER        string      convert a string to lowercase
FORMAT_FULL         string      format to a complete date-time format
FORMAT_TIME         string      format to a time only
FORMAT_DATE         string      format to a date only
FORMAT_CONCISE      string      format to a concise date only
FORMAT_YEAR         string      format to a 4-digit year
!endblock

H2: Description

The {{character}} variables are the preferred way of
including the respective symbols. A format-specific configuration file
can override the default definitions of these symbols.

The {{environment}} variables can be used to find out which version
of SDF is executing and where it is installed.

The {{expression format}} variables define bits of Perl code to
format variables or expressions. They can be defined in a
configuration file - your system adminstrator may wish to
configure date formatting to suit local conventions.

!end_topic
sdf-2.001/doc/ref/mexecute.html010064400042570001753000000040250672242536000161530ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: execute Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.17. execute Macro
    

    

    Interface
    

    The general syntax is:
    

      !execute cmd [; filter] [; params]

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

cmd


string


 


 


    

    

filter


filter


sdf


 


    

    

params


rest


_NULL_


 


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The execute macro executes the nominated command and includes the output within the document. A filter may optionally be applied to the output before it is included.
    

    

    Examples
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/mclass.html010064400042570001753000000037670672242532500156330ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: class Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.5. class Macro
    

    

    Interface
    

    The general syntax is:
    

      !class name styles [; ids] [; properties]

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

name


symbol


 


 


    

    

styles


string


 


 


    

    

ids


string


Name,Long


 


    

    

properties


string


Jump


 


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The class macro declares a class of objects.
    

    

    Examples
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/in_filt.html010064400042570001753000000160620672242530400157620ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: verbatim Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5. Filters
    

    

    5.1. Overview
    

    The filters available are summarised below.
    

    

    

Name


Purpose


    

    

General:


 


    

    

table


tabular data


    

    

note


a note


    

    

quote


a quotation


    

    

abstract


the abstract for a paper


    

    

title


title block for a memo, fax or minutes


    

    

Line based:


 


    

    

example


fixed-width text (e.g. source code)


    

    

verbatim


fixed-width text, ignoring embedded symbols


    

    

ascii_graphic


fixed-width text, wide enough for ASCII graphics


    

    

nofill


a set of lines


    

    

address


an address


    

    

Components:


 


    

    

front


front section of a document


    

    

about


about section of a document


    

    

appendix


change headings to appendix style


    

    

plain


change headings to plain style


    

    

Formatting:


 


    

    

box


surround a region of text with a box


    

    

changed


mark a block of text as changed


    

    

sections


paragraphs are sections


    

    

namevalues


format a set of name-value pairs (e.g. as used in a title block)


    

    

sdf


apply arbitrary phrase attributes to text


    

    

pod


embedded POD


    

    

File processing:


 


    

    

comment


ignore text


    

    

topics


include a set of sub-topics


    

    

inline


embed text into target format (e.g. HTML)


    

    

script


execute text as a Perl script


    

    

end


process text at the end


    

    

get


extract embedded documentation


    

    

Configuration:


 


    

    

langdefs


define vgrind-like language definitions


    

    

define


define a block of variables


    

    

default


provide defaults for a block of variables


    

    

simple


generic filter for building others


    

    

datestrings


define strings used within dates


    

    

Help:


 


    

    

hlp_header


table of jumps at the top of a help topic


    

    

hlp_window


contents of a help popup window


    

    


    Further details on these are provided below.
    

    about Filter
    

    abstract Filter
    

    address Filter
    

    appendix Filter
    

    ascii_graphic Filter
    

    box Filter
    

    changed Filter
    

    comment Filter
    

    datestrings Filter
    

    default Filter
    

    define Filter
    

    end Filter
    

    example Filter
    

    front Filter
    

    get Filter
    

    hlp_header Filter
    

    hlp_window Filter
    

    inline Filter
    

    langdefs Filter
    

    namevalues Filter
    

    nofill Filter
    

    note Filter
    

    plain Filter
    

    pod Filter
    

    quote Filter
    

    script Filter
    

    sdf Filter
    

    sections Filter
    

    simple Filter
    

    table Filter
    

    title Filter
    

    topics Filter
    

    verbatim Filter
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



ref/faddress.html">address
    		

an address


    

    

Components:


 


    

    

front


front section of a document


    

    

about


about section of a document


    

    

appendix


change headings to appendix stylsdf-2.001/doc/ref/in_prog.html010064400042570001753000000076120672242564600160050ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: prn2ps - PostScript Conversion Utility




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    11. Programs
    

    

    11.1. Overview
    

    The programs available are summarised below.
    

    

    

Name


Purpose


    

    

sdf


convert SDF files to other formats


    

    

sdfapi


extract the Application Programming Interface from source code


    

    

sdfbatch


generate FrameMaker batch files


    

    

sdfcli


extract the Command Line Interface from a utility


    

    

sdfget


extract documentation embedded in source code


    

    

sdftest


execute SDF regression tests


    

    

sdngen


build an SDF tuning module from a FrameMaker template


    

    

prn2ps


convert Windows PostScript to Unix PostScript


    

    


    sdf is typically invoked as follows:
    

       sdf -2format [options] files

    

    Supported format values include the following:
    

    

    

Format


Description


    

    

ps


a PostScript document


    

    

html


a HTML document


    

    

hlp


Microsoft Windows help input files


    

    

fvo


a FrameViewer file


    

    

txt


a plain text document


    

    

rtf


an RTF document


    

    

book


a book (PostScript)


    

    


    Further details on the programs are provided below.
    

    sdf - SDF Conversion Utility
    

    sdfapi - API Extraction Utility
    

    sdfbatch - Batch Processing Utility
    

    sdfcli - Command Line Interface Utility
    

    sdfget - Documentation Extraction Utility
    

    sdftest - Execute SDF Regression Tests
    

    sdngen - SDF Tuning File Generator
    

    prn2ps - PostScript Conversion Utility
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/ftopics.html010064400042570001753000000072530672242530000160030ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: topics Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.33. topics Filter
    

    

    Interface
    

    The general syntax is:
    

      !block topics[; parameters]
  table
  !endblock

    

    The parameters are:
    

    

    

Name


Type


Rule


    

    

intro


string


 


    

    

noslide


boolean


 


    

    

data


boolean


 


    

    


    The table fields are:
    

    

    

Field


Category


Rule


    

    

Topic


mandatory


 


    

    

Label


optional


 


    

    

Level


optional


 


    

    

Next


optional


 


    

    

Prev


optional


 


    

    

Up


optional


 


    

    


    See Understanding Filter Interfaces, if necessary.
    

    

    Description
    

    The topics filter is used to include a set of sub-topics into a document. For PostScript, this implies that the heading levels on topics included as sub-topics are adjusted accordingly. For HTML and Windows help files, this implies that hypertext jumps are inserted to the topics.
    

    This filter expects a table of data in TBL format. The only field typically provided is Topic - the name of the file containing the topic, excluding the .sdf extension. The other fields are used by SDF internally during the generation of HTML topics.
    

    The intro parameter can be used to specify SDF text to be output before the hypertext jumps. This text is not output for formats where the topics are simply included, e.g. PostScript.
    

    The noslide parameter stops the heading levels of the topics being slid down.
    

    The data parameter is used to specify that the table is topics data and no output should be generated. This parameter is used by SDF internally during the generation of HTML topics.
    

    

    Examples
    

    
The subroutines are documented below.

!block topics; intro='H2: Subroutines'
Topic
mysub1
mysub2
!endblock

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



ean
    		

 


    

    

data


boolean


 


    

    


    The table fields are:
    
sdf-2.001/doc/ref/var_file.html010064400042570001753000000040230672242570200161210ustar00iancmtr00000400000236SDF 2.001: SDF Reference: File Information Variables
    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    13.4. File Information Variables
    

    

    Purpose
    

    These variables provide information on the file SDF is currently processing.
    

    

    Interface
    

    

    

Field


Category


Rule


    

    

Topic


mandatory













    

    

Name


Type


Purpose


    

    

FILE_PATH


string


current pathname (e.g. /doc/sdf/mydoc.sdf)


    

    

FILE_DIR


string


directory of current filename (e.g. /doc/sdf)


    

    

FILE_BASE


string


base component of current filename (e.g. mydoc)


    

    

FILE_EXT


string


extension of current filename (e.g. sdf)


    

    

FILE_MODIFIED


datetime


time when this file was last modified


    

    



    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/mcontinu.html010064400042570001753000000053360672242533300161760ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: continued Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.7. continued Macro
    

    

    Interface
    

    The general syntax is:
    

      !continued style [; suffix]

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

style


string


 


 


    

    

suffix


string


, Continued


 


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The continued macro continues a heading from a previous page, provided the target format is page-based, i.e. nothing is output for html or hlp formats.
    

    The first parameter is the heading style to repeat. The second parameter is the suffix to append the text from the repeated heading. The default suffix is ", {{N:Continued}}".
    

    

    Examples
    

    A typical example is:
    

    H2: Solving world peace

H3: Procedure

The steps are given below.

...

!continued 'H2'
!continued 'H3'; ' (Continued)'

Some more procedure text.

    

    In the example above, the macros effectively produce:
    

    H2[notoc;noid;continued] Solving world peace, {{Continued}}
H3[notoc;noid;continued] Procedure {{(N:Continued)}}

    

    
Note: This macro does not cause a new page. Typically, a rule (i.e. event processing) is used to trigger new pages at the necessary paragraph styles.

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/in_sub.sdf010064400042570001753000000024170661416520500154250ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
H1: Subroutines

H2: Overview

The subroutines available are summarised below.

!block table; tags="SUBR"
Name            Purpose
FormatTime      format a date-time value
AppendText      within the {{MAC:on}} macro, appends text after the current line
PrependText     within the {{MAC:on}} macro, prepends text before the current line
#DefineAttrs     within the {{MAC:on}} macro, defines a set of attributes
#DefaultAttrs    within the {{MAC:on}} macro, defaults a set of attributes
FindFile        override this if you need custom searching rules
!endblock

Further details on these are provided below.

# Include the subsections, placing each at the top of a page (or after a line)
!if $var{'OPT_TARGET'} eq 'txt'
    !on paragraph 'H2'; h2top; &PrependText("Line:")
!else
    !on paragraph 'H2'; h2top; $attr{'top'} = 1
!endif
!block topics
Topic
sappendt
sfindfil
sformatt
sprepend
!endblock
!off paragraph h2top
sdf-2.001/doc/ref/in_class.html010064400042570001753000000036250672242511300161300ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: terms Class




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    1. Classes
    

    

    1.1. Overview
    

    The classes available are summarised below.
    

    

    

Name


Purpose


    

    

references


references/documents


    

    

terms


terms/definitions


    

    

organisations


organisations


    

    

products


products


    

    


    Further details on these are provided below.
    

    organisations Class
    

    products Class
    

    references Class
    

    terms Class
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/mbuild_t.html010064400042570001753000000027270672242532000161360ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: build_title Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.3. build_title Macro
    

    

    Interface
    

    The general syntax is:
    

      !build_title

    

    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The build_title macro create a title page or section for documents and papers.
    

    

    Examples
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/fquote.html010064400042570001753000000032100672242524500156340ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: quote Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.26. quote Filter
    

    

    Interface
    

    The general syntax is:
    

      !block quote
  ...
  !endblock

    

    See Understanding Filter Interfaces, if necessary.
    

    

    Description
    

    The quote filter is used to format a quotation. This typically implies:
    

      

    • for PostScript, the text is italics and indented from both margins

    • for HTML, the text is given an appropriate style.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/fascii_g.html010064400042570001753000000027050672242516300161040ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: ascii_graphic Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.6. ascii_graphic Filter
    

    

    Interface
    

    The general syntax is:
    

      !block ascii_graphic
  ...
  !endblock

    

    See Understanding Filter Interfaces, if necessary.
    

    

    Description
    

    The ascii_graphic filter is used to specify a section of text as a diagram.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/in_sym.sdf010064400042570001753000000037350645715411000154460ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
H1: Phrase Styles

The phrase styles available are summarised below.

!block table; groups
Tag         Description                     Sample_Output
Emphasis:
1           1st level emphasis (default)    {{1:emphasis 1}}
2           2nd level emphasis              {{2:emphasis 2}}
3           3rd level emphasis              {{3:emphasis 3}}
Formatting:
N           normal                          {{N:some normal text}}
I           italic                          {{I:some italic text}}
B           bold                            {{B:some bold text}}
U           underline                       {{U:some underline text}}
EX          example                         {{EX:some example text}}
Types:
EMAIL       email address                   {{EMAIL:ianc@mincom.com}}
F (or FILE) Filename                        {{FILE:myfile.sdf}}
SECT        Section                         {{SECT:Paragraphs}}
URL         Uniform Resource Locator        {{URL:http://www.mincom.com}}
Classes:
DOC         document title                  {{DOC:SDF User Guide}}
REF         reference (document code)       {{REF:MTR-SDF-0002}}
ORG         organisation                    {{ORG:Mincom}}
PRD         product                         {{PRD:MIMS}}
Specials:
E (or CHAR) escape (i.e. special character) E
S           spaces are non-breaking         {{S:section 2.1}}
IMPORT      name of a figure to import      {{IMPORT:key}}
URLs:
http
ftp
telnet
news
gopher
wais
https
snews
!endblock

Note: When emphasising text, it is generally better to
use an emphasis style rather than a formatting style as the best way of
doing so depends on the output format.
sdf-2.001/doc/ref/mendbloc.html010064400042570001753000000030130672242535200161140ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: endblock Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.14. endblock Macro
    

    

    Interface
    

    The general syntax is:
    

      !endblock

    

    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The endblock macro marks the end of a "block" of text. The block is started by the block macro.
    

    

    Examples
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/fmt_tbl.html010064400042570001753000000111600672242514300157600ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: TBL Format




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    4.4. TBL Format
    

    

    Purpose
    

    TBL format is a text-based format for storing tabular data.
    

    

    Overview
    

    The basic rules are:
    

      

    • blank lines and comment lines are ignored,

    • the first data line specifies the record format,

    • each remaining data line specifies a single record.
    

    Comment lines begin with # as the first non-whitespace character.
    

    

    Record Formats
    

    For a given table, all records have the same format. The record format is either:
    

      

    • delimited - fields are separated by a special character, or

    • fixed-width - fields are defined by column positions.
    

    An example of delimited format is given below.
    

    # A simple TBL example
Name:Age:Phone:Addr
Bill:42:397 1234:14 Smith St, New Farm
Sarah:37:892 4321:105 Brown St, Chelmer
Joe:44:365 7890:6 Royal Av, Buranda

    

    An example of fixed-width format is given below.
    

    # A simple TBL example
Name    Age     Phone           Addr
Bill    42      397 1234        14 Smith St, New Farm
Sarah   37      892 4321        105 Brown St, Chelmer
Joe     44      365 7890        6 Royal Av, Buranda

    

    
Note: Tabs in fixed-width records are assumed to be 8 spaces wide.

    

    

    Input Format Specification
    

    The first data line is called the input format specification. It specifies:
    

      

    • the name and order of the fields in each record

    • the record format - delimited or fixed-width
    

    Field names can contain:
    

      

    • alphanumeric characters (A-Z, a-z, 0-9)

    • the underscore character (_)
    

    If the first character after the first field name is a space or tab, the format is assumed to be fixed width. Otherwise, the format is delimited with fields separated by the special character found.
    

    

    Multi-line Fields
    

    Generally, each data line specifies a single record. However, if the last field begins with the sequence '<<', then it is a multi-line field terminated by the first line beginning with '>>'. Multi-line fields are supported by both record formats.
    

    Within a multi-line field, blank lines and lines starting with # are treated as part of that field. i.e. it is not possible to embed a comment line within a multi-line field.
    

    An example of a table containing multi-line fields is given below.
    

    # A simple TBL example with multi-line fields
Name    Age     Phone           Addr
Bill    42      397 1234        <<
14 Smith St
New Farm QLD 4005
>>
Sarah   37      892 4321        <<
105 Brown St
Chelmer QLD 4068
>>
Joe     44      365 7890        <<
6 Royal Av
Buranda QLD 4102
>>

    

    

    Special Characters in Fields
    

    For delimited fields:
    

      

    1. If a field contains the delimiter character or the double quote character, it must be enclosed in double quotes.

    2. A double quote character within a field is represented by two double quotes.

    3. Leading whitespace is kept.

    4. Trailing whitespace is kept.
    

    For fixed-width fields:
    

      

    1. Leading whitespace is kept.

    2. Trailing whitespace is removed.
    

    
Note: Multi-line fields are enclosed by the << and >> symbols so none of the rules above apply to them.

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/fmt_ini.sdf010064400042570001753000000017530622022216000155600ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: INI Format

H2: Purpose

INI files are used to store simple configuration information for scripts.

H2: Description

An INI file contains of a series of sections. Each section begins
with a header enclosed in '[' and ']'. Comment lines begin with
';' or '#' as the first non-whitespace character. Blank lines before
a section or at the end of a section are ignored.

H2: Examples

A sample file is:

!block example
[Drivers]
Format  Library     Subroutine  Book
mif     sdf2mif.pl  MifFormat   MifBook
raw     sdf2raw.pl  RawFormat

[PostProcessing]
ps     = &SdfBatch("-pfile")
doc    = &SdfBatch("-sdoc -Sd")
!endblock
sdf-2.001/doc/ref/fexample.html010064400042570001753000000071560672242521100161400ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: example Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.14. example Filter
    

    

    Interface
    

    The general syntax is:
    

      !block example[; parameters]
  ...
  !endblock

    

    The parameters are:
    

    

    

Name


Type


Rule


    

    

skipheader


boolean


 


    

    

lang


string


 


    

    

wide


boolean


 


    

    

listitem


integer


 


    

    

pure


boolean


 


    

    


    See Understanding Filter Interfaces, if necessary.
    

    

    Description
    

    The example filter is used to specify a section of fixed-width text. Unlike the verbatim filter, embedded SDF symbols (like {{) are relevant.
    

    The skipheader parameter is useful when an external file is being included as an example, but you do not want the header comment in the example. The lang parameter, if any, is used to determine the commenting conventions. If no language is specified, comments are assumed to start with a # and be terminated by the end of line.
    

    The lang parameter can be used to pretty-print programming languages. In practice, this means:
    

      

    • comments are output in italics

    • keywords are output in bold.
    

    
Note: The langdefs filter is used to configure the information the pretty-printing feature needs to know. A large number of languages are predefined in the stdlib/langdefs.sdm file.

    

    The wide parameter can be used to ensure that at least 80 characters are output on a line before it is wrapped.
    

    The listitem parameter can be used to specify that this block of text is part of a list. The value is the logical indent of the list (e.g. 1, 2, etc.).
    

    The pure parameter can be used to escape special SDF symbols (like {{) embedded within the text.
    

    

    Examples
    

    
# Include myfile.c but exclude the copyright, revision history, etc.
!include "myfile.c"; example; skipheader; lang='c'

# Pretty-print the same file
!include "myfile.c"; example; wide; lang='c'

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/in_claif.html010064400042570001753000000254330672242571700161140ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: Understanding Class Interfaces




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    A. Understanding Class Interfaces
    

    

    A.1. Overview
    

    General Syntax
    

    The general syntax for declaring and/or formatting a table of objects in the class is shown first. By convention, the filter is shown using the block and endblock macros, although filters can also be used with other macros, including include and execute.
    

    Object Attributes
    

    The attributes supported for each class are listed in a table with the following columns:
    

      

    • Field - the field name

    • Category - key, mandatory or optional

    • Rule - the pattern, if any, used to validate the value.
    

    

    A.2. Parameters
    

    Overview
    

    All class filters support the set of parameters listed below.
    

    

    

Name


Type


Description


    

    

data


boolean


define objects but do not display them


    

    

cited


boolean


number these objects as the cited ones (for [1] style references)


    

    

root


string


string to prepend to Jump attribute, if any


    

    

columns


string


comma-separated list of attributes to display in table


    

    

style


string


table style to use (the default is plain)


    

    

compact


boolean


display in a compact table, (make cellpadding and cellspacing both equal to zero)


    

    

wide


boolean


use sidehead when formatting on paper


    

    

headings


boolean


display the column headings


    

    

where


string


filter the rows using the nominated expression


    

    

sort


string


comma-separated list of columns to sort by


    

    

colaligns


string


a comma-separated list of horizontal alignments  values (Left, Center, Right) for columns; alternatively, a single word containing the letters L, C and R can be used for the value


    

    

colvaligns


string


a comma-separated list of vertical alignments  values (Top, Middle, Bottom, Baseline) for columns; alternatively, a single word containing the letters T, M, B and L can be used for the value


    

    

select


string


a comma-separated list of columns to display


    

    

delete


string


a comma-separated list of columns to delete


    

    

wrap


integer


number of logical rows to place on a physical row


    

    


    

    A.3. Building the Columns
    

    Using the columns Parameter
    

    The columns parameter is a comma-separated list of:
    

       [tag":"]attribute["&"view]

    

    where:
    

      

    • tag is a phrase style (or expression format)

    • attribute is the name of an attribute of the class

    • view is a view to apply to the object when looking up or calculating that attribute (see Object Views below).
    

    To remember the syntax for applying an object view, think of C's bit-masking operator, &.
    

    Examples are given below:
    

    

    

Column


Description


    

    

Code


output the Code attribute


    

    

2:Code


output the Code using the 2 (emphasised) phrase style


    

    

BUG:Code


output the Code using the BUG phrase style


    

    

CONCISE:Date


output the Date attribute using the CONCISE format


    

    


    Calculated Attributes
    

    Some class filters support calculated attributes, so the total set of attributes you can place in the columns parameter can be quite large. For example, for references, an unknown attribute which is sequence of uppercase letters is assumed to be a file extension and the generated attribute is an icon providing a jump to that file, if any. For example, if a reference has a Jump attribute of xyz.html, then the PDF attribute is an image (pdf.gif) which provides a jump to xyz.pdf.
    

    Object Views
    

    On some occasions, it can be very useful if the value placed in a column is a variation of an attribute, rather than the attribute itself. For example, the references class supports an attribute called PS which is an image (postscript.gif) with a jump to xyz.ps (assuming the Jump attribute is xyz.html). But what if the PostScript file is in a different place to the HTML file? In this case, you need to use an object view.
    

    For example, the SDF Document Catalog provides access to SDF's documents in several formats:
    

      

    • PDF and PostScript, stored on SDF's web site

    • HTML, stored locally.
    

    This catalog was created by using the following columns parameter:
    

      columns='PDF&website,PS&website,DOC:Document,Date,Pages'

    

    where website is a file containing the following:
    

      prefix_Jump=http://www.mincom.com/mtr/sdf/

    

    The name of a view is either a file or a directory:
    

      

    • If the name of a view is a file, then the view is loaded from that file. The format is a same as a set of name-value pairs in an INI file.

    • If the name of a view is a directory, then a view with prefix_Jump=name/ is returned.
    

    Within a view, the parameters supported are:
    

      

    • prefix_xxx - prefix for attribute xxx

    • suffix_xxx - suffix for attribute xxx.
    

    
Note: If it proves helpful, I'm happy to expand this list to include other types of parameters like default_xxx and value_xxx, say.

    

    

    A.4. Filtering and Sorting
    

    Filter Expressions
    

    The where attribute takes an expression which is evaluated for each record. Special symbols available are:
    

    

    

Symbol


Meaning


    

    

$_


the current record


    

    

$o{"xyz"}


the value of column xyz


    

    

$var{"abc"}


the value of variable abc


    

    


    For example:
    

     !define MODULE_CODE "XYZ"
 ...
 !include "../document.reg"; references; compact; \
   where='$o{"Reference"} =~ /$var{"MODULE_CODE"}/'; \
   columns="PS,REF:Reference,DOC:Document,CONCISE:Date"

    

    Sorting
    

    sort takes a comma-separated list of column names to sort on. If no columns are specified, the data is sorted using all columns in the order in which they appear. All sorting is done alphabetically - numeric sorting is not supported.
    

    Using the delete Parameter
    

    The delete parameter is particularly useful if you want to sort or filter a table (using the sort and where parameters, respectively) using columns which you don't want in the output. For example:
    

      # Load the bug tracking module
  !use "bugtrack"

  # Display the open bugs, sorted by priority
  H1: Open Defects
  !include 'bugs.reg'; bugs; headings; \
           columns='Code,BUGTITLE:Title,Status,Priority'; \
           where='$o{"Status"} eq "Open"'; \
           sort='Priority'; \
           delete='Status'

    

    
Note: The order of the parameters to a class filter are not important, although the order above best reflects the processing.

    

    In the case above, the columns parameter builds a data table which is then filtered and sorted. Note that the Status and Priority attributes are required in the columns as those attributes are required to do the filtering and sorting. However, as the heading tell the user that this is the table of open defects, we don't need/want the Status attribute in the output, so we delete it.
    

    Filtering Using the catalog Macro
    

    Another way of building the table above is to use the catalog macro like this:
    

      # Load the bug tracking module
  !use "bugtrack"

  # Load the bug data
  !include 'bugs.reg'; bugs; data

  # Display the open bugs, sorted by priority
  H1: Open Defects
  !catalog bugs 'Status:Open'; headings; \
           columns='Code,BUGTITLE:Title,Priority'; \
           sort='Priority'

    

    In this case, the filtering is done before the data reaches the class filter, so things are easier once the data has been loaded.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/mend_top.html010064400042570001753000000030760672242535000161450ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: end_topic Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.13. end_topic Macro
    

    

    Interface
    

    The general syntax is:
    

      !end_topic

    

    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    This macro marks the end of a topic.
    

    

    Examples
    

    

    Limitations & Future Directions
    

    Hopefully, this macro will disappear real soon now.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/fdatestr.html010064400042570001753000000050670672242517500161630ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: datestrings Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.10. datestrings Filter
    

    

    Interface
    

    The general syntax is:
    

      !block datestrings
  table
  !endblock

    

    The table fields are:
    

    

    

Field


Category


Rule


    

    

Symbol


key


<month|smonth|weekday|sweekday|ampm|AMPM>


    

    

Values


optional


 


    

    


    See Understanding Filter Interfaces, if necessary.
    

    

    Description
    

    The datestrings filter can be used to change the strings used within a date. The fields within the table are:
    

      

    • Symbol - the matching symbol name (without the $) from the FormatTime subroutine

    • Values - a Perl string containing a whitespace-separated list of values.
    

    

    Examples
    

    !block datestrings
Symbol   Values
month    "January February March April May June July August September October November December"
smonth   "Jan     Feb      Mar   Apr   May Jun  Jul  Aug    Sep       Oct     Nov      Dec"
weekday  "Monday Tuesday Wednesday Thursday Friday Saturday Sunday"
sweekday "Mon    Tue     Wed       Thu      Fri    Sat      Sun"
ampm     "am pm"
AMPM     "AM PM"
!endblock

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/finline.html010064400042570001753000000047420672242522400157650ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: inline Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.19. inline Filter
    

    

    Interface
    

    The general syntax is:
    

      !block inline[; parameters]
  ...
  !endblock

    

    The parameters are:
    

    

    

Name


Type


Rule


    

    

target


string


<\w+>


    

    

expand


boolean


 


    

    


    See Understanding Filter Interfaces, if necessary.
    

    

    Description
    

    The inline filter is used to pass a section of text directly to a target documentation system.
    

    The target parameter is used to specify which target system the nominated text is to be passed to. The default target is html.
    

    The expand parameter can be used to request expansion of SDF expressions (enclosed in [[ and ]]) within the text.
    

    

    Examples
    

    To embed HTML within an SDF document:
    

    !block inline
  add arbitrary HTML here ...
!endblock

    

    SDF expressions can be expand like this:
    

    !define VERB "is"
...
!block inline; expand
<P>
This HTML [[VERB]] expanded.
!endblock

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/sdftest.sdf010064400042570001753000000021760647544111200156230ustar00iancmtr00000400000236H1[id='sdftest'] sdftest - Execute SDF Regression Tests

H2: Purpose

{{B:sdftest}} executes the regression tests provided with SDF.

H2: Usage

>  sdftest

H2: Description

This program is typically run just after SDF has been installed to
check that the installation succeeded. However, users should be
able to run it at any time to confirm that everything is still ok.

This program works by iterating over the {{sdf}} files in the
{{FILE:test}} directory where SDF is installed. For each file
called {{xx.sdf}}, it generates {{xx.out}} and {{xx.log}} files
containing the output and error logs, respectively. These files
are then validated against the expected files in the {{FILE:checked}}
directory.

Note: Generated files which are ok are deleted. However, if a
test fails, the file which failed is not deleted, so a user can
then use {{CMD:diff}}, say, to analyse what the problem is.

H2: Limitations and future directions

This program only provides regression testing on the core
SDF engine. In particular, it doesn't provide regression
testing on the drivers used to generate each of the different
output formats (e.g. HTML, PostScript).
sdf-2.001/doc/ref/fget.html010064400042570001753000000036770672242521500152740ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: get Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.16. get Filter
    

    

    Interface
    

    The general syntax is:
    

      !block get[; parameters]
  ...
  !endblock

    

    The parameters are:
    

    

    

Name


Type


Rule


    

    

report


string


 


    

    

rule


string


 


    

    

filename


string


 


    

    

inverse


boolean


 


    

    


    See Understanding Filter Interfaces, if necessary.
    

    

    Description
    

    The get filter is used to extract embedded documentation. The parameters map to the options for sdfget.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



ents | Parent Topic | 






SDF 2.001: SDF Reference: appendix Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.5. appendix Filter
    

    

    Interface
    

    The general syntax is:
    

      !block appendix
  ...
  !endblock

    

    See Understanding Filter Interfaces, if necessary.
    

    

    Description
    

    The appendix filter is used when including a topic as an "appendix" section within a document, i.e. normal headings are converted to appendix headings.
    

    

    Examples
    

    A typical book might look like this:
    

    !init OPT_STYLE="manual"

!define DOC_NAME "A Sample Book"
!build_title

!include "chapter1.sdf"
!include "chapter2.sdf"
!include "chapter3.sdf"
!include "appendx1.sdf"; appendix

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/fmt_sdg.sdf010064400042570001753000000027160661520103200155610ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: SDG Format

H2: Purpose

SDG files are used to format information extracted from source code
by {{CMD:sdfget}}.

H2: Description

An SDG is a table of {{Key-Format}} pairs. For example:

E:     Key     Format
E:     -       "Key\t\tDescription\n"
E:     *       sprintf("%-15.15s\t%s\n", $key, $data)

The first line specifies the layout of the table and is required.
An item is only printed if it has a description.
The {{Key}} field can be one of the following:

* an item name
* a minus (-) character, indicating free text
* an asterix (*) character, indicating all remaining items

The {{Format}} field is a Perl expression. {{$key}} and {{$data}}
are used to indicate the key and description of the current
item respectively. Other available symbols are:

* {{$dir}} - directory component of current file
* {{$base}} - base component of current file
* {{$ext}} - extension component of current file
* {{$short}} - base & extension components of current file

H2: Examples

The SDG file used to format topics within the SDF documentation is:

!include "stdlib/default.sdg"; example; skipheader; pure
sdf-2.001/doc/ref/re_sdf.sdf010064400042570001753000000025270645715505600154220ustar00iancmtr00000400000236!init OPT_LOOK='infomap'; OPT_STYLE='manual'
# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

# Load the configuration
!define SDF_ROOT "../"
!inherit "sdf"

# Define variables
!define DOC_NAME    "SDF"
!define DOC_TYPE    "Reference"
!define DOC_AUTHOR  "Ian Clatworthy"
!define DOC_TOC     2
!define DOC_IX

# For HTML, only put the chapter headings in the contents
!if $var{'OPT_TARGET'} eq 'html'
!define DOC_TOC     1
!endif

# Build the title page
!build_title

# Make all level 3 headings plain
!on paragraph '[HA]3';; $style = 'P3'

# Include the document components
!include "reasdf.sdf"; about
!include "in_class.sdf"
!include "in_dstyl.sdf"
!include "in_esc.sdf"
!include "in_fmt.sdf"
!include "in_filt.sdf"
!include "in_mac.sdf"
!include "in_pattr.sdf"
!include "in_pstyl.sdf"
!include "in_oattr.sdf"
!include "in_ostyl.sdf"
!include "in_prog.sdf"
!include "in_sub.sdf"
!include "in_var.sdf"
!include "in_claif.sdf"; appendix
!include "in_filif.sdf"; appendix
!include "in_macif.sdf"; appendix
!include "gl_cli.sdf"; appendix
sdf-2.001/doc/ref/in_pattr.html010064400042570001753000000065730672242546500161740ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: Paragraph Attributes




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    7. Paragraph Attributes
    

    The paragraph attributes available are summarised below. Phrase Attributes can also be used as paragraph attributes.
    

    

    

Name


Purpose


    

    

Margins:


 


    

    

left


left margin indent (in points)


    

    

first


first line indent (in points)


    

    

right


right margin indent (in points)


    

    

align


either Full, Left, Right or Center


    

    

Positioning:


 


    

    

top


either Page (the default), Column, LPage or RPage


    

    

sp_before


space before this paragraph


    

    

sp_after


space after this paragraph


    

    

keep_prev


keep this paragraph with the previous one


    

    

keep_next


keep this paragraph with the next one


    

    

Miscellaneous:


 


    

    

label


prefix label (e.g. Note:)


    

    

obj


define this paragraph as an object with a given tag


    

    

noevents


disable event processing for this object


    

    

nopb


disable the implicit page break, if any


    

    

notoc


remove this heading from the table of contents


    

    

Help specific:


 


    

    

hlp.context


context in the HPJ file


    

    

hlp.topic


topic in the HPJ file


    

    

hlp.header


include this paragraph in the non-scrolling region


    

    

hlp.window


paragraph is part of the contents in a popup window


    

    

hlp.endwindow


paragraph is the last one in a popup window


    

    


    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



attributes.
    

    

    

Name


Purpose







SDF 2.001: SDF Reference: getdoc Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.21. getdoc Macro
    

    

    Interface
    

    The general syntax is:
    

      !getdoc filename [; filter] [; params]

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

filename


string


 


 


    

    

filter


filter


_NULL_


 


    

    

params


rest


_NULL_


 


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The getdoc macro extracts embedded documentation from source code using the sdfget command.
    

    

    Examples
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/sdfcli.html010064400042570001753000000112230672242560200155750ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: sdfcli - Command Line Interface Utility




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    11.5. sdfcli - Command Line Interface Utility
    

    

    Purpose
    

    sdfcli extracts command line interface (CLI) information from applications and formats it into SDF.
    

    

    Usage
    

    usage  : sdfcli [-h[help]] [-o[out_ext]]
         [-l[log_ext]] [-O[out_dir]] [-w wrap]
         utility ...
purpose: format a utility's command line interface into SDF
version: 2.000    (SDF 2.001)

    

    The options are:
    

    

    

Option


Description


    

    

-h


display help on options


    

    

-o


output file extension


    

    

-l


log file extension


    

    

-O


output to input file's (or explicit) directory


    

    

-w


column at which to wrap option specifications


    

    


    

    Description
    

    The -h option provides help. If it is specified without a parameter, a brief description of each option is displayed. To display the attributes for an option, specify the option letter as a parameter.
    

    By default, generated output goes to standard output. To direct output to a file per input file, use the -o option to specify an extension for output files. If the -o option is specified without a parameter, an extension of out is assumed.
    

    Likewise, error messages go to standard error by default. Use the -l option to create a log file per input file. If the -l option is specified without a parameter, an extension of log is assumed.
    

    By default, generated output and log files are created in the current directory. Use the -O option to specify an explicit output directory. If the -O option is specified without a parameter, the input file's directory is used.
    

    sdfcli executes each argument with a -h flag and converts the resultant output to nicely formatted SDF. An argument of "-" specifies that the help should be read from standard input.
    

    Formatting is done as follows:
    

      

    1. lines are tagged as Example paragraphs, with the first line formatted to wrap option usage specifications nicely

    2. if a line is found that starts with 'options:', it is replaced with a Body paragraph saying "The options are:", and the following lines are formatted as a table of codes and descriptions

    3. if a line is found that starts with 'aliases:', it is replaced with a Body paragraph saying "The aliases are:", and the following lines are formatted as a table of names and descriptions

    4. each option code in the table is formatted as a hypertext jump to a tag called cmd_opt where:
        

      • cmd is the command name
        

      • opt is the option code
    

     The -w option specifies at what column to wrap option specifications. The default is 50 - this is the best for output imported into the Mincom templates.
    

    

    Limitations and future directions
    

    The table formats used are hard coded.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/minherit.html010064400042570001753000000035350672242540200161550ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: inherit Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.25. inherit Macro
    

    

    Interface
    

    The general syntax is:
    

      !inherit library

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

library


string


 


 


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The inherit macro is used to inherit configuration information from a library. Typically, a library inherits from another library and then adds some new things.
    

    

    Examples
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/mcatalog.html010064400042570001753000000061110672242532300161200ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: catalog Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.4. catalog Macro
    

    

    Interface
    

    The general syntax is:
    

      !catalog class mask [; params]

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

class


symbol


 


 


    

    

mask


string


 


 


    

    

params


rest


_NULL_


 


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The catalog macro build a catalog from objects already loaded.
    

    The class parameter specifies the class name. As it is defined as a symbol rather than a string type, the name is given without quotes and it is space-separated from the following parameter.
    

    The mask parameter can be used to filter the objects as shown below:
    

    

    

Mask


Description


    

    

empty string


no filtering - display all objects


    

    

cited


display just the cited objects


    

    

abc.*


display the objects with (short) names matching the pattern, i.e. names beginning with abc


    

    

xyz:abc


display the objects where attribute xyz matches the pattern, i.e. xyz is exactly equal to abc


    

    


    Remaining parameters are passed through to the class filter.
    

    

    Examples
    

    Display some interesting attributes of references with a Status of 'Review':
    

    !catalog references 'Status:Review'; compact; \
  columns="PDF,2:Reference,DOC:Document,Version"

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/fnofill.html010064400042570001753000000040030672242523400157610ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: nofill Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.22. nofill Filter
    

    

    Interface
    

    The general syntax is:
    

      !block nofill
  ...
  !endblock

    

    See Understanding Filter Interfaces, if necessary.
    

    

    Description
    

    The nofill filter is used to format a set of lines, i.e. lines are separated by newline characters.
    

    
Note: The address filter may be a better choice that nofill in certain cases. Unlike nofill, address is mapped to ADDRESS tags when HTML is generated. (It's then up to the browser to decide how the address is formatted.)

    

    

    Examples
    

    !block nofill
Mr I.M. Lucky
B.Sc. (Computing)
B.Fun. (Eating)
!endblock

    

    The output is:
    

    Mr I.M. Lucky
    B.Sc. (Computing)
    B.Fun. (Eating)
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/fchanged.html010064400042570001753000000034370672242517000161000ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: changed Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.8. changed Filter
    

    

    Interface
    

    The general syntax is:
    

      !block changed
  ...
  !endblock

    

    See Understanding Filter Interfaces, if necessary.
    

    

    Description
    

    The changed filter is used to mark a section of text as changed.
    

    

    Examples
    

    To add change bars to a section of text:
    

    !block changed
This text has been changed.

And so has this.
!endblock

    

    

    Limitations & Future Directions
    

    At the moment, this filter only works when generating FrameMaker documents.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



e general syntax is:
    

      !block changed
  ...
  !endblock

    

    See Understanding Filter Interfaces, if necessary.
    

    

    Description>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: FormatTime

H2: Purpose

This routine is used to format a date-time quantity into a
human readable form.

H2: Interface

E:  $result = &FormatTime($fmt, $var);

H2: Description

The first parameter is either a format string or the name of a variable
containing a format string.
The second parameter is the name of the variable to be formatted.
The variable's value is a number of seconds since January 1, 1970.

The building blocks used in the format strings are given below.

!block table; format=352
Symbol:Description:Example
$day:day number in month:6 or 22
$day0:day number in month zero-padded:06 or 22
$month:month name:January
$smonth:abbreviated month name:Jan
$monthnum:month number (1..12):6 or 12
$monthnum0:month number zero-padded (01..12):06 or 12
$year:year:1995
$syear:abbreviated year:95
$weekday:weekday name:Monday
$sweekday:abbreviated weekday name:Mon
$hour:hour (1..24):6 or 14
$hour0:hour zero-padded (01..24):06 or 14
$shour:hour (1..12):6 or 12
$shour0:hour zero-padded (01..12):06 or 12
$ampm:am or pm:am
$AMPM:AM or PM:PM
$minute:minute (0..59):0 or 42
$minute0:minute zero-padded (00..59):00 or 42
$second:second (0..59):0 or 42
$second0:second zero-padded (00..59):00 or 42
!endblock

Commonly used formats are defined in the variables given below.

!block table
Variable    Value
FMT_FULL    $day $month $year, $hour:$minute0.$second0
FMT_TIME    $hour:$minute0.$second0
FMT_DATE    $day $month $year
FMT_CONCISE $day0-$smonth-$syear
!endblock

H2: Examples

To format the 'last modified' date-time for a document:

E:   &FormatTime('FMT_FULL', 'DOC_MODIFIED')

To format the year when conversion started (for copyright reasons, say):

E:   &FormatTime('$year', 'DOC_START')
sdf-2.001/doc/ref/in_esc.sdf010064400042570001753000000140150645730246400154100ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1998, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 15-Jan-98 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
H1: Escape Characters

The escape characters available are summarised below.
Escape characters are entered in paragraphs using either the {{E}}
or {{CHAR}} phrase styles.

!block table; groups
Symbol          Description                             Output
Syntax related:
lt              less-than                               E
gt              greater-than                            E
2{              double left brace                       E<2{>
2}              double right brace                      E<2}>
2[              double left bracket                     E<2[>
2]              double right bracket                    E<2]>
Special symbols:
amp             ampersand                               E
bullet          bullet                                  E
c               copyright                               E
cent            cent                                    E
dagger          dagger                                  E
doubledagger    double dagger                           E
emdash          em-dash                                 E
endash          en-dash                                 E
emspace         em-space                                E
enspace         en-space                                E
lbrace          left brace                              E
lbracket        left bracket                            E
nbdash          non-breaking hyphen                     E
nbspace         non-breaking space                      E
nl              newline                                 E
pound           pound                                   E
quot            double quote                            E
r               registered trademark                    E
rbrace          right brace                             E
rbracket        right bracket                           E
tab             tab                                     E
tm              trademark                               E
yen             yen                                     E

International:
Aacute          capital A, acute accent                 E
aacute          small a, acute accent                   E
Acirc           capital A, circumflex accent            E
acirc           small a, circumflex accent              E
AElig           capital AE diphthong (ligature)         E
aelig           small ae diphthong (ligature)           E
Agrave          capital A, grave accent                 E
agrave          small a, grave accent                   E
Aring           capital A, ring                         E
aring           small a, ring                           E
Atilde          capital A, tilde                        E
atilde          small a, tilde                          E
Auml            capital A, dieresis or umlaut mark      E
auml            small a, dieresis or umlaut mark        E
Ccedil          capital C, cedilla                      E
ccedil          small c, cedilla                        E
Eacute          capital E, acute accent                 E
eacute          small e, acute accent                   E
Ecirc           capital E, circumflex accent            E
ecirc           small e, circumflex accent              E
Egrave          capital E, grave accent                 E
egrave          small e, grave accent                   E
Euml            capital E, dieresis or umlaut mark      E
euml            small e, dieresis or umlaut mark        E
Iacute          capital I, acute accent                 E
iacute          small i, acute accent                   E
Icirc           capital I, circumflex accent            E
icirc           small i, circumflex accent              E
Igrave          capital I, grave accent                 E
igrave          small i, grave accent                   E
Iuml            capital I, dieresis or umlaut mark      E
iuml            small i, dieresis or umlaut mark        E
Ntilde          capital N, tilde                        E
ntilde          small n, tilde                          E
Oacute          capital O, acute accent                 E
oacute          small o, acute accent                   E
Ocirc           capital O, circumflex accent            E
ocirc           small o, circumflex accent              E
Ograve          capital O, grave accent                 E
ograve          small o, grave accent                   E
Oslash          capital O, slash                        E
oslash          small o, slash                          E
Otilde          capital O, tilde                        E
otilde          small o, tilde                          E
Ouml            capital O, dieresis or umlaut mark      E
ouml            small o, dieresis or umlaut mark        E
Uacute          capital U, acute accent                 E
uacute          small u, acute accent                   E
Ucirc           capital U, circumflex accent            E
ucirc           small u, circumflex accent              E
Ugrave          capital U, grave accent                 E
ugrave          small u, grave accent                   E
Uuml            capital U, dieresis or umlaut mark      E
uuml            small u, dieresis or umlaut mark        E
yuml            small y, dieresis or umlaut mark        E
!endblock
{CHAR}} phrase styles.

!block table; groups
Symbol          Description                             Output
Syntax related:
lt              less-than                               E
gt              greater-than                            E
2{              double left brace                       E<2{>
2}              double right brace                      E<2}>
2[              double left bracket                     E<2[>
2]              double right bracket                    E<2]>
Spesdf-2.001/doc/ref/mperlapi.html010064400042570001753000000040670672242543600161570ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: perlapi Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.35. perlapi Macro
    

    

    Interface
    

    The general syntax is:
    

      !perlapi filename [; filter] [; params]

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

filename


string


 


 


    

    

filter


filter


_NULL_


 


    

    

params


rest


_NULL_


 


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description The perlapi macro extracts the API of a Perl 4 library which follows SDF's coding conventions.
    

    

    Examples
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/sdftest.html010064400042570001753000000047610672242562000160160ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: sdftest - Execute SDF Regression Tests




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    11.7. sdftest - Execute SDF Regression Tests
    

    

    Purpose
    

    sdftest executes the regression tests provided with SDF.
    

    

    Usage
    

      sdftest

    

    

    Description
    

    This program is typically run just after SDF has been installed to check that the installation succeeded. However, users should be able to run it at any time to confirm that everything is still ok.
    

    This program works by iterating over the sdf files in the test directory where SDF is installed. For each file called xx.sdf, it generates xx.out and xx.log files containing the output and error logs, respectively. These files are then validated against the expected files in the checked directory.
    

    
Note: Generated files which are ok are deleted. However, if a test fails, the file which failed is not deleted, so a user can then use diff, say, to analyse what the problem is.

    

    

    Limitations and future directions
    

    This program only provides regression testing on the core SDF engine. In particular, it doesn't provide regression testing on the drivers used to generate each of the different output formats (e.g. HTML, PostScript).
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/in_sub.html010064400042570001753000000037450672242566600156340ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: PrependText




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    12. Subroutines
    

    

    12.1. Overview
    

    The subroutines available are summarised below.
    

    

    

Name


Purpose


    

    

FormatTime


format a date-time value


    

    

AppendText


within the on macro, appends text after the current line


    

    

PrependText


within the on macro, prepends text before the current line


    

    

FindFile


override this if you need custom searching rules


    

    


    Further details on these are provided below.
    

    AppendText
    

    FindFile
    

    FormatTime
    

    PrependText
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/muse.html010064400042570001753000000036230672242546000153110ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: use Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.42. use Macro
    

    

    Interface
    

    The general syntax is:
    

      !use filename [; filter] [; params]

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

filename


string


 


 


    

    

filter


filter


sdf


 


    

    

params


rest


_NULL_


 


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The use macro loads a (library) module.
    

    

    Examples
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/sdf.html010064400042570001753000000474170672242554500151310ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: sdf - SDF Conversion Utility




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    11.2. sdf - SDF Conversion Utility
    

    

    Purpose
    

    sdf converts SDF files to other document formats.
    

    

    Usage
    

    usage  : sdf [+alias] [-h[help]] [-o[out_ext]]
         [-l[log_ext]] [-O[out_dir]] [-2 format]
         [-D variable,..] [-n split_level]
         [-f flag,..] [-I include_path,..]
         [-p[prefilter]] [-a parameters] [-P[plang]]
         [-N[line_numbers]] [-g[get_report]]
         [-r report] [-L locale] [-k look]
         [-s style] [-S page_size] [-c config]
         [-u uses,..] [-H head_level] [-K head_look]
         [-d driver] [-y post_filter]
         [-z post_process,..] [-t target]
         [-v[verbose]] [-T trace_levels,..]
         [-w width] [-Y library_path,..]
         sdf_file ...
purpose: convert an sdf file to another format
version: 2.001    (SDF 2.001)

    

    The options are:
    

    

    

Option


Description


    

    

-h


display help on options


    

    

-o


output file extension


    

    

-l


log file extension


    

    

-O


output to input file's (or explicit) directory


    

    

-2


the output format you want


    

    

-D


define variables


    

    

-n


heading level to autosplit into topics


    

    

-f


define flags (i.e. DOC_* variables)


    

    

-I


search path for include files, templates, etc.


    

    

-p


pre-filter input file from each argument


    

    

-a


parameters for the pre-filter


    

    

-P


pre-filter as a programming language


    

    

-N


number lines in pretty-printed source code


    

    

-g


pre-filter using sdfget with the report specified


    

    

-r


report to run on the SDF to transform it before formatting


    

    

-L


locale


    

    

-k


look library


    

    

-s


style of document


    

    

-S


page size for paper documents


    

    

-c


configuration library


    

    

-u


modules to use


    

    

-H


initial heading level


    

    

-K


heading look (H, A or P)


    

    

-d


format driver - default is expand


    

    

-y


filter to post-filter the output with


    

    

-z


list of post processing actions to do


    

    

-t


logical target format


    

    

-v


verbose mode


    

    

-T


debugging trace levels


    

    

-w


width for text-based outputs


    

    

-Y


search path for libraries


    

    


    The aliases are:
    

    

    

Alias


Description


    

    

mc


generate a MIMS chapter


    

    

ms


generate a MIMS spec


    

    

mt


generate a MIMS topic


    

    

sdf2doc_fm


generate Frame binary format via FrameMaker


    

    

sdf2dvi_sgml


generate DVI format via SGML


    

    

sdf2fvo_fm


generate FrameViewer format via FrameMaker


    

    

sdf2hlp_mif


generate Windows Help input files via MIF


    

    

sdf2html_


generate a HTML document


    

    

sdf2html_dir


generate an SDF directory in HTML


    

    

sdf2html_fm


generate a HTML document via FrameMaker


    

    

sdf2html_topics


generate HTML topics


    

    

sdf2htx_


generate MIMS HTX format


    

    

sdf2info_sgml


generate GNU info format via SGML


    

    

sdf2latex_


generate LaTeX


    

    

sdf2latex_pod


generate LaTeX format via POD


    

    

sdf2latex_sgml


generate LaTeX format via SGML


    

    

sdf2lyx_sgml


generate a LyX file via SGML


    

    

sdf2man_pod


generate Man page format via POD


    

    

sdf2mf6_


generate MIMS F6 help format


    

    

sdf2mif_


generate Frame MIF format


    

    

sdf2pdf_html


generate PDF via HTML


    

    

sdf2pdf_mif


generate PostScript and PDF via FrameMaker


    

    

sdf2pod_


generate POD format


    

    

sdf2ps_fm


generate PostScript via FrameMaker


    

    

sdf2ps_fmbook


generate PostScript via a FrameMaker book


    

    

sdf2ps_html


generate PostScript via HTML


    

    

sdf2ps_pod


generate PostScript via POD


    

    

sdf2ps_sgml


generate PostScript via SGML


    

    

sdf2rtf_fm


generate RTF format via FrameMaker


    

    

sdf2rtf_mif


generate RTF format via MIF


    

    

sdf2rtf_sgml


generate RTF format via SGML format


    

    

sdf2sdf_expand


generate expanded SDF


    

    

sdf2sdf_raw


generate raw SDF


    

    

sdf2sgml_


generate SGML format


    

    

sdf2txt_


generate plain text format


    

    

sdf2txt_fm


generate plain text format via FrameMaker


    

    

sdf2txt_pod


generate plain text format via POD


    

    


    

    Description
    

    The -h option provides help. If it is specified without a parameter, a brief description of each option is displayed. To display the attributes for an option, specify the option letter as a parameter.
    

    By default, generated output goes to standard output. To direct output to a file per input file, use the -o option to specify an extension for output files. If the -o option is specified without a parameter, an extension of out is assumed.
    

    Likewise, error messages go to standard error by default. Use the -l option to create a log file per input file. If the -l option is specified without a parameter, an extension of log is assumed.
    

    By default, generated output and log files are created in the current directory. Use the -O option to specify an explicit output directory. If the -O option is specified without a parameter, the input file's directory is used.
    

    The -2 option is a convenient way of specifying the alias (collection of options) which generates the output you want. e.g.
    

         sdf -2html abc

    

    is equivalent to:
    

         sdf +sdf2html abc

    

    The -D option is used to define variables. These are typically used for controlling conditional text and substituting text which changes. The format used is:
    

     -Dvariable1=value1,variable2=value2

    

    A flag is a shorthand way of specifying variables in the DOC family. i.e. -ftoc=3 is equivalent to -DDOC_TOC=3. The format of the -f option is:
    

     -fflag1=value1,flag2=value2

    

    If a variable or flag is specified without a value, 1 is assumed.
    

    To generate HTML topics, the command is:
    

         sdf -2topics abc

    

    By default, this will create sub-topics for each heading already in a separate file. It will also autosplit level 1 headings into sub-topics. The -n option can be used to control which level headings are split at:
    

      

    • 1 autosplits on level 1 headings (the default)

    • 2 autosplits on level 2 headings

    • 3 autosplits on level 3 headings

    • 0 disables autosplitting.
    

    Include files are searched for in the current directory, then in the directories given by the -I option, then in the default library directory.
    

    By default, sdf is configured to prefilter files with certain extensions. For example:
    

     sdf mytable.tbl

    

    is equivalent to executing sdf on a file which only contains:
    

     !include "mytable.pl"; table

    

    The -p option can be used to explicitly prefilter files or to override the default prefilter used. If a parameter is not provided, the prefilter is assumed to be table.
    

    The -a option can be used to specify parameters for the prefilter. For example:
    

     sdf -aformat='15,75,10' mytable.tbl

    

    The -P option prefilters the input files as programming languages. The parameter is the language to use. If none is provided, the extension is assumed to be the language name. For example:
    

     sdf -P myapp.c

    

    is equivalent to executing sdf on a file which only contains:
    

     !include "myapp.c"; example; wide; lang='c'

    

    The -N option adds line numbers at the frequency given. The default frequency is 1. i.e. every line.
    

     The -g option prefilters the input files by executing sdfget using the default report (default.sdg). To change the report used, specify the report name as the parameter. If the report name doesn't include an extension, sdg is assumed.
    

    
Note: sdfget searches for reports in the current directory, then in the stdlib directory within SDF's library directory.

    

    The -r option runs the nominated SDR report on each input before formatting. In other words, SDR reports provide a mechanism for:
    

      

    • analysing the SDF just before it would be formatted, and

    • replacing that SDF with the output of the report (also SDF) so that the final output is a nicely formatted report.
    

    For example, the sdf_dir report generates a directory (tree) of the components (files) included in an SDF document. Reports are stored in sdr files and are searched for using the usual rules.
    

    The -L option can be used to specify a locale. The default locale name is specified in sdf.ini. Locale naming follows POSIX conventions (i.e. language_country), so the locale name for American english is en_us. The information for each locale is stored in the locale directory, so you'll need to have to look in there to see what locales are available. (As the default locale can be set in sdf.ini, this isn't as ugly as it first sounds.)
    

    
Note: At the moment, a locale file simply contains a list of language specific strings. Ultimately, it should be extended to support localisation of date and time formats.

    

    The -k option is used to specify a look. The default look library is specified in sdf.ini.
    

    The -s option can be used to specify a document style. Typical values are:
    

      

    • document - a technical document

    • memo - a memo

    • fax - a facsimile

    • minutes - minutes of a meeting.
    

    The -S option is used to specify the page size. Values supported include:
    

    

    

Name


Width


Height


Comment


    

    

global


21.0cm


11.0in


will fit on either A4 or letter


    

    

A3


29.7cm


42.0cm


 


    

    

A4


21.0cm


29.7cm


 


    

    

A5


14.8cm


21.0cm


 


    

    

B4


25.7cm


36.4cm


 


    

    

B5


17.6cm


25.0cm


 


    

    

letter


8.5in


11.0in


 


    

    

legal


8.5in


14.0in


 


    

    

tabloid


11.0in


17.0in


 


    

    


    Additional page sizes can be configured in sdf.ini. To specify a rotated version of a named page size, append an R. For example, A4R implies a width of 29.7cm and a height of 21cm. A custom page size can also be specified using the format:
    

         {{width}}x{{height}}

    

    where width and height are the respective sizes in points.
    

    The -c option is used to specify a configuration library.
    

    A list of modules to use can be specified via the -u option.
    

     The initial heading level to start on can be specified via the -H option. This is useful if you want to preview how a topic will be displayed without regenerating the complete document. If a topic begins with a level 1 heading (e.g. H1) and you wish to format it as a document (i.e. the level 1 text becomes the DOC_NAME for build_title), use the -H option with a value of 0.
    

    The look of headings can also be adjusted. By default, H-style headings are numbered, A-style headings are lettered and P-style headings are plain. To force a particular style for all headings, the -K option can be used. Sensible parameter values are H, A and P although other values may work depending on what paragraph styles are configured at your site.
    

    The -d option is used to specify the format driver. Values supported include:
    

      

    • expand - format as expanded text (the default)

    • mif - Maker Interchange Format

    • pod - Plain Old Documentation (as used by Perl).
    

    Additional drivers can be configured in sdf.ini.
    

    The -y option can to used to specify a post-filter.
    

    The -z option can be used to specify a list of post-processing actions you want to execute on each output file after it is generated. The actions supported include:
    

      

    • ps - generate PostScript

    • doc - generate a Frame (binary) file

    • fvo - generate a Frame View-Only file

    • txt - generate a text file

    • rtf - generate an RTF file

    • clean - delete the output file (must be last).
    

    Additional actions can be configured in sdf.ini. By convention, the generated files are given the same names as the action keywords.
    

    The -t option is used to specify the logical target format. If none is specified, the default is the first post processing action, if any. Otherwise, the default is the format driver name.
    

    The -v option enables verbose mode. This is useful for debugging problems related to post processing. In particular, post processing actions containing the pattern clean are skipped in verbose mode. You can also switch off the post processing messages by using a verbose value of -1. Values higher than 1 switch on additional trace messages as follows:
    

      
2 - show how names of files and libraries are resolved

      
3 - show the directories searched for libraries

      
4 - show the directories searched for modules

      
5 - show the directories searched for normal files.
    

    The -T option can be used to switch on debug tracing. The parameter is a comma-separated list of name-value pairs where each name is a tracing group and each value is the level of tracing for that group. To get the trace output provided by the -v option, one can use the user group like this:
    

      sdf -Tuser=2 ...

    

    This is slightly different from the -v option in that intermediate files are not implicitly kept. Additional tracing groups will be added over time (probably one per output driver).
    

    The -w option is used to specify the width for text-based outputs.
    

    The -z, -D, -f and -I options are list options. i.e. multiple values can be separated by commas and/or the options can be supplied multiple times.
    

    

    Examples
    

    Convert mydoc.sdf to a technical document in mif format, output is mydoc.mif:
    

     sdf -2mif mydoc.sdf

    

    Convert mydoc.sdf to online documentation in FrameViewer format, output is mydoc.fvo:
    

     sdf -2fvo mydoc.sdf

    

    Convert mydoc.sdf to online documentation in HTML, output is mydoc.html:
    

     sdf -2html mydoc.sdf

    

    The following command will build the reference documentation for a SDF module in HTML:
    

     sdf -2html abc.sdm

    

    

    Limitations and future directions
    

    Many of the default post processing (-z) actions only works on Unix as FrameMaker for Windows does not support batch conversion.
    

    Topics mode has several limitations:
    

      

    • only documents in the current directory can be converted

    • all sub-topics must also be in the current directory.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



 default, sdf is configured to prefilter files with certain extensions. For example:
    

     sdf mytable.tbl

    

    is equivalent to executing sdf on a file which onlsdf-2.001/doc/ref/mon.html010064400042570001753000000042640672242543000151300ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: on Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.33. on Macro
    

    

    Interface
    

    The general syntax is:
    

      !on type mask ; [id] ; code

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

type


symbol


 


<paragraph|phrase|macro|filter|table>


    

    

mask


string


 


 


    

    

id


eventid


_NULL_


<\w+>


    

    

code


rest


 


 


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The on macro specifies a rule to execute on certain events.
    

    See Event Processing in the SDF User Guide for further details.
    

    

    Examples
    

    To be completed ...
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/fsimple.html010064400042570001753000000044610672242525700160040ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: simple Filter




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5.30. simple Filter
    

    

    Interface
    

    !block simple [;parameters]
...
!endblock

    

    The parameters are:
    

    

    

Name


Description


    

    

pre


Perl code to execute before the block


    

    

exec


executed for each line with $line containing the text line


    

    

post


Perl code to execute after the block


    

    


    

    Description
    

    The simple filter is typically used as a building block for other filters. It provides a simple way of specifying the before (pre), per-line (exec) and after (post) actions.
    

    
Note: As creating new filters is not something that the average SDF users does, this filter is really provided to make life easier for advanced SDF users and SDF administrators.

    

    

    Examples
    

    !on filter "testcases";; \
        $name='simple'; \
        $params.=';pre="!testcaseStart"'; \
        $params.=';post="!testcaseEnd"'

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/index.html010044400042570001753000000040520672242573600154500ustar00iancmtr00000400000236






SDF 2.001: SDF Reference




    

    

    Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    SDF Reference
    

    MTR-SDF-0004.001 (Final)
    

    Ian Clatworthy
    

    25 May 1999
    

    

    

    

    

    Table of Contents
    


    

    

    

    Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/mjumps.html010064400042570001753000000041410672242541300156450ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: jumps Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.28. jumps Macro
    

    

    Interface
    

    The general syntax is:
    

      !jumps labels [; layout]

    

    The arguments are:
    

    

    

Name


Type


Default


Rule


    

    

labels


string


 


 


    

    

layout


string


Center


<Left|Center|Right|left|center|right>


    

    


    See Understanding Macro Interfaces, if necessary.
    

    

    Description
    

    The jumps macro generates lines of jumps to headings.
    

    

    Examples
    

    Typical usage is:
    

       !jumps "Purpose,Usage,,Description,Examples"

    

    This will create two jump lines: the first has Purpose and Usage; the second has Description and Examples.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/in_claif.sdf010064400042570001753000000175050647050434000157130ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Understanding Class Interfaces

H2: Overview

H3: General Syntax

The general syntax for declaring and/or formatting a table of
objects in the class is shown first.
By convention, the filter is shown using the {{MAC:block}}
and {{MAC:endblock}} macros, although filters can also be
used with other macros, including {{MAC:include}} and {{MAC:execute}}.

H3: Object Attributes

The attributes supported for each class are listed in a table
with the following columns:

* {{Field}} - the field name
* {{Category}} - {{key}}, {{mandatory}} or {{optional}}
* {{Rule}} - the pattern, if any, used to validate the value.

H2: Parameters

H3: Overview

All class filters support the set of parameters listed below.

!block table
Name       Type         Description
data       boolean      define objects but do not display them
cited      boolean      number these objects as the cited ones \
                        (for [1] style references)
root       string       string to prepend to Jump attribute, if any
columns    string       comma-separated list of attributes to display in table
style      string       table style to use (the default is {{plain}})
compact    boolean      display in a compact table, (make cellpadding \
                        and cellspacing both equal to zero)
wide       boolean      use sidehead when formatting on paper
headings   boolean      display the column headings
where      string       filter the rows using the nominated expression
sort       string       comma-separated list of columns to sort by
colaligns  string       a comma-separated list of horizontal alignments  \
                        values (Left, Center, Right) for columns; \
                        alternatively, a single word containing the \
                        letters L, C and R can be used for the value
colvaligns string       a comma-separated list of vertical alignments  \
                        values (Top, Middle, Bottom, Baseline) for columns; \
                        alternatively, a single word containing the \
                        letters T, M, B and L can be used for the value
select     string       a comma-separated list of columns to display
delete     string       a comma-separated list of columns to delete
wrap       integer      number of logical rows to place on a physical row
!endblock

H2: Building the Columns

H3: Using the columns Parameter

The {{columns}} parameter is a comma-separated list of:

E:   [tag":"]attribute["&"view]

:where:

* {{tag}} is a phrase style (or expression format)
* {{attribute}} is the name of an attribute of the class
* {{view}} is a view to apply to the object when looking up or
  calculating that attribute (see {{SECT:Object Views}} below).

To remember the syntax for applying an object view, think of C's
bit-masking operator, &.

Examples are given below:

!block table
Column          Description
Code            output the Code attribute
2:Code          output the Code using the 2 (emphasised) phrase style
BUG:Code        output the Code using the BUG phrase style
CONCISE:Date    output the Date attribute using the CONCISE format
!endblock

H3: Calculated Attributes

Some class filters support calculated attributes, so the total set of
attributes you can place in the {{columns}} parameter can be quite
large. For example, for {{CLASS:references}}, an unknown attribute
which is sequence of uppercase letters is assumed to be a file
extension and the generated attribute is an icon providing a jump
to that file, if any. For example, if a reference has a {{Jump}}
attribute of {{xyz.html}}, then the PDF attribute is an image (pdf.gif)
which provides a jump to {{xyz.pdf}}.

H3: Object Views

On some occasions, it can be very useful if the value placed in a column
is a variation of an attribute, rather than the attribute itself.
For example, the {{CLASS:references}} class supports an attribute
called PS which is an image (postscript.gif) with a jump to {{xyz.ps}}
(assuming the {{Jump}} attribute is {{xyz.html}}). But what if the
PostScript file is in a different place to the HTML file? In this case,
you need to use an object {{view}}.

For example, the {{DOC: SDF Document Catalog}} provides access to
SDF's documents in several formats:

* PDF and PostScript, stored on SDF's web site
* HTML, stored locally.

This catalog was created by using the following {{columns}} parameter:

>  columns='PDF&website,PS&website,DOC:Document,Date,Pages'

where {{website}} is a file containing the following:

>  prefix_Jump=http://www.mincom.com/mtr/sdf/

The name of a view is either a file or a directory:

* If the name of a view is a file, then the view
  is loaded from that file. The format is a same
  as a set of name-value pairs in an {{FMT:INI}} file.
* If the name of a view is a directory, then a view
  with {{prefix_Jump=name/}} is returned.

Within a view, the parameters supported are:

* {{prefix_xxx}} - prefix for attribute {{xxx}}
* {{suffix_xxx}} - suffix for attribute {{xxx}}.

Note: If it proves helpful, I'm happy to expand this list
to include other types of parameters like {{default_xxx}} and
{{value_xxx}}, say.


H2: Filtering and Sorting

H3: Filter Expressions

The {{where}} attribute takes an expression which is evaluated
for each record. Special symbols available are:

!block table
Symbol      Meaning
$_          the current record
$o{"xyz"}   the value of column xyz
$var{"abc"} the value of variable abc
!endblock

For example:

E: !define MODULE_CODE "XYZ"
E: ...
E: !include "../document.reg"; references; compact; \
E:   where='$o{"Reference"} =~ /$var{"MODULE_CODE"}/'; \
E:   columns="PS,REF:Reference,DOC:Document,CONCISE:Date"

H3: Sorting

{{sort}} takes a comma-separated list of column names to sort on.
If no columns are specified, the data is sorted using
all columns in the order in which they appear. All sorting
is done alphabetically - numeric sorting is not supported.

H3: Using the delete Parameter

The {{delete}} parameter is particularly useful if you want to sort or
filter a table (using the {{sort}} and {{where}} parameters, respectively)
using columns which you don't want in the output. For example:

!block verbatim
  # Load the bug tracking module
  !use "bugtrack"

  # Display the open bugs, sorted by priority
  H1: Open Defects
  !include 'bugs.reg'; bugs; headings; \
           columns='Code,BUGTITLE:Title,Status,Priority'; \
           where='$o{"Status"} eq "Open"'; \
           sort='Priority'; \
           delete='Status'
!endblock

Note: The order of the parameters to a class filter are not
important, although the order above best reflects the processing.

In the case above, the {{columns}} parameter builds a data table
which is then filtered and sorted. Note that the {{Status}}
and {{Priority}} attributes are required in the columns as
those attributes are required to do the filtering and sorting.
However, as the heading tell the user that this is the table
of open defects, we don't need/want the {{Status}} attribute
in the output, so we delete it.

H3: Filtering Using the catalog Macro

Another way of building the table above is to use the {{MAC:catalog}}
macro like this:

!block verbatim
  # Load the bug tracking module
  !use "bugtrack"

  # Load the bug data
  !include 'bugs.reg'; bugs; data

  # Display the open bugs, sorted by priority
  H1: Open Defects
  !catalog bugs 'Status:Open'; headings; \
           columns='Code,BUGTITLE:Title,Priority'; \
           sort='Priority'
!endblock

In this case, the filtering is done before the data reaches the
class filter, so things are easier once the data has been loaded.
is a phrase style (or expression format)
* {{attribute}} is the name of an attribute of the class
* {{view}} is a view to apply to the object when looking up or
  calculating that attribusdf-2.001/doc/ref/in_dstyl.html010064400042570001753000000047540672242511600161710ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: Document Styles




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    2. Document Styles
    

    The document styles available are summarised below.
    

    

    

Style


Purpose


    

    

General:


 


    

    

document


a normal document


    

    

manual


a manual


    

    

paper


a technical paper


    

    

Administration:


 


    

    

admin


generic administration document


    

    

fax


a fascimile


    

    

memo


a memorandum


    

    

newslttr


a newsletter


    

    

minutes


minutes of a meeting


    

    

Miscellaneous:


 


    

    

listing


a source code listing


    

    


    For HTML output, the general styles are all the same. For PostScript output, they typically differ as follows:
    

      

    • document - single-sided, busy cover page, busy headers/footers, table of contents

    • manual - double-sided, simple cover page, simple header/footers, table of contents

    • paper - single-sided, no cover page (just a centered title), simple header/footers, no table of contents.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/ref/in_mac.html010064400042570001753000000212170672242546100155660ustar00iancmtr00000400000236






SDF 2.001: SDF Reference: use Macro




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6. Macros
    

    

    6.1. Overview
    

    The macros available are summarised below.
    

    

    

Name


Purpose


    

    

General:


 


    

    

build_title


build a title page


    

    

block


begin a block of text


    

    

endblock


end a block of text


    

    

include


include another file


    

    

execute


include output from a command


    

    

Variables:


 


    

    

init


initialise variables (before loading configuration files)


    

    

define


set a variable


    

    

default


set a variable (if not already set)


    

    

undef


clear a variable


    

    

export


export a variable to the format driver (and/or mark it for later exporting)


    

    

restrict


declare a restricted family of variables


    

    

Figures:


 


    

    

import


import an external object (e.g. figure)


    

    

clear


reset text wrapping around a figure


    

    

Libraries:


 


    

    

inherit


inherit entities from a library


    

    

use


load a library module


    

    

Macros:


 


    

    

macro


begin a macro definition


    

    

endmacro


end a macro definition


    

    

insert


call a macro


    

    

Classes:


 


    

    

class


define a class of objects


    

    

catalog


build a catalog from objects already loaded


    

    

Conditional text:


 


    

    

if


begin conditional text


    

    

elsif


begin a conditional section


    

    

else


begin alternative section


    

    

endif


end conditional text


    

    

elseif


same as elsif


    

    

Event processing:


 


    

    

on


specify processing for an event


    

    

off


disable processing previously specified


    

    

File processing:


 


    

    

output


dynamically change the output file used


    

    

script


execute a line of Perl


    

    

message


output a message during execution


    

    

line


change message parameters


    

    

slide_down


decrease heading levels (e.g. H2 -> H3)


    

    

slide_up


increase heading levels (e.g. H2 -> H1)


    

    

Extraction:


 


    

    

getdoc


extract documentation embedded in source code


    

    

getcode


extract source code (i.e. non-documentation) from a file


    

    

getcli


extract command-line interface information


    

    

perlapi


extract API information from a Perl library


    

    

Miscellaneous:


 


    

    

jumps


generates lines of jumps


    

    

subsections


specify the subsections for a topic


    

    

continued


continue a heading from a previous page


    

    

end_topic


mark the end of a topic


    

    


    Further details on these are provided below.
    

    block Macro
    

    build_title Macro
    

    catalog Macro
    

    class Macro
    

    clear Macro
    

    continued Macro
    

    default Macro
    

    define Macro
    

    else Macro
    

    elseif Macro
    

    elsif Macro
    

    end_topic Macro
    

    endblock Macro
    

    endif Macro
    

    endmacro Macro
    

    execute Macro
    

    export Macro
    

    getcli Macro
    

    getcode Macro
    

    getdoc Macro
    

    if Macro
    

    import Macro
    

    include Macro
    

    inherit Macro
    

    init Macro
    

    insert Macro
    

    jumps Macro
    

    line Macro
    

    macro Macro
    

    message Macro
    

    off Macro
    

    on Macro
    

    output Macro
    

    perlapi Macro
    

    restrict Macro
    

    script Macro
    

    slide_down Macro
    

    slide_up Macro
    

    subsections Macro
    

    undef Macro
    

    use Macro
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/guru/004075500042570001753000000000000672243775000136645ustar00iancmtr00000400000236sdf-2.001/doc/guru/parse.html010064400042570001753000000315220672242231100156470ustar00iancmtr00000400000236






SDF 2.001: SDF Guru Guide: parse.pl - Simple Document Format Library




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    2.6. parse.pl - Simple Document Format Library
    

    

    2.6.1. Purpose
    

    This library provides support for handling SDF files.
    

    

    2.6.2. Interface
    

    require "parse.pl";

%SDF_IMAGE_EXTS = ...

%sdf_driver = ...

%sdf_report = ...

%sdf_pagesize = ...

$sdf_subtopic_cnt = ...

$sdf_fmext = ...

@sdf_include_path = ...

@sdf_library_path = ...

$sdf_lib = ...

@sdf_if_start = ...

@sdf_if_now = ...

@sdf_if_yet = ...

@sdf_if_else = ...

$sdf_block_start = ...

$sdf_block_type = ...

@sdf_block_text = ...

%sdf_block_param = ...

@sdf_tbl_start = ...

@sdf_tbl_state = ...

@sdf_end = ...

$sdf_cutting = ...

$sdf_sections = ...

@sdf_book_files = ...

@sdf_report_names = ...

&SdfLoadDrivers(@table);

&SdfLoadPageSizes(@table);

($success, @records) =
&SdfFetch($file);

@records =
&SdfParse(@sdf_strs);

@result =
&SdfConvert(*p_sdf, $target, *uses, %convert_var);

&SdfInit(*var);

($text, $style, %attr) =
&SdfNextPara(*sdf);

($text, %attr) =
&SdfParseCell($cell);

($sect_type, $text, $style, %attr) =
&SdfNextSection(*para, *state);

$pts =
&SdfPoints($measure);

$pts =
&SdfVarPoints($name);

$info =
&SdfPageInfo($page, $attr, $category);

$sdf =
&SdfJoin($style, $text, %attr);

%attrs =
&SdfAttrSplit($attrs);

$attrtext =
&SdfAttrJoin(*attr, $sep);

$attrtext =
&SdfAttrJoinSorted(*attr, $sep);

&SdfAttrClean(*attr);

&SdfAttrMap(*attr, $target, *map_to, *map_map, *map_attrs, $defaults);

($width, $height) =
&SdfSizeGraphic($file);

@result =
&SdfColPositions($columns, $format, $margin);

$prefix =
&SdfHeadingPrefix($type, $level);

$exit_code =
&SdfSystem($cmd);

$exit_code =
&SdfQuietSystem($cmd);

&SdfBatch($flags);

&SdfHtmldoc($infile, $outfile);

&SdfHtmldocHFOpts();

&SdfDelete($file);

&SdfBookClean($ext);

&SdfRenamePS($xx);


    

    

    2.6.3. Description
    

    The following symbols are occasionally accessed from other modules but aren't really for public consumption:
    

    SDF_IMAGE_EXTS, sdf_if_start, sdf_if_now, sdf_if_yet, sdf_if_else, sdf_block_start, sdf_block_type, sdf_block_text, sdf_block_param, sdf_tbl_start, sdf_tbl_state, sdf_end, sdf_cutting, sdf_sections, sdf_book_files, sdf_report_names, SdfSystem, SdfBatch, SdfDelete, SdfBookClean, SdfRenamePS.
    

    sdf_driver is a lookup table of valid format drivers. This table is build by SdfLoadDrivers.
    

    sdf_report is a lookup table of valid reports. This table is build by SdfLoadReports.
    

    sdf_pagesize is a lookup table of valid page sizes. This table is build by SdfLoadPageSizes.
    

    sdf_subtopic_cnt is the counter of subtopics left during topics mode processing.
    

    sdf_fmext is the extension of FrameMaker template files. Typically values are 'fm5' and 'fm4'.
    

    sdf_include_path contains the list of directories searched for to find files specified in include macros. sdf_library_path contains the list of directories searched for to find libraries and modules. In both cases, the current directory and the document's directory are searched before these directories and sdf_lib is searched last of all.
    

    SdfLoadDrivers loads a configuration table of drivers. The columns are:
    

      

    • Name - the driver name

    • Library - the library containing the subroutine

    • Subroutine - the subroutine name.
    

    Call this routine before calling SdfConvert.
    

    SdfLoadPageSizes loads a configuration table of page sizes.
    

    SdfFetch inputs an SDF file, ready for SdfConvert (i.e. ready conversion to another format). It returns 1 if the file is opened successfully.
    

    SdfParse prepares an array of SDF strings for SdfConvert (i.e. for conversion to another format).
    

    SdfConvert converts a list of sdf records to a list of target format paragraphs. The input records to this routine are usually read in by SdfFetch. The output records are typically output to a file, separated by newlines. %convert_var is the initial set of variables.
    

    SdfInit initialises global data used during the conversion process.
    

    SdfNextPara gets the next paragraph from an SDF buffer. Format drivers use this routine to process buffers. @sdf is the buffer which is updated ready for another call to this routine.
    

    SdfParseCell parses an SDF cell into its components.
    

    SdfNextSection gets the next section of a paragraph. Format drivers use this routine to process paragraphs. $para is the paragraph text which is updated ready for another call to this routine. $state is a state variable which this routines uses to help it keep state. sect_type is one of:
    

      

    • string - a string normal paragraph text

    • phrase - a phrase

    • phrase_end - end of a phrase

    • special - a special phrase (e.g. CHAR, IMPORT, etc.)

    • an empty string - end of paragraph
    

    For a string, text is the string, style and attr are empty. At the end of a phrase, text, style and attr are empty.
    

    SdfPoints converts a measurement to points. This is required for calculations involving measurements.
    

    SdfVarPoints converts an variable to points.
    

    SdfPageInfo returns information about a page.
    

    SdfJoin formats a style, text and attributes into a paragraph.
    

    SdfAttrSplit parses a string of attributes into a set of name-value pairs.
    

    SdfAttrJoin formats a set of name-value pairs (%attr) into a string. sep is the separator to use between attributes. The default separator is semi-colon.
    

    SdfAttrJoinSorted formats a set of name-value pairs (%attr) into a string where the attributes are sorted by name. sep is the separator to use between attributes. The default separator is semi-colon.
    

    SdfAttrClean removes target-specific attributes (for other targets) from a set of attributes. However, if the driver is 'raw', all attributes are kept.
    

    SdfAttrMap maps a set of attributes using the configuration tables %map_to, %map_map and %map_attrs. $defaults is a string of default attributes. This routine is used by format drivers to merge user-supplied attributes with those in 'attribute' and 'style' configuration tables.
    

    SdfSizeGraphic returns the width and height of a graphic stored in file. Zero is returned for both values if the size could not be extracted. File types currently supported are EPSI, PICT, GIF and PCX.
    

    SdfColPositions returns a list of column positions given a total number of columns, a format attribute and a right margin.
    

    SdfHeadingPrefix returns the prefix for the next heading. type is H, A or P and level is the heading level.
    

    

    2.6.4. Limitations and future directions
    

    Append/Prepend is not implemented for macros - is it needed for them?
    

    SdfBookConvert currently generates (Unix) shell scripts. It should be generalised to support other operating systems?
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/guru/in_api.sdf010064400042570001753000000035300647456665200156270ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: SDFAPI

H2: Overview

The libraries provided with [[SDF]] are summarised below.

!block table; groups
Name            Purpose
General:
parse.pl        general parsing and processing of SDF files
app.pl          application framework for all SDF scripts
name.pl         filename processing routines
table.pl        table processing routines (including read/write of {{FMT:TBL}} files)
dict.pl         dictionary processing routines
misc.pl         miscellaneous routines
Support:
subs.pl         general run-time support
macros.pl       built-in macros
filters.pl      built-in filters
specials.pl     built-in special phrase styles
Drivers:
toraw.pl        raw format driver
tomif.pl        [[MIF]] format driver
tohtml.pl       [[HTML]] format driver
totxt.pl        plain text format driver
topod.pl        {{POD}} format driver
toman.pl        {{man page}} format driver
API extraction:
apiperl.pl      routines for extracting API information from a [[Perl]] library
!endblock

Further details on the general libraries are given below.

# Add the library directory to the search path
!path_append "../../perllib/sdf"

# Include the subsections, placing each at the top of a page (or after a line)
!if $var{'OPT_TARGET'} eq 'txt'
    !on paragraph 'H2'; h2top; &PrependText("Line:")
!else
    !on paragraph 'H2'; h2top; $attr{'top'} = 1
!endif
!slide_down
!getdoc "app.pl"
!getdoc "dict.pl"
!getdoc "name.pl"
!getdoc "misc.pl"
!getdoc "parse.pl"
!getdoc "table.pl"
!slide_up
!off paragraph h2top
sdf-2.001/doc/guru/app.html010064400042570001753000000657220672242223600153340ustar00iancmtr00000400000236






SDF 2.001: SDF Guru Guide: app.pl - Application Framework Library




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    2.2. app.pl - Application Framework Library
    

    

    2.2.1. Purpose
    

    This library provides a common application framework for Perl scripts.
    

    

    2.2.2. Interface
    

    require "app.pl";

$APP_STDIN_ARGS = ...

$app_lib_dir = ...

@app_exit_routines = ...

%app_config = ...

@app_option_core = ...

@app_option = ...

@app_msg_table = ...

$app_context = ...

$app_lineno = ...

%app_msg_index = ...

$app_log_strm = ...

$app_product_name = ...

$app_product_version = ...

%app_trace_level = ...

&AppMsg($type, $text, $calltree, $log_only);

%count =
&AppMsgCounts($start_index);

$index =
&AppMsgNextIndex();

&AppExit($type, $text, $calltree, $log_only);

&AppTrace($group, $level, $msg, $log_only);

$ok =
&AppInit($arguments, $purpose, $product, $ini_handler);

&AppPrintUsage();

%values =
&AppSectionValues($strs);

&AppShowParts();

&AppShowCallTree();

$app_err =
&AppProcess($arg_process_fn, $arg_post_process_fn, $default_ext);


    

    

    2.2.3. Description
    

    2.2.3.1. Overview
    

    This library provides routines for:
    

      

    • option processing

    • argument processing

    • message handling

    • exiting a script
    

    In principle, scripts using this library have a consistent user interface and internal structure, making them easier to use and maintain. A typical script looks like:
    

         require "sdf/app.pl";

     # define configuration
     %app_config = (
             'inifile',      'abc.ini',
     );

     # define options
     push(@app_option, (
             'str|STR|my string parameter',
     ));

     # handle options
     &AppInit('file ...', 'do things to files') || &AppExit();

     # my post init stuff. e.g.
     # * act on options
     # * pop leading/trailing argument

     &AppProcess('argProcess');

     # my pre exit stuff. e.g.
     # * print summary information

     &AppExit();

    

    To summarise the framework:
    

      

    • %app_config is an optional set of configuration parameters

    • @app_option is the set of options supported

    • AppInit processes options and checks the argument count

    • AppProcess processes arguments (i.e. for each one, calls a user defined subroutine typically called argProcess)

    • argProcess outputs messages using AppMsg

    • AppExit exits and returns an error code to the operating system based on the severity of the messages output via AppMsg
    

    2.2.3.2. Option Definitions
    

    Each option is defined by the fields in the table below.
    

    

    

Field


Description


    

    

Option


option name


    

    

Spec


option specification (type, etc.)


    

    

Help


short description of option


    

    


    The name of the option is used in several ways:
    

      

    • as the name of the Perl variable (e.g. $help)

    • as the name of the long option (e.g. --help)
    

    If short format is enabled (e.g. -h), by default, the first character of the option name is used as the option code. Alternatively, the code to use can be explicitly specified using the Option syntax:
    

          name";"code

    

    This should be done if the default codes are not unique. To specify an option without a parameter, use the following Spec syntax:
    

         BOOL

    

    If no Spec field is specified, this is the default. The value of a parameter-less option is 1 if the option if supplied on the command-line.
    

    To specify an option with a parameter, use the following Spec syntax:
    

         opt_type"-"validation";"initial_value";"default_value

    

    Only the opt_type field is mandatory. The second semi-colon must be present to nominate the parameter as optional. Otherwise, the parameter is assumed to be required. The list of supported opt_types is given in the table below.
    

    

    

Type


Validation


Description


    

    

STR


value list


text string


    

    

INT


min,max


integer number


    

    

NUM


min,max


real number


    

    


    min and max are optional in the validation of numeric options. Typical STR definitions are given below.
    

         STR-(qwe,asd,zxc);qwe;asd       # in-lining of codes
     STR-@ok_array;qwe;asd           # array lookup
     STR-keys %ok_hash;qwe;asd       # hash validate
     STR-values %ok_hash;qwe;asd     # hash validate

    

    An array of STR, INT or NUM can be requested by suffixing the type with 'LIST' or 'HASH'. LIST create a normal array and HASH create an associative array in Perl. Array options can be specified multiple times on the command-line and multiple items can be specified at once separated by commas. For a LIST, the values supplied are appended to the current list. For a HASH, values are treated as follows:
    

      

    • if the format is 'x=y', the result is: $optname{'x'} = 'y'

    • otherwise, the result is: $optname{'x'} = 1
    

    In some cases, it is useful to give an array option an initial value but permit the user to 'reset' the array back to empty. This can be done by defining the option as having an empty optional parameter. i.e. selecting the default value of a parameter-optional LIST or HASH does not append the default value - it initialises the array to the default value.
    

    If finer control is required over processing an option, a routine can be nominated to process an option. To do this, use the following Spec syntax:
    

         ROUTINE"-"routine_name";"initial_value";"default_value

    

    The parameter type is specified by the number of semi-colons:
    

      

    • 0 - no parameter

    • 1 - required parameter

    • 2 - optional parameter
    

    The parameter, if any, is passed as a string to the nominated routine.
    

    2.2.3.3. Configuration Parameters
    

    The configuration parameters supported are summarised below.
    

    

    

Parameter


Description


    

    

inifile


the name of the initialisation file to use, if any


    

    

version


the script version


    

    

product


the product to which this script belongs, if any


    

    

parts


display name & version of components (and exit)


    

    

time


display execution time (when exiting)


    

    

calltree


display the sequence of function calls causing the exit


    

    


    There are several ways to set configuration parameters:
    

      

    1. by initialising %app_config before calling AppInit

    2. by defining parameters in the '[Configuration]' section of an initialisation file

    3. by setting parameters on the command line (using the . option)

    4. for backwards compatibility, certain parameters can be set other ways:
        

      • version can be set via $VERSION{'PUBLIC'}
        

      • product can be set via AppInit
    

    2.2.3.4. Configuration Data
    

    Configuration data can be stored in ini files and loaded during the initialisation stage (i.e. while AppInit is running). To do this, specify a subroutine as the ini_handler parameter for AppInit. The routine is passed the name of the ini file and an associative array containing the sections (after the standard ones like 'Configuration' have been removed). A warning will be produced for any sections not processed by your routine, so delete each section after you have finished processing it. A sample processing routine is given below.
    

    sub iniProcess {
    local($fname, *data) = @_;
#   local();
    local($section);
    local(@my_table, %my_values);

    for $section (sort keys %data) {
        if ($section eq 'MyTable') {
            @my_table = &TableParse($data{$section});
            delete $data{$section};
        }
        elsif ($section eq 'MyValues') {
            %my_values = &AppIniValues($data{$section});
            delete $data{$section};
        }
    }
}

    

    2.2.3.5. Component Descriptions
    

    $APP_STDIN_ARGS is the pseudo argument (default '+') which causes standard input to be processed as a list of arguments. Some scripts may wish to use another symbol (i.e. '+' might be required as a genuine argument), or disable this behaviour altogether. See AppProcess.
    

    $app_path, $app_dir and $app_name are the full pathname, directory and name of the application respectively.
    

    $app_lib_dir is the library directory for this application, i.e. the directory containing configuration files. The default value is the $app_dir. This directory is typically set by searching the Perl library path for the libdir configuration parameter, if any.
    

    @app_exit_routines is the stack of routines to be executed on program termination. If you want a routine to be called on termination (normal and abnormal), push the name of the routine onto this stack. These routines will be executed when AppExit is called. It is thus advisable to ensure that AppExit is NOT called within an exit routine.
    

    %app_config contains the application's configuration parameters. @app_option defines the options supported by the application. The default options are help, out_ext, log_ext and out_dir. To append to these, push your arguments onto the array. For example:
    

     push(@app_option,
      'report|STR|report file',
 );

    

    If the script will never have a need for 'per file' output or errors, assign @app_option_core to @app_option before appending your script-specific options. For example:
    

     @app_option = @app_option_core;
 push(@app_option,
      'report|STR|report file',
 );

    

    To obtain a concise description of each option, use the help option with no parameter. Alternatively, detailed help on a given option can be obtained by suppying the option name as a parameter.
    

    By default, output goes to standard output and diagnostics goes to standard error. These rules can be changed by specifying the out_ext and log_ext options respectively (and calling AppProcess to process arguments). If a string is supplied to these options, it is treated as the extension of the file to send things to for each file. If supplied without a parameter, the extensions default to out and log respectively. A minus character (-) or an equals character (=) can be used to indicate standard output or standard error respectively.
    

    By default, output and log files are created in the current directory. To specify the same directory as the input file, specify the out_dir option without an argument. To specify an explicit directory, pass that directory as the argument to the out_dir option.
    

    app_msg_table defines the known message types. Each type is defined by the attributes in the table below.
    

    

    

Attribute


Description


    

    

Type


message type name


    

    

Severity


application exit code caused by this message


    

    

Layout


format of message text


    

    


    Layout can include the symbols given in the table below.
    

    

    

Symbol


Description


    

    

$text


user text


    

    

$type


message type


    

    

$app_name


application name


    

    

$ARGV


current argument name (usually a file name)


    

    

$app_context


current "context" (e.g. 'line ')


    

    

$.


current line number


    

    

$app_lineno


current line number (if $. is 0)


    

    


    The standard message types are explained in the table below.
    

    

    

Tag


Severity


Description


    

    

current object:


 


 


    

    

object


0


general information


    

    

warning


8


something you should know


    

    

error


16


something you should fix


    

    

abort


24


cannot precede processing


    

    

whole application:


 


 


    

    

app


0


general information


    

    

app_warning


10


something you should know


    

    

app_error


18


something you should fix


    

    

fatal


32


cannot precede processing


    

    

non-user messages:


 


 


    

    

debug


0


debugging diagnostics - ignore


    

    

failed


64


internal check failed - notify developer


    

    


    All messages are output to the standard error stream with a newline appended and prefixed as follows:
    

      

    • object messages by the current object name

    • warning, error and abort by current object name, line number and message type

    • app messages by the application name

    • app_warning messages by the application name and 'warning'

    • app_error messages by the application name and 'error'

    • fatal messages by the application name and 'fatal'

    • debug by application name and 'debug'

    • failed by application name and 'internal failure'
    

    Most applications only use fatal, abort, error and warning. fatal is used when an application decides to terminate. (e.g. when an option is illegal.) abort is used when an application decides not be precede any further on the current object (e.g. too many errors encountered). error is used when a serious error is detected in processing the current object. warning is used when a minor error or possible error is detected. Typically, an application continues processing the current object when an error or warning is encountered but errors prevent further passes on the object while warnings do not.
    

    app_context and app_lineno are the context and line number used in error messages. app_lineno is only used if $. is 0.
    

    %app_msg_index is the index into the message table. (Most programmers have no need for this, but it's provided in case someone does want it.)
    

    $app_log_strm is a stream on which all messages are logged to if it's set. If required, this stream is opened and provided by the user.
    

    app_product_name and app_product_version are the application name and version respectively. These are typically set during execution of the AppInit routine.)
    

    app_trace_level is the highest level of trace messages output by AppTrace for each tracing group.
    

    AppMsg outputs a message. The format of the message is determined by the type parameter which should be defined in app_msg_table. If the type is unknown, behaviour is undefined. If calltree is set, a call tree is dumped after the message is output. If log_only is set, the message is only output to the $app_log_strm, if any.
    

    If a message layout includes the current line number ($.) and it is 0, AppMsg uses the dot-version (e.g. ".error") of the message instead.
    

    The messages output via AppMsg influence the exit code returned to the operating system by AppExit. If you wish to influence this but not output a message, specify a type parameter without a text parameter.
    

    AppMsgCounts returns the number of each message type found. If you are interested in the message counts since a particular point in time, a starting index to begin the counting from can be specified.
    

    AppMsgNextIndex returns the next index to be used in the message log. The value returned can be used as the start_index parameter to the AppMsgCounts routine.
    

    AppExit exits the current application. If a message is specified, it is first output via AppMsg. The exit code returned to the operating system is dependent on the messages output by AppMsg. If calltree is set, a call tree is dumped after the message is output. If log_only is set, the message is only output to the $app_log_strm, if any.
    

    AppTrace outputs a trace message if group tracing is supported and for that group, the trace level is >= level. The default group is called user. If log_only is set, the message is only output to the $app_log_strm, if any.
    

    AppInit processes options and checks the argument count for a perl script. The supported options are defined by @app_option. Options must occur before arguments and begin with a - character for the short format or -- for the long format. Option processing is terminated when either an argument or the -- symbol is detected. If an environment variable of the form app_nameOPTS is found, options are first processed from there.
    

    The expected number of arguments is derived from the format of the arguments parameter as illustrated by the table below.
    

    

    

Expected


Format


    

    

0


""


    

    

0 or more


"..."


    

    

1


"file"


    

    

1 or more


"file ..."


    

    

2


"source destination"


    

    

2 or more


"pattern file ..."


    

    

2 or more


"file ... destination"


    

    


    The pattern "..." is used to detect if a variable number of arguments is permitted. If no arguments are supplied and one or more are expected, then a concise usage message is output. If an application does not require an argument, there is no way to output only a concise usage (use the help option instead). purpose is displayed as part of the usage message. product is an optional parameter. If it is supplied and a product of that name exists in the internal product version lookup table, the product version is included in the usage too. Note that the usage message always includes a script version, regardless of whether a product version is displayed or not.
    

    If AppInit encounters an error, it outputs a usage message and returns 0. Otherwise, it returns 1.
    

    AppPrintUsage outputs the usage header message build during the last call to AppInit. Only the first call to this routine (after AppInit is called) will print the message. This allows programmers to do additional validation after AppInit returns and know that only one usage header message will be output.
    

    AppSectionValues converts an inifile section into a set of name-value pairs.
    

    AppShowParts displays the versions of components making up this application and exits. To support this facility, each library should include a line of the form:
    

      
$VERSION{__FILE__} = "x.y"
    

    Strings containing SCCS or RCS stuff have the baggage stripped. For example:
    

      

    • '@(#) 3.2' is displayed as '3.2'

    • '$Revision: 1.27 $' is displayed as '3.3'
    

    AppShowParts is usually called via the '.parts' special help option. However, certain application code might have a need to call it directly.
    

    AppShowCallTree displays the call tree (excluding the call to itself). The routine is usually called indirectly:
    

      

    • via AppMsg or AppExit (calltree parameter set), or

    • via the .calltree special help parameter
    

    Like AppShowComponents, certain application code may wish to call AppShowCallTree directly.
    

    AppProcess processes each argument on the command-line. In particular, it does the following for each argument:
    

      

    • if the argument is '+', processes each line of standard input as an argument

    • if a file matching an argument is not found, but default_ext is supplied and adding that extension results in a file being found, then default_ext is added as an extension to the argument

    • echos the argument to standard error if there is more than one

    • if $out_ext is set, opens an output file for the current argument and redirects STDOUT to it

    • if $log_ext is set, opens a log file for the current argument and redirects STDERR to it

    • calls arg_process_fn

    • close the output and log files, returning STDOUT and STDERR back to their initial state

    • calls arg_post_process_fn, if any
    

    Note that arg_post_process is optional - it is only used in scripts which need to do additional processing on an file after output streams have been closed.
    

    arg_process_fn has the following interface:
    

         $err = &arg_process_fn($arg)

    

    arg_post_process_fn has the following interface:
    

         $err = &arg_post_process_fn($arg, $arg_err)

    

    where arg_err is the error code returned by arg_process_fn. AppProcess returns the highest error code it encounters from the user processing functions it calls.
    

    If you need to disable the special meaning of '+', set the APP_STDIN_ARGS configuration constant to an empty string. Likewise, you can change the character used by setting it to another value, although this is not recommended given the consistency implications.
    

    

    2.2.4. Limitations and future directions
    

    On MS-DOS using BigPerl v2 or v3, redirecting STDOUT after AppProcess doesn't work.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



> is used when an application decides not be psdf-2.001/doc/guru/name.html010064400042570001753000000152130672242226200154610ustar00iancmtr00000400000236






SDF 2.001: SDF Guru Guide: name.pl - Name Processing Library




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    2.4. name.pl - Name Processing Library
    

    

    2.4.1. Purpose
    

    This library provides support for file-name processing. With careful use, the routines provide portability across Unix-like and Windows-like file-naming systems.
    

    

    2.4.2. Interface
    

    require "name.pl";

$NAME_OS = ...

$NAME_OS = ...

%NAME_DIR_TABLE = ...

%NAME_PATH_TABLE = ...

$NAME_DIR_SEP = ...

$NAME_PATH_SEP = ...

&NameOS();

$result =
&NameIsAbsolute($name);

$result =
&NameAbsolute($name);

$found_name =
&NameFind($name, @dirs);

($dir, $base, $ext, $short) =
&NameSplit($name);

&NamePathComponentSplit();

$name =
&NameJoin($dir, $base, $ext);

$new_name =
&NameSubExt($name, $new_ext);

&NameLoadConversionRules(*table, $validate);

$full =
&NameFindOrGenerate($name, $dir_list_ref, $ext_list_ref, $context);

$full =
&NameFindInDirectory($dir, $base, $ext_list_ref, $context);


    

    

    2.4.3. Description
    

    NAME_OS returns the current operating system style, either unix or dos. NAME_DIR_TABLE and NAME_PATH_TABLE are lookup tables of directory and path separators for different operating system styles. NAME_DIR_SEP and NAME_PATH_SEP are the respective separators for NAME_OS.
    

    NameOS returns the SDF version of the OS name.
    

    NameIsAbsolute returns 1 if the name is in absolute (or non-relative) format.
    

    NameAbsolute returns the absolute name for a file.
    

    NameFind searches the directories for a file with the name given. If found, the combined name (directory + local name) is returned. If the name is absolute, the file is checked to exist. i.e. the directories are not searched. In either case, if the file is not found, an empty string is returned.
    

    NameSplit extracts components from a name. short is the name without the directory.
    

    NamePathComponentSplit completely splits a path into its component parts. Returns a list of the parts.
    

    NameJoin builds a name from its components. If the base name is already absolute, the directory is not prepended.
    

    NameSubExt substitutes the extension on a name.
    

    NameLoadConversionRules loads a table of conversion rules to be used by NameFindOrGenerate. The fields in @table are:
    

      

    • Context - the driver for which this conversion applies

    • To - the destination figure format

    • From - the original figure format

    • Action - the command to use to do the conversion.
    

    Rules do not chain, so defining rules for A->B and B->C do not imply that A will be converted to C. If validate is set, the table is validated.
    

    NameFindOrGenerate searches a list of directories for a file with one of the list of extensions. The extensions are searched for in the order given. If NameLoadConversionRules has been called, this routine will attempt to generate a file in the current directory using the nominated context, if any. If a file was found or generated, the combined name (directory + local name) is returned. If the name is absolute, the file is checked to exist. i.e. the directories are not searched. In either case, if the file is not found, an empty string is returned.
    

    NameFindInDirectory attempts to find a file directory dir using base and the set of extensions given by $ext_list_ref. For each base.ext combination, if it doesn't find that file, it tries to generate a file of that name in the current directory using:
    


    If the file is found or generated, its name is returned, otherwise an empty string is returned.
    

    
Note: If the base already has an extension, the extension list isn't used.

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/guru/about.html010064400042570001753000000041700672242212500156510ustar00iancmtr00000400000236






SDF 2.001: SDF Guru Guide: About this manual




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    About this manual
    

    Purpose
    

    This manual provides information on customising and extending SDF - a documentation system for software developers. Readers should be familiar with the following documents before reading this one:
    


    Scope
    

    This manual contains information on:
    

      

    • how to extend SDF with new entities (e.g. macros, filters, etc.)

    • how to develop an SDF driver to support a new output format

    • SDFAPI - the set of Perl libraries provided with SDF.
    

    Amendments
    

    Suggested enhancements and corrections to SDF and its documentation can be forwarded to sdf-bugs@mincom.com.
    

    
Note: This manual documents version 2.001 of SDF.

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/guru/ex_tbl.sdf010064400042570001753000000015120647021666600156340ustar00iancmtr00000400000236H1: Creating New Table Styles

H2: Using Event Processing

SDF's event processing feature makes it easy to create
a new table style from an existing one. For example, the
following line makes {{schedule}} a variation of the {{shade}} style:

E:!on table 'schedule';; $style='shade'; $param{"wide"} = 1


H2: Using Mapping Tables

SDF uses the {{tablestyles}} filter to define the mapping between
an SDF table style and a target table style.
For example:

!block example; pure
!block tablestyles
Name    To
columns Columns
rows    Rows
grid    Grid
plain   Plain
box     Box
shade   Shade
!endblock
!endblock


H2: Creating New Target Phrase Styles

SDF makes it easy to define new target table styles
by inheriting configuration details from an existing style.

See the {{FILE:look/simple/mif.sdn}} file in the SDF distribution
for examples.
sdf-2.001/doc/guru/ex_para.html010064400042570001753000000042240672242215200161560ustar00iancmtr00000400000236






SDF 2.001: SDF Guru Guide: Creating New Paragraph Styles




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    1.4. Creating New Paragraph Styles
    

    

    1.4.1. Using Event Processing
    

    SDF's event processing feature makes it easy to create a new paragraph style from an existing one. For example, the following line makes FEATURE an alias of the P2 style:
    

    !on paragraph 'FEATURE';; $style='P2'

    

    

    1.4.2. Using Mapping Tables
    

    SDF uses the parastyles filter to define the mapping between an SDF paragraph style and a target paragraph style. For example:
    

    !block parastyles
Name        To                      Attributes

# normal paragraphs
N           b0_Body

# headings
H1          h1_Heading
H2          h2_Heading
H3          h3_Heading
!endblock

    

    

    1.4.3. Creating New Target Paragraph Styles
    

    SDF makes it easy to define new target paragraph styles by inheriting configuration details from an existing style.
    

    See the look/simple/mif.sdn file in the SDF distribution for examples.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/guru/table.html010064400042570001753000000214000672242232000156160ustar00iancmtr00000400000236






SDF 2.001: SDF Guru Guide: table.pl - Table Processing Library




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    2.7. table.pl - Table Processing Library
    

    

    2.7.1. Purpose
    

    This library provides routines for reading, processing and writing TBL files.
    

    

    2.7.2. Interface
    

    require "table.pl";

@TABLE_MODEL_MODEL = ...

($success, @records) =
&TableFetch($file, $format);

@records =
&TableParse(@strings);

@records =
&TableParseUsingParams($ref_to_strings, %params);

&TableValidate(*table, *rules);

&TablePrint($strm, *table, %flags);

@strings =
&TableFormat(*table, %flags);

@fields =
&TableFields($format);

%values =
&TableRecSplit(*fields, $record);

$record =
&TableRecJoin(*fields, %values);

$string =
&TableRecFormat($format, %values);

@result =
&TableFilter(*table, $where, *var);

@result =
&TableDeleteFields(*table, @junk);

@result =
&TableSelectFields(*table, @new_fields);

@result =
&TableSort(*table, @by);

%index =
&TableIndex(*table, *duplicates, @by);

%values =
&TableLookup(*table, *index, @key_values);

@flds =
&TableFieldsCheck($format, $msg_type, %known);


    

    

    2.7.3. Description
    

    Tables are stored in arrays. The first element in the array is the input format specification. Remaining elements are data, one record per element.
    

    The routines are often used together as follows:
    

         # Read in the table (using the default format)
     ($ok, @table) = &TableFetch($table_name);

     # Process the data records
     $format = shift @table;
     @flds = &TableFields($format);
     for $rec (@table) {
             %value = &TableRecSplit(*flds, $rec);
             $value{'Age'}++;        # say ...
             $rec = &TableRecJoin(*flds, %value);
     }
     unshift(@table, $format);

     # Ouptut the new table (using the default flags)
     &TablePrint(STDOUT, *table);

    

    
Note: Multi-line fields are stored with a newline as the first character so be sure to allow for this when processing them.

    

    TABLE_MODEL_MODEL is the model for model files.
    

    TableFetch reads file as a table defined in TBL format. If the first data line of the file is not an input format specification, it can be specified using format. success is 1 if the file is opened successfully. records is an array of records, the first of which is the format specification.
    

    TableParse converts a list of strings into a table.
    

    TableParseUsingParams converts a list of strings into a table using the nominated parameters. No parameters are supported yet.
    

    TableValidate validates @table against @rules.
    

    TablePrint outputs @table to strm. The flags supported are outlined below.
    

    

    

Flag


Description


    

    

TBL format:


 


    

    

behead


column headings are not included at the top of the output


    

    

delimited


use delimited format - delimiter is the argument (default is tab)


    

    


    TableFormat formats @table using flags and returns a set of strings. See TablePrint for a list of the flags supported.
    

    TableFields returns the list of fields in format. Behaviour for custom formats is currently undefined.
    

    TableRecSplit converts a record into a set of name-value pairs using a set of fields (typically returned from TableFields).
    

    TableRecJoin converts a set of name-value pairs into a record using a set of fields (typically returned from TableFields).
    

    TableRecFormat formats a set of name-value pairs into a string using a format string. Behaviour for custom formats is currently undefined.
    

    TableFilter filters a table using an expression.
    

    TableDeleteFields deletes a list of fields from a table.
    

    TableSelectFields selects a list of fields from a table.
    

    TableSort sorts a table by one of more fields. The fields to use are passed in by. If no fields are specified, all fields are used in the order they appear in the table.
    

    TableIndex indexes a table by one of more fields. The fields to use are passed in by. If no fields are specified, all fields are used in the order they appear in the table. index is an associative array where:
    

      

    • the key is the value of the by fields

    • the data is the index in table of the matching record
    

    For multiple-field keys, values are separated by a null character (\000). The index of the first data record is 1 (the field specification record has an index of 0). @duplicates is the list of indices which do not appear in %index. If duplicate keys are found, the highest index is stored in %index for each key.
    

    TableLookup returns the name-value pairs for a given key. @table is the data table. %index is an index created using TableIndex. An empty associative array is returned if no matching record is found.
    

    TableFieldsCheck is a wrapper around TableFields which checks that the fields contains no duplicates. If known is defined, its keys are used to find unknown fields, if any. Any errors encountered are output as such using AppMsg. msg_type can be used to control the message type - error is the default.
    

    

    2.7.4. Limitations and future directions
    

    When validating field-names, the line number and context should be set to something meaningful. To achieve this, the line number of the format string in the file (if it's in the file, that is!) needs to be saved as part of the table.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



ta line of the file is not an input format specification, it can be specified using format. success is 1 if the file is opened successfully. records is an array of records, the first of which is the format specification.
    

    






SDF 2.001: SDF Guru Guide: Creating New Macros




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    1.2. Creating New Macros
    

    

    1.2.1. Using Event Processing
    

    SDF's event processing feature makes it easy to create a new macro from an existing one. For example, the following line makes image an alias for the import macro:
    

    !on macro 'image';; $name='import'

    

    The new macro can then be used as follows:
    

    !image 'mylogo'

    

    

    1.2.2. Using !macro and !endmacro
    

    The macro and endmacro macros are useful for creating simple macros. For example, if you have a block of text which is regularly repeated, you can make it a macro like this:
    

    !macro RealSoonNow
Note: This feature will be implemented real soon now.
The documentation below is the proposed design.
Any feedback on the design should be forwarded to
{{EMAIL:bill}} as soon as possible.
!endmacro

    

    See the stdlib/macros.sdm file within the SDF distribution for more examples of macro definitions.
    

    

    1.2.3. Using Perl
    

    For complicated macros including those requiring arguments, Perl subroutines can be used to implement the logic and build the SDF text to be inserted, if any.
    

    An SDF macro called xxx is mapped to a Perl subroutine called xxx_Macro within the SDF_USER package. The subroutine has the following interface:
    

           @text = xxx_Macro(%arg);

    

    where:
    

      

    • @text is the SDF to be inserted when this macro is called

    • %arg is the set of arguments (name-value pairs).
    

    For example, a Perl implementation of the RealSoonNow macro is:
    

    !block script
sub RealSoonNow_Macro {
    local(%arg) = @_;
    local(@text);

    @text = (
      'Note: This feature will be implemented real soon now.',
      'The documentation below is the proposed design.',
      'Any feedback on the design should be forwarded to',
      '{{EMAIL:bill}} as soon as possible.');
    return @text;
}
!endblock

    

    
Note: The script filter makes it easy to embed Perl code within an SDF document. (The code is executed within the SDF_USER package.)

    

    The perllib/sdf/macros.pl file within the SDF distribution contains lots of examples of macros implemented as Perl subroutines.
    

    

    1.2.4. Adding Arguments
    

    If a macro is implemented as a Perl subroutine, arguments can be declared in a Perl array called _xxx_MacroArgs. The array is a table in TBL format which contains the following fields:
    

    

    

Field


Description


    

    

Name


The argument name


    

    

Type


The argument type


    

    

Default


The default value, if any


    

    

Rule


The argument validation rule, if any


    

    


    For example, the RealSoonNow macro can be generalised so that the person to contact is an optional argument.
    

    !block script
@_RealSoonNow_MacroArgs = (
    'Name       Type        Default     Rule',
    'contact    string      bill',
);
sub RealSoonNow_Macro {
    local(%arg) = @_;
    local(@text);

    @text = (
      'Note: This feature will be implemented real soon now.',
      'The documentation below is the proposed design.',
      'Any feedback on the design should be forwarded to',
      '{{EMAIL:' . $arg{'contact'} . '}} as soon as possible.');
    return @text;
}
!endblock

    

    

    1.2.5. Argument Types
    

    The supported set of argument types are:
    

    

    

Type


Description


    

    

Common:


 


    

    

string


a string


    

    

integer


an integer


    

    

boolean


either 1 or 0


    

    

Special:


 


    

    

symbol


a symbolic name


    

    

filter


a filter name


    

    

rest


the rest of the arguments


    

    

eventid


an event tag


    

    

condition


a logical expression


    

    


    The special types are needed for some of SDF's built-in macros including define, include, on and if - they are rarely needed for normal macros.
    

    

    1.2.6. Default Values
    

    For default values within argument tables:
    

      

    • the empty string means there is no default

    • the symbol _NULL_ means the default is the empty string.
    

    For example, the arguments for the include macros are declared as shown below:
    

    @_include_MacroArgs = (
    'Name       Type        Default     Rule',
    'filename   string',
    'filter     filter      sdf',
    'params     rest        _NULL_',
);

    

    

    1.2.7. Rules
    

    If you wish, arguments can be validated using a rule. Rules are either:
    


    

    1.2.8. Patterns
    

    A pattern is a Perl regular expression which the argument value is matched against. Patterns are enclosed in angle brackets to differentiate them from normal Perl expressions. Typical patterns are given in the table below.
    

    

    

Pattern


Explanation


    

    

<\w+>


one or more characters in A-Z, a-z, 0-9 and '_'


    

    

<\d{4}>


a 4 digit number


    

    

<on|off>


a string which is either "on" or "off"


    

    

<XMIT-.*>


a string which begins with "XMIT-"


    

    


    

    1.2.9. General Perl Expressions
    

    More complex rules are required when:
    

      

    • the regular expression does not apply to the whole value

    • the regular expression is case-insensitive.
    

    In these cases, a general Perl expression can be used as the rule. Within the expression, $_ is the value of the argument. Examples are:
    

    

    

Expression


Explanation


    

    

/\d/


a digit exists somewhere in the string


    

    

/^(on|off)$/i


value is either "on" or "off" (case insensitive)


    

    


    
Note: A pattern is simply a short-hand notation for the general Perl expression below:
    

            /^(pattern)$/

    

    Pattern notation is provided as it makes rules easier to read and write. (Pattern-style validation typically covers 80% or more of validation rules so improving the readability of patterns has a large impact on the overall readability.)
    

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



s Perl subroutines.
    

    

    1.2.4. Adding Arguments
    

    If a macro is implemented as a Perl subroutine, arguments can be declared in a Perl array called _xxx_MacroArgs. The array is a table in TBL format which contains the following fields:
    
SDF 2.001: SDF Guru Guide: Creating New Looks and Document Styles
    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    1.7. Creating New Looks and Document Styles
    

    

    1.7.1. Libraries and Modules
    

    SDF implements looks and document styles as follows:
    

      

    1. Each look is actually a library (within the look directory).

    2. Each document style is actually a module (with an sds extension).
    

    As a result, looks and document styles have all the flexibility and features of normal libraries and modules.
    

    

    1.7.2. Creating a New Look
    

    The easiest way to create a new look is to inherit details from an existing look. Typically, this involves 3 steps:
    

      

    1. Creating a library directory and module.

    2. Overriding the pages module.

    3. Overriding tuning modules.
    

    For example, the infomap look inherits most of its configuration details from the simple look.
    

    

    1.7.3. Creating a library directory and module
    

    Each library needs its own directory and a main module within it. The look/infomap/infomap.sdm file is simply:
    

    # To remove the header/footer borders, uncomment the line below
#!default OPT_BORDERS 0

# Inherit the simple look
!inherit "look/simple"

    

    

    1.7.4. Overriding the pages module
    

    If the page layout is different, you will also need to override the pages.sdm module. For example, the look/infomap/pages.sdm file is:
    

    # Inherit what we can from the simple look
!use "look/simple/pages"

# Adjust the header/footer size and positioning
!define PAGE_FIRST_FOOTER_HEIGHT  '0.50in'
!define PAGE_FIRST_FOOTER_GAP     '0.25in'
!define PAGE_RIGHT_HEADER_HEIGHT  '0.50in'
!define PAGE_RIGHT_HEADER_GAP     '0.25in'
!define PAGE_RIGHT_FOOTER_HEIGHT  '0.50in'
!define PAGE_RIGHT_FOOTER_GAP     '0.25in'

# Adjust the sidehead size
!define OPT_SIDEHEAD_WIDTH "90pt"
!define OPT_SIDEHEAD_GAP   "10pt"

    

    

    1.7.5. Overriding tuning modules
    

    Each look can define a tuning module for each target format which supports looks. As tuning modules are simple modules named with an sdn extension, new tuning modules can easily reuse the configuration details in an existing tuning module.
    

    See the look/infomap/mif.sdn file for an example.
    

    

    1.7.6. Creating a New Document Style
    

    To create a new document style, simply create a module file of the required name with an sds extension in the appropriate look library directory.
    

    For example, to create a new document style called article which is available in all looks, create a module file called article.sds in the look/simple directory.
    

    See the look/simple/*.sds files in the SDF distribution for examples.
    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    
sdf-2.001/doc/guru/ex_filt.html010064400042570001753000000141630672242215000161720ustar00iancmtr00000400000236SDF 2.001: SDF Guru Guide: Creating New Filters
    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    1.3. Creating New Filters
    

    

    1.3.1. Using Event Processing
    

    SDF's event processing feature makes it easy to create a new filter from an existing one. For example, the following lines make grid a variation of the table filter:
    

    !on filter 'grid';; \
    $name='table'; $params.="; style='grid'"

    

    

    1.3.2. Using Perl
    

    Perl subroutines can be used to implement filter logic. An SDF filter called xxx is mapped to a Perl subroutine called xxx_Filter within the SDF_USER package. The subroutine has the following interface:
    

           xxx_Filter(*text, %param);

    

    where:
    

      

    • @text is the text (original in and result out)

    • %param is the set of parameters (name-value pairs).
    

    For example, the Perl implementation of the appendix filter is:
    

    sub appendix_Filter {
    local(*text, %param) = @_;

    # change headings
    unshift(@text, '!on paragraph \'H\d\'; __appendix; $style =~ s/H/A/');
    push   (@text, '!off paragraph __appendix');
}

    

    The perllib/sdf/filters.pl file within the SDF distribution contains lots of examples of filters implemented as Perl subroutines.
    

    

    1.3.3. Adding Parameters
    

    Parameters can be declared in a Perl array called _xxx_FilterParams. The array is a table in TBL format which contains the following fields:
    

    




























    

    

Field


Description


    

    

Name


The parameter name


    

    

Type


The parameter type


    

    

Rule


The parameter validation rule, if any


    

    


    Parameter types and rules follow the same conventions as macro argument types and rules. Refer to Creating New Macros for details.
    

    For example, the parameters for the example filter are declared like this:
    

    @_example_FilterParams = (
    'Name       Type        Rule',
    'skipheader boolean',
    'lang       string',
    'wide       boolean',
    'listitem   integer',
    'pure       boolean',
);

    

    

    1.3.4. Arbitary Parameters
    

    Occasionally, it is useful to support arbitary parameters. To do this, specify ('ANY') as the value of the parameter table. For example, the sdf filter can be used to apply an arbitary set of attributes to a block of text. Its parameter table is:
    

    @_sdf_FilterParams = ('ANY');

    

    

    1.3.5. Data Models
    

    If the text is a table, the filter typically has a data model (i.e. validation table) called xxx_FilterModel. To speed up processing, model validation is only done in verbose mode. For example, the define filter is defined as follows:
    

    # define - variable definitions
@_define_FilterParams = (
    'Name       Type        Rule',
    'family     string      <\w+>',
    'export     boolean',
);
@_define_FilterModel = (
    'Field      Category    Rule',
    'Name       key         <\w+>',
    'Value      optional',
);
sub define_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($family, $export, $name);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_define_FilterModel) if $validate;

    # Process the data
    $family = $param{'family'};
    $family .= '_' if $family ne '';
    $export = $param{'export'};
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);
        $name = $family . $values{'Name'};
        push(@text, "!define $name $values{'Value'}");
        push(@text, "!export $name") if $export;
    }
}

    

    

    1.3.6. Dynamic Filter Loading
    

    Most filters are either built-in or defined in a library or module which is loaded at the top of a document. The script filter makes it easy to embed Perl code within an SDF file, and library and module files are simply normal SDF files.
    

    However, if SDF is asked to apply a filter which it does not know about, it looks for a file called filter_name.sdp and dynamically loads the filter from that file if it can. This feature is useful for complex filters which are rarely used.
    

    See the stdlib/module.sdp file for an example.
    


    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/guru/misc.html010064400042570001753000000134570672242227400155070ustar00iancmtr00000400000236






SDF 2.001: SDF Guru Guide: misc.pl - Miscellaneous Library




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    2.5. misc.pl - Miscellaneous Library
    

    

    2.5.1. Purpose
    

    This library provides miscellaneous routines.
    

    

    2.5.2. Interface
    

    require "misc.pl";

%misc_date_strings = ...

$result =
&MiscCheckRule($_, $rule, $type);

($action, $what) =
&MiscDoAction($action, $what);

$newtext =
&MiscTextWrap($text, $wrap, $prefix, $suffix, $keep_spaces);

$result =
&MiscDateFormat($fmt, $time, $msg_type);

$mixed =
&MiscUpperToMixed($upper);

$upper =
&MiscMixedToUpper($mixed);


    

    

    2.5.3. Description
    

    misc_date_strings contains the string lists used by MiscDateFormat indexed by the symbols (e.g. 'month') used by that routine.
    

    MiscCheckRule checks a rule for a value $_. If an execution error is detected, an appropriate error is output. The result of the code executed is returned as result. If rule is an empty string, type is used to lookup a default rule for that type, if any. If rule is still an empty string, 1 is returned.
    

    MiscDoAction executes a block of Perl code (action). If an execution error is detected, an appropriate error is output using what to name the block of code that failed. The result of the code executed is returned as result. action is only executed if it exists. If it does not, 1 is returned.
    

    MiscTextWrap wraps a text string at a margin given by wrap. prefix is the string to begin each wrapped line. suffix is the string to terminate each wrapped line.
    

    
Note: 
    

      

    • prefix is not added to the first line

    • suffix is not added to the last line

    • wrap includes prefix but excludes suffix
    

    

    MiscDateFormat formats a date-time value. fmt is a string containing the symbols below.
    

    

    

Symbol


Description


Example


    

    

$day


day number in month


6 or 22


    

    

$day0


day number in month zero-padded


06 or 22


    

    

$month


month name


January


    

    

$smonth


abbreviated month name


Jan


    

    

$monthnum


month number (1..12)


6 or 12


    

    

$monthnum0


month number zero-padded (01..12)


06 or 12


    

    

$year


year


1995


    

    

$syear


abbreviated year


95


    

    

$weekday


weekday name


Monday


    

    

$sweekday


abbreviated weekday name


Mon


    

    

$hour


hour (1..24)


6 or 14


    

    

$hour0


hour zero-padded (01..24)


06 or 14


    

    

$shour


hour (1..12)


6 or 12


    

    

$shour0


hour zero-padded (01..12)


06 or 12


    

    

$ampm


am or pm


am


    

    

$AMPM


AM or PM


PM


    

    

$minute


minute (0..59)


0 or 42


    

    

$minute0


minute zero-padded (00..59)


00 or 42


    

    

$second


second (0..59)


0 or 42


    

    

$second0


second zero-padded (00..59)


00 or 42


    

    


    time is a number of seconds since January 1, 1970. msg_type is the type of message, if any, to output when a bad format is found.
    

    MiscUpperToMixed converts a name in an uppercase form (e.g. MY_STRING) to a mixed-case form (e.g. MyString).
    

    MiscMixedToUpper converts a name in a mixed-case form (e.g. MyString) to an uppercase form (e.g. MY_STRING).
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



he symbols (e.g. 'month') used by that routine.
    

    MiscCheckRule checks a rule for a value $_. If an execution error is detected, an apprsdf-2.001/doc/guru/in_ex.html010064400042570001753000000053320672242217200156440ustar00iancmtr00000400000236






SDF 2.001: SDF Guru Guide: Creating a New Format Driver




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    1. Extending SDF
    

    

    1.1. Overview
    

    1.1.1. Logical Documents
    

    A central part of SDF's philosophy is that documents should be specified in a logical manner. In order to make this possible, SDF has been designed to be easy to extend.
    

    1.1.2. Documenting Extensions
    

    If you do extend SDF and other people need to use your extensions, please try to document things. Within the SDF distribution, the SDF document catalog (doc/catalog.html) provides a link for local documentation (doc/local/) which you may wish to use.
    

    1.1.3. Packaging Extensions
    

    If your extensions would be useful to a wider audience, please consider packaging them into an SDF library or module, documenting the features and notifying people on the SDF mailing lists.
    

    1.1.4. What Can I Create?
    

    Almost every part of SDF is extensible. As a rule, the most commonly created extensions are new macros and new filters. However, creating new paragraph, phrase and table styles is also quite simple.
    

    Details on how to create these things and other SDF entities are given below.
    

    Creating New Macros
    

    Creating New Filters
    

    Creating New Paragraph Styles
    

    Creating New Phrase Styles
    

    Creating New Table Styles
    

    Creating New Looks and Document Styles
    

    Creating a New Format Driver
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/guru/ex_look.sdf010064400042570001753000000053650647021666600160310ustar00iancmtr00000400000236H1: Creating New Looks and Document Styles

H2: Libraries and Modules

SDF implements looks and document styles as follows:

^ Each look is actually a library (within the {{look}} directory).
+ Each document style is actually a module (with an {{sds}} extension).

As a result, looks and document styles have all the flexibility
and features of normal libraries and modules.

H2: Creating a New Look

The easiest way to create a new look is to inherit details from
an existing look. Typically, this involves 3 steps:

!block sections
^ Creating a library directory and module.
+ Overriding the pages module.
+ Overriding tuning modules.
!endblock

For example, the {{infomap}} look inherits
most of its configuration details from the {{simple}} look.

H2: Creating a library directory and module

Each library needs its own directory and a {{main module}} within it.
The {{FILE:look/infomap/infomap.sdm}} file is simply:

!block example; pure
# To remove the header/footer borders, uncomment the line below
#!default OPT_BORDERS 0

# Inherit the simple look
!inherit "look/simple"
!endblock

H2: Overriding the pages module

If the page layout is different, you will also need to override
the {{pages.sdm}} module. For example, the
{{FILE:look/infomap/pages.sdm}} file is:

!block example; pure
# Inherit what we can from the simple look
!use "look/simple/pages"

# Adjust the header/footer size and positioning
!define PAGE_FIRST_FOOTER_HEIGHT  '0.50in'
!define PAGE_FIRST_FOOTER_GAP     '0.25in'
!define PAGE_RIGHT_HEADER_HEIGHT  '0.50in'
!define PAGE_RIGHT_HEADER_GAP     '0.25in'
!define PAGE_RIGHT_FOOTER_HEIGHT  '0.50in'
!define PAGE_RIGHT_FOOTER_GAP     '0.25in'

# Adjust the sidehead size
!define OPT_SIDEHEAD_WIDTH "90pt"
!define OPT_SIDEHEAD_GAP   "10pt"
!endblock

H2: Overriding tuning modules

Each look can define a tuning module for each target format which
supports looks. As tuning modules are simple modules named with an
{{sdn}} extension, new tuning modules can easily reuse the configuration
details in an existing tuning module.

See the {{FILE:look/infomap/mif.sdn}} file for an example.


H2: Creating a New Document Style

To create a new document style, simply create a module file
of the required name with an {{sds}} extension in the appropriate
look library directory.

For example, to create a new document style called {{article}}
which is available in all looks, create a module file called
{{article.sds}} in the {{look/simple}} directory.

#Some of the variables you may wish to set in a document style
#module are:
#
#!block table
#Variable        Description
#OPT_BORDERS     high level header/footer border control
#OPT_HEADINGS    high level header/footer line count control
#!endblock

See the {{FILE:look/simple/*.sds}} files in the SDF distribution
for examples.
sdf-2.001/doc/guru/ex_tbl.html010064400042570001753000000041210672242216000160070ustar00iancmtr00000400000236






SDF 2.001: SDF Guru Guide: Creating New Table Styles




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    1.6. Creating New Table Styles
    

    

    1.6.1. Using Event Processing
    

    SDF's event processing feature makes it easy to create a new table style from an existing one. For example, the following line makes schedule a variation of the shade style:
    

    !on table 'schedule';; $style='shade'; $param{"wide"} = 1

    

    

    1.6.2. Using Mapping Tables
    

    SDF uses the tablestyles filter to define the mapping between an SDF table style and a target table style. For example:
    

    !block tablestyles
Name    To
columns Columns
rows    Rows
grid    Grid
plain   Plain
box     Box
shade   Shade
!endblock

    

    

    1.6.3. Creating New Target Phrase Styles
    

    SDF makes it easy to define new target table styles by inheriting configuration details from an existing style.
    

    See the look/simple/mif.sdn file in the SDF distribution for examples.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/guru/in_ex.sdf010064400042570001753000000021610633574157400154630ustar00iancmtr00000400000236H1: Extending SDF

H2: Overview

H3: Logical Documents

A central part of SDF's philosophy is that documents should be
specified in a logical manner. In order to make this possible,
SDF has been designed to be easy to extend.

H3: Documenting Extensions

If you do extend SDF and other people need to use your extensions,
please try to document things. Within the SDF distribution, the
SDF document catalog (doc/catalog.html) provides a link for
local documentation (doc/local/) which you may wish to use.

H3: Packaging Extensions

If your extensions would be useful to a wider audience, please
consider packaging them into an SDF library or module, documenting
the features and notifying people on the SDF mailing lists.

H3: What Can I Create?

Almost every part of SDF is extensible. As a rule, the most commonly
created extensions are new macros and new filters. However, creating
new paragraph, phrase and table styles is also quite simple.

Details on how to create these things and other SDF entities are
given below.

!block topics
Topic
ex_mac
ex_filt
ex_para
ex_phras
ex_tbl
ex_look
ex_dvrs
#ex_attr
#ex_lang
#ex_rpt
!endblocksdf-2.001/doc/guru/ex_dvrs.sdf010064400042570001753000000044130635011175600160230ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Creating a New Format Driver

H2: Overview

The steps are:

^ Pick an existing driver to copy.
+ Copy it.
+ Make the necessary changes.
+ Update the {{FILE:sdf.ini}} file in the bin directory.

Simple, really! :-)

Good drivers to start from are {{FILE:totxt.pl}},
{{FILE:tohtml.pl}} and {{FILE:tomif.pl}}.
The drivers can be found in the {{perllib/sdf}} directory of
the SDF distribution.

H2: Required Skills

The following skills are required to write a format driver:

^ Good knowledge of the target format.
+ Perl programming.

It also helps if one has a look at {{SECT:SDFAPI}} before beginning.


H2: Driver Architecture Overview

An SDF driver interacts with the core SDF system as follows:

^ The {{FILE:sdf.ini}} file configures SDF so that the relevant driver
  is loaded and called, when necessary.

+ Each driver is implemented by a single subroutine which is
  responsible for initialising itself, processing the input,
  finalising things and returning the output.

+ The input should be processed by:
  ^^ calling the {{SdfNextPara}} routine within a while loop
  ++ for each paragraph, calling the {{SdfNextSection}} routine
     within a while loop.


H2: Some General Comments

If you are considering writing a driver, it might be a good idea
to let people on the SDF mailing lists know. If you're lucky,
someone else might have started a driver for the same output
format or be willing to assist you develop a new one.
Likewise, if you're having problems, send email to
{{EMAIL:sdf-bugs@mincom.com}}. Chances are, an SDF guru will
try to help.

As a rule, it is a good idea to use configuration files to
define the mappings from SDF entities to target entities.
In this way, people can override the default mappings
without changing your driver.

Depending on your skills, the amount of changes you need to make,
and your knowledge of SDF, the driver can take anything from 10
minutes to 10 weeks. Good luck. :-)
sdf-2.001/doc/guru/gg_sdf.html010064400042570001753000000044240672242232100157700ustar00iancmtr00000400000236






SDF 2.001: SDF Guru Guide




    

    

    Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    SDF Guru Guide
    

    MTR-SDF-0005.001 (Final)
    

    Ian Clatworthy
    

    25 May 1999
    

    

    

    

    

    Table of Contents
    


    

    

    

    Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/guru/ex_mac.sdf010064400042570001753000000130000647526744000156070ustar00iancmtr00000400000236H1: Creating New Macros

H2: Using Event Processing

SDF's event processing feature makes it easy to create
a new macro from an existing one. For example, the
following line makes {{image}} an alias for the
{{MAC:import}} macro:

E:!on macro 'image';; $name='import'

The new macro can then be used as follows:

E:!image 'mylogo'

H2: Using !macro and !endmacro

The {{MAC:macro}} and {{MAC:endmacro}} macros are useful for
creating simple macros. For example, if you have a block of text
which is regularly repeated, you can make it a macro like this:

!block example; pure
!macro RealSoonNow
Note: This feature will be implemented real soon now.
The documentation below is the proposed design.
Any feedback on the design should be forwarded to
{{EMAIL:bill}} as soon as possible.
!endmacro
!endblock

See the {{FILE:stdlib/macros.sdm}} file within the SDF distribution
for more examples of macro definitions.

H2: Using Perl

For complicated macros including those requiring arguments,
Perl subroutines can be used to implement the logic and
build the SDF text to be inserted, if any.

An SDF macro called {{xxx}} is mapped to a Perl subroutine
called {{xxx}}_Macro within the SDF_USER package.
The subroutine has the following interface:

E:       @text = xxx_Macro(%arg);

:where:

* @text is the SDF to be inserted when this macro is called
* %arg is the set of arguments (name-value pairs).

For example, a Perl implementation of the RealSoonNow macro is:

!block example; pure
!block script
sub RealSoonNow_Macro {
    local(%arg) = @_;
    local(@text);

    @text = (
      'Note: This feature will be implemented real soon now.',
      'The documentation below is the proposed design.',
      'Any feedback on the design should be forwarded to',
      '{{EMAIL:bill}} as soon as possible.');
    return @text;
}
!endblock
!endblock

Note: The {{FILT:script}} filter makes it easy to embed
Perl code within an SDF document. (The code is executed within
the SDF_USER package.)

The {{FILE:perllib/sdf/macros.pl}} file within the SDF distribution
contains lots of examples of macros implemented as Perl subroutines.

H2: Adding Arguments

If a macro is implemented as a Perl subroutine, arguments can
be declared in a Perl array called _{{xxx}}_MacroArgs.
The array is a table in {{FMT:TBL}} format which contains
the following fields:

!block table
Field   Description
Name    The argument name
Type    The argument type
Default The default value, if any
Rule    The argument validation rule, if any
!endblock

For example, the RealSoonNow macro can be generalised so that
the person to contact is an optional argument.

!block example; pure
!block script
@_RealSoonNow_MacroArgs = (
    'Name       Type        Default     Rule',
    'contact    string      bill',
);
sub RealSoonNow_Macro {
    local(%arg) = @_;
    local(@text);

    @text = (
      'Note: This feature will be implemented real soon now.',
      'The documentation below is the proposed design.',
      'Any feedback on the design should be forwarded to',
      '{{EMAIL:' . $arg{'contact'} . '}} as soon as possible.');
    return @text;
}
!endblock
!endblock

H2: Argument Types

The supported set of argument types are:

!block table; groups
Type            Description
Common:
string          a string
integer         an integer
boolean         either 1 or 0
Special:
symbol          a symbolic name
filter          a filter name
rest            the rest of the arguments
eventid         an event tag
condition       a logical expression
!endblock

The special types are needed for some of SDF's built-in
macros including {{MAC:define}}, {{MAC:include}}, {{MAC:on}}
and {{MAC:if}} - they are rarely needed for normal macros.

H2: Default Values

For default values within argument tables:

* the empty string means there is no default
* the symbol _NULL_ means the default is the empty string.

For example, the arguments for the {{MAC:include}} macros
are declared as shown below:

!block example
@_include_MacroArgs = (
    'Name       Type        Default     Rule',
    'filename   string',
    'filter     filter      sdf',
    'params     rest        _NULL_',
);
!endblock

H2: Rules

If you wish, arguments can be validated using a rule.
Rules are either:

!block sections
* Patterns
* General Perl Expressions.
!endblock

H2: Patterns

A {{pattern}} is a Perl regular expression which the argument
value is matched against. Patterns are enclosed in angle brackets
to differentiate them from normal Perl expressions.
Typical patterns are given in the table below.

!block table
Pattern     Explanation
<\w+>       one or more characters in A-Z, a-z, 0-9 and '_'
<\d{4}>     a 4 digit number
    a string which is either "on" or "off"
   a string which begins with "XMIT-"
!endblock

H2: General Perl Expressions

More complex rules are required when:

* the regular expression does not apply to the whole value
* the regular expression is case-insensitive.

In these cases, a general Perl expression can be used as the rule.
Within the expression, $_ is the value of the argument.
Examples are:

!block table
Expression      Explanation
/\d/            a digit exists somewhere in the string
/^(on|off)$/i   value is either "on" or "off" (case insensitive)
!endblock

!block note
A pattern is simply a short-hand notation for the general
Perl expression below:

E:	/^(pattern)$/

Pattern notation is provided as it makes rules easier
to read and write. (Pattern-style validation typically covers
80% or more of validation rules so improving the readability of
patterns has a large impact on the overall readability.)
!endblocksdf-2.001/doc/guru/index.html010044400042570001753000000044240672242232100156440ustar00iancmtr00000400000236






SDF 2.001: SDF Guru Guide




    

    

    Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    SDF Guru Guide
    

    MTR-SDF-0005.001 (Final)
    

    Ian Clatworthy
    

    25 May 1999
    

    

    

    

    

    Table of Contents
    


    

    

    

    Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/guru/ex_phras.sdf010064400042570001753000000016400647021666600161720ustar00iancmtr00000400000236H1: Creating New Phrase Styles

H2: Using Event Processing

SDF's event processing feature makes it easy to create
a new phrase style from an existing one. For example, the
following line makes {{LIB}} an alias of the {{S}} style:

E:!on phrase 'LIB';; $style='S'


H2: Using Mapping Tables

SDF uses the {{phrasestyles}} filter to define the mapping between
an SDF phrase style and a target phrase style.
For example:

!block example; pure
!block phrasestyles
Name    To

# Emphasis
A       Default
B       Bold
I       Italic
N       Normal
U       Underline
E       Filename
JUMP    Jump
1       =I
2       =B
3       =U
S       =2
SUB     Subscript
SUP     Superscript
!endblock
!endblock


H2: Creating New Target Phrase Styles

SDF makes it easy to define new target phrase styles
by inheriting configuration details from an existing style.

See the {{FILE:look/simple/mif.sdn}} file in the SDF distribution
for examples.
e:

!block example; pure
!block phrasestyles
Name    To

# Emphasis
A       Default
B       Boldsdf-2.001/doc/guru/ex_filt.sdf010064400042570001753000000077170645302371200160130ustar00iancmtr00000400000236H1: Creating New Filters

H2: Using Event Processing

SDF's event processing feature makes it easy to create
a new filter from an existing one. For example, the
following lines make {{grid}} a variation of the
{{FILT:table}} filter:

E:!on filter 'grid';; \
E:    $name='table'; $params.="; style='grid'"

H2: Using Perl

Perl subroutines can be used to implement filter logic.
An SDF filter called {{xxx}} is mapped to a Perl subroutine
called {{xxx}}_Filter within the SDF_USER package.
The subroutine has the following interface:

E:       xxx_Filter(*text, %param);

:where:

* {{@text}} is the text (original in and result out)
* {{%param}} is the set of parameters (name-value pairs).

For example, the Perl implementation of the {{FILT:appendix}} filter is:

!block Perl
sub appendix_Filter {
    local(*text, %param) = @_;

    # change headings
    unshift(@text, '!on paragraph \'H\d\'; __appendix; $style =~ s/H/A/');
    push   (@text, '!off paragraph __appendix');
}
!endblock

The {{FILE:perllib/sdf/filters.pl}} file within the SDF distribution
contains lots of examples of filters implemented as Perl subroutines.


H2: Adding Parameters

Parameters can be declared in a Perl array called _{{xxx}}_FilterParams.
The array is a table in {{FMT:TBL}} format which contains
the following fields:

!block table
Field   Description
Name    The parameter name
Type    The parameter type
Rule    The parameter validation rule, if any
!endblock

Parameter types and rules follow the same conventions
as macro argument types and rules. Refer to
{{SECT:Creating New Macros}} for details.

For example, the parameters for the {{FILT:example}} filter are declared
like this:

!block Perl
@_example_FilterParams = (
    'Name       Type        Rule',
    'skipheader boolean',
    'lang       string',
    'wide       boolean',
    'listitem   integer',
    'pure       boolean',
);
!endblock


H2: Arbitary Parameters

Occasionally, it is useful to support arbitary parameters.
To do this, specify ('ANY') as the value of the parameter table.
For example, the {{FILT:sdf}} filter can be used to apply an
arbitary set of attributes to a block of text. Its parameter table is:

!block Perl
@_sdf_FilterParams = ('ANY');
!endblock


H2: Data Models

If the text is a table, the filter typically has a data model
(i.e. validation table) called {{xxx_FilterModel}}.
To speed up processing, model validation is only done
in verbose mode. For example, the {{FILT:define}} filter
is defined as follows:

!block Perl
# define - variable definitions
@_define_FilterParams = (
    'Name       Type        Rule',
    'family     string      <\w+>',
    'export     boolean',
);
@_define_FilterModel = (
    'Field      Category    Rule',
    'Name       key         <\w+>',
    'Value      optional',
);
sub define_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($family, $export, $name);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_define_FilterModel) if $validate;

    # Process the data
    $family = $param{'family'};
    $family .= '_' if $family ne '';
    $export = $param{'export'};
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);
        $name = $family . $values{'Name'};
        push(@text, "!define $name $values{'Value'}");
        push(@text, "!export $name") if $export;
    }
}
!endblock


H2: Dynamic Filter Loading

Most filters are either built-in or defined in a library or
module which is loaded at the top of a document. The {{FILT:script}}
filter makes it easy to embed Perl code within an SDF file,
and library and module files are simply normal SDF files.

However, if SDF is asked to apply a filter which it does not know about,
it looks for a file called {{filter_name}}.sdp and dynamically
loads the filter from that file if it can. This feature is useful
for complex filters which are rarely used.

See the {{FILE:stdlib/module.sdp}} file for an example.sdf-2.001/doc/guru/ex_dvrs.html010064400042570001753000000064470672242217000162220ustar00iancmtr00000400000236






SDF 2.001: SDF Guru Guide: Creating a New Format Driver




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    1.8. Creating a New Format Driver
    

    

    1.8.1. Overview
    

    The steps are:
    

      

    1. Pick an existing driver to copy.

    2. Copy it.

    3. Make the necessary changes.

    4. Update the sdf.ini file in the bin directory.
    

    Simple, really! :-)
    

    Good drivers to start from are totxt.pl, tohtml.pl and tomif.pl. The drivers can be found in the perllib/sdf directory of the SDF distribution.
    

    

    1.8.2. Required Skills
    

    The following skills are required to write a format driver:
    

      

    1. Good knowledge of the target format.

    2. Perl programming.
    

    It also helps if one has a look at SDFAPI before beginning.
    

    

    1.8.3. Driver Architecture Overview
    

    An SDF driver interacts with the core SDF system as follows:
    

      

    1. The sdf.ini file configures SDF so that the relevant driver is loaded and called, when necessary.

    2. Each driver is implemented by a single subroutine which is responsible for initialising itself, processing the input, finalising things and returning the output.

    3. The input should be processed by:
        

      1. calling the SdfNextPara routine within a while loop

      2. for each paragraph, calling the SdfNextSection routine within a while loop.
    

    

    1.8.4. Some General Comments
    

    If you are considering writing a driver, it might be a good idea to let people on the SDF mailing lists know. If you're lucky, someone else might have started a driver for the same output format or be willing to assist you develop a new one. Likewise, if you're having problems, send email to sdf-bugs@mincom.com. Chances are, an SDF guru will try to help.
    

    As a rule, it is a good idea to use configuration files to define the mappings from SDF entities to target entities. In this way, people can override the default mappings without changing your driver.
    

    Depending on your skills, the amount of changes you need to make, and your knowledge of SDF, the driver can take anything from 10 minutes to 10 weeks. Good luck. :-)
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/guru/dict.html010064400042570001753000000051630672242224600154710ustar00iancmtr00000400000236






SDF 2.001: SDF Guru Guide: dict.pl - Dictionary Library




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    2.3. dict.pl - Dictionary Library
    

    

    2.3.1. Purpose
    

    This library provides support for reading and processing dictionaries stored in text files.
    

    

    2.3.2. Interface
    

    require "dict.pl";

@DICT_DFLT_REPORT = ...

@dict_rest = ...

$success =
&DictFetch($file, $begin, $delimiter, $end, $prefix);

$ok =
&DictPrint($strm, $level, $buffer_name, $bufref, @report);


    

    

    2.3.3. Description
    

    A dictionary is a collection of items where each item has:
    

      

    • a unique key

    • a description
    

    DICT_DFLT_REPORT is the default report for DictPrint. It:
    

      

    • outputs items in the order found, separated by blank lines

    • outputs each item as:
        

      • key on one line

      • description on the next
    

    dict_rest is the set of lines in the last file processed by DictFetch which are not in the dictionary.
    

    DictFetch inputs filename as a dictionary.
    

    DictPrint outputs a dictionary using report. If no report is specified, DICT_DFLT_REPORT is used.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/guru/gg_sdf.sdf010064400042570001753000000014160645302464200156030ustar00iancmtr00000400000236!init OPT_LOOK='infomap'; OPT_STYLE='manual'
# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

# Load the configuration
!define SDF_ROOT "../"
!inherit "sdf"

# Define variables
!define DOC_NAME    "SDF"
!define DOC_TYPE    "Guru Guide"
!define DOC_AUTHOR  "Ian Clatworthy"
!define DOC_TOC     2
!define DOC_IX

# Build the title page
!build_title

# Include the document components
!include "about.sdf"; about
!include "in_ex.sdf"
!include "in_api.sdf"
sdf-2.001/doc/guru/ex_phras.html010064400042570001753000000042320672242215500163520ustar00iancmtr00000400000236






SDF 2.001: SDF Guru Guide: Creating New Phrase Styles




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    1.5. Creating New Phrase Styles
    

    

    1.5.1. Using Event Processing
    

    SDF's event processing feature makes it easy to create a new phrase style from an existing one. For example, the following line makes LIB an alias of the S style:
    

    !on phrase 'LIB';; $style='S'

    

    

    1.5.2. Using Mapping Tables
    

    SDF uses the phrasestyles filter to define the mapping between an SDF phrase style and a target phrase style. For example:
    

    !block phrasestyles
Name    To

# Emphasis
A       Default
B       Bold
I       Italic
N       Normal
U       Underline
E       Filename
JUMP    Jump
1       =I
2       =B
3       =U
S       =2
SUB     Subscript
SUP     Superscript
!endblock

    

    

    1.5.3. Creating New Target Phrase Styles
    

    SDF makes it easy to define new target phrase styles by inheriting configuration details from an existing style.
    

    See the look/simple/mif.sdn file in the SDF distribution for examples.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/guru/about.sdf010064400042570001753000000017040633573527000154710ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: About this manual

H2: Purpose

This manual provides information on customising and extending [[SDF]] - a
documentation system for software developers.
Readers should be familiar with the following documents before
reading this one:

. {{DOC:The SDF Document Development System}}
. {{DOC:SDF User Guide}}.

H2: Scope

This manual contains information on:

* how to extend SDF with new entities (e.g. macros, filters, etc.)
* how to develop an [[SDF]] driver to support a new output format
* [[SDFAPI]] - the set of Perl libraries provided with SDF.

H2: Amendments

!SDF_AMENDMENTS
sdf-2.001/doc/guru/in_api.html010064400042570001753000000071060672242232100157760ustar00iancmtr00000400000236






SDF 2.001: SDF Guru Guide: table.pl - Table Processing Library




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    2. SDFAPI
    

    

    2.1. Overview
    

    The libraries provided with SDF are summarised below.
    

    

    

Name


Purpose


    

    

General:


 


    

    

parse.pl


general parsing and processing of SDF files


    

    

app.pl


application framework for all SDF scripts


    

    

name.pl


filename processing routines


    

    

table.pl


table processing routines (including read/write of TBL files)


    

    

dict.pl


dictionary processing routines


    

    

misc.pl


miscellaneous routines


    

    

Support:


 


    

    

subs.pl


general run-time support


    

    

macros.pl


built-in macros


    

    

filters.pl


built-in filters


    

    

specials.pl


built-in special phrase styles


    

    

Drivers:


 


    

    

toraw.pl


raw format driver


    

    

tomif.pl


MIF format driver


    

    

tohtml.pl


HTML format driver


    

    

totxt.pl


plain text format driver


    

    

topod.pl


POD format driver


    

    

toman.pl


man page format driver


    

    

API extraction:


 


    

    

apiperl.pl


routines for extracting API information from a Perl library


    

    


    Further details on the general libraries are given below.
    

    app.pl - Application Framework Library
    

    dict.pl - Dictionary Library
    

    name.pl - Name Processing Library
    

    misc.pl - Miscellaneous Library
    

    parse.pl - Simple Document Format Library
    

    table.pl - Table Processing Library
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/guru/ex_para.sdf010064400042570001753000000016200647021666600157760ustar00iancmtr00000400000236H1: Creating New Paragraph Styles

H2: Using Event Processing

SDF's event processing feature makes it easy to create
a new paragraph style from an existing one. For example, the
following line makes {{FEATURE}} an alias of the {{P2}} style:

E:!on paragraph 'FEATURE';; $style='P2'


H2: Using Mapping Tables

SDF uses the {{parastyles}} filter to define the mapping between
an SDF paragraph style and a target paragraph style.
For example:

!block example; pure
!block parastyles
Name        To                      Attributes

# normal paragraphs
N           b0_Body

# headings
H1          h1_Heading
H2          h2_Heading
H3          h3_Heading
!endblock
!endblock


H2: Creating New Target Paragraph Styles

SDF makes it easy to define new target paragraph styles
by inheriting configuration details from an existing style.

See the {{FILE:look/simple/mif.sdn}} file in the SDF distribution
for examples.
sdf-2.001/doc/release/004075500042570001753000000000000672243775100143235ustar00iancmtr00000400000236sdf-2.001/doc/release/rn_sdf.sdf010075500042570001753000000033320672210475400162670ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1999, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 24-May-99 ianc    2.001 release
# 06-Mar-98 ianc    2.001beta1 release
# 07-Oct-97 ianc    2.000 release
# 18-Jul-97 ianc    2.000beta12 release
# 08-Jul-97 ianc    2.000beta11 release
# 19-Jun-97 ianc    2.000beta10 release
# 03-Jun-97 ianc    2.000beta9a release
# 01-May-97 ianc    2.000beta9 release
# 08-Apr-97 ianc    2.000beta8a release
# 02-Apr-97 ianc    2.000beta8 release
# 19-Aug-96 ianc    2.000beta7c release
# 29-Aug-96 ianc    2.000beta7b release
# 13-Jun-96 ianc    2.000beta6c release
# 03-Jun-96 ianc    2.000beta6a release
# 23-May-96 ianc    2.000beta6 release
# 26-Apr-96 ianc    2.000beta5 release
# 23-Apr-96 ianc    2.000beta4c release
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

# Load the configuration
!define SDF_ROOT "../"
!inherit "sdf"

# Define variables
!define DOC_NAME    "SDF"
!define DOC_TYPE    "Release Notes"
!define DOC_AUTHOR  "Ian Clatworthy"
!define DOC_TOC     1

# Build the title page
!build_title

!include "2001.sdf"
!include "2001b1.sdf"
!include "2000.sdf"
!include "2000b12.sdf"
!include "2000b11.sdf"
!include "2000b10.sdf"
!include "2000b9a.sdf"
!include "2000b9.sdf"
!include "2000b8a.sdf"
!include "2000b8.sdf"
!include "2000b7c.sdf"
!include "2000b7b.sdf"
!include "2000b7a.sdf"
!include "2000b7.sdf"
!include "2000b6c.sdf"
!include "2000b6b.sdf"
!include "2000b6a.sdf"
!include "2000b6.sdf"
!include "2000b5.sdf"
!include "2000b4c.sdf"
!include "2000b4b.sdf"
sdf-2.001/doc/release/2000b6c.sdf010064400042570001753000000004650622022216600157600ustar00iancmtr00000400000236H1: 2.000beta6c

!subsections "Enhancements,Fixes,Incompatibilities"

H2: Enhancements

A {{FILE:template}} directory has been added. This contains
skeleton SDF files for different document types.

Prefilters now have their own subdirectory under {{FILE:lib}}.

H2: Fixes

None.

H2: Incompatibilities

None.
sdf-2.001/doc/release/2000b5.html010064400042570001753000000120470672242656200160200ustar00iancmtr00000400000236






SDF 2.001: SDF Release Notes: 2.000beta5




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    19. 2.000beta5
    

    Enhancements | General Fixes | HTML Fixes | HLP Fixes | Incompatibilities
    

    

    19.1. Enhancements
    

    19.1.1. Performance
    

    Performance is now 2-3 times faster for most documents. There is still some work to do here, but the performance is now "respectable" (rather than "disappointing").
    

    19.1.2. Perl 5
    

    This release has been tested with Perl 5.002 and is configured to use it, by default. However:
    

      

    • the odd "eval" buglet still (randomly?) appears when using Perl 5

    • the mif2rtf script has not been tested.
    

    If you wish to use Perl 4 instead, you will need to change the top line of the scripts in the bin directory after installing SDF.
    

    19.1.3. Newsletters
    

    There is now a new style called newsletter.
    

    The title filter now supports a toc parameter for specifying a table of contents. For example:
    

    !block title; toc=$var{'OPT_TARGET'} eq 'html' ? 2 : 0
Name    Value
Title   My Newsletter
Editor  Me
!endblock

    

    This produces a title block for a newsletter and only gives it a table of contents when the target is HTML.
    

    19.1.4. Pre-Filtering
    

    sdfcvt's -p option prefilters the input file for each argument. The (optional) parameter is the filter to use. For example:
    

            sdfcvt -ptable mytable.tbl

    

    is equivalent to executing sdfcvt on a file which only contains:
    

            !include "mytable.pl"; table

    

    File extensions can be mapped to filters in sdfcvt.ini. For example, sdfcvt.ini now contains the following:
    

    [PreFilters]
Name    Aliases     Module
table   tbl
module  sdm,sde     frmodule

    

    As tbl is mapped to table, creating nicely formatted tables is now quite easy. For example:
    

            sdfcvt -p -aformat='15,75,10' mytable.tbl

    

    (The -a option can be used to specify prefilter parameters.)
    

    For a given prefilter, a module can be configured in sdfcvt.ini to be loaded before the filter is applied. As a result, it's possible to do really clever things via autoloaded filters. Examples include:
    

      

    • automatically documenting SDF modules

    • converting other formats to SDF on the fly.
    

    For example, the following command will build the reference documentation for a SDF module in HTML (real soon now):
    

     sdfcvt +sdf2html -p abc.sdm

    

    

    19.2. General Fixes
    

    The sdf2txt stuff now works.
    

    

    19.3. HTML Fixes
    

    Empty cells now look better. (This was supposed to be fixed by the previous release but I had missed a few.)
    

    Paragraphs with multiple anchors are now handled better (although the odd problem probably remains with this stuff).
    

    If a table of contents is requested and SDF doesn't know the "right" place for it, it is now prepended (rather than being dumped).
    

    Title blocks for correspondence look much better now.
    

    

    19.4. HLP Fixes
    

    Absolute path names for libraries now correctly go into HPJ files. / characters are now also mapped to \ characters.
    

    Title blocks for correspondence look much better now.
    

    

    19.5. Incompatibilities
    

    None.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/release/2000b7b.sdf010064400042570001753000000074560635011350400157660ustar00iancmtr00000400000236H1: 2.000beta7b

!subsections "Enhancements,Fixes,Incompatibilities"

H2: Enhancements

The new features in this version are:

!block sections
. Object catalog formatting
. Subsections support
. Appending text to phrases
. New figure attributes
. Other 2.000beta7b goodies
!endblock

Details are given below.

H3: Object catalog formatting

The user can now control how a catalog of objects
(e.g. a table of references) is presented by
setting the {{columns}} and {{compact}} parameters.
{{columns}} is a comma-separated list of:

E:   [tag":"]attribute

:where:

* {{tag}} is a phrase style (or expression format)
* {{attribute}} is the name of an attribute of the class.

{{compact}} is a boolean flag which reduces the spacing
between the rows in the table.

This feature is extremely useful for building "project overview"
Web pages. See the SDF document catalog for an example.

H3: Subsections support

The new {{MAC:subsections}} macro can now be used to specify
the subsections in a topic. This has several advantages:

* subsections can be given a hypertext {{id}} which contains the
  current topic name (making them unique)
* for HTML, a "jump line" can be generated.

For example:

E:   H1: MyApp
E:   !subsections "Purpose,Usage,Description,Examples"

In this case, the {{MAC:subsections}} macro changes the
{{id}} generated for the headings listed to:

E:   MyApp - {{heading}}

For HTML, it will also generate a line of jumps to the headings.

H3: Appending text to phrases

Event processing on phrases has now been extended to support
appending text to a phrase, i.e. prepending text to the rest of
the paragraph. Text is appended by setting {{$append}}.
For example:

E:   !on phrase 'PRD';; $append .= '(tm)'

Note: This feature is used to provide "qsd-style" (document name and code)
expansion for REF phrases.

H3: New figure attributes

The {{IMPORT}} phrase style and the {{MAC:import}} macro
now support new attributes:

* {{base}} - the prefix to prepend to the figure pathname
  to get the location needed for the HTML output
* {{jump}} - the URL to jump to
* {{border}} - the border width in pixels.

These attributes are currently only supported for HTML output.

H3: Other 2.000beta7b goodies

The {{FILT:table}} filter now supports new attributes:

* {{cellpadding}} - the pixels between the cell boundary and contents
* {{cellspacing}} - the pixels between cells.

These attributes are currently only supported for HTML output.

In topics mode, the default header for the main topic now
contains jumps to the next and previous topics.

The {{SUBR:Values}} subroutine can now be used to lookup the value
of an attribute for an object in a class.

{{Calculation subroutines}} can now be defined for attributes in
a class. See {{FILE:perllib/sdf/values.pl}} for examples.

H2: Fixes

Unzipping SDF 2.000beta7a on MS-DOS caused problems as symbolic
links on Un*x were not being unzipped correctly.
This should now be fixed - the new distribution does not contain
symbolic links for files, just directories.

SECT phrases are now output again in [[PostScript]] documents.
(However, there is a still a bug in the cross reference support
which caused this problem.)

A number of obscure errors in formatting list items for HTML
are now fixed.

Warnings are now produced again for unknown parameters to filters.
(This was broken by the performance enhancements added in
2.000beta5, I think.)

An error is now output for tables which have repeated headings.
Previously, columns were silently "ignored".

A "noheadings" table with no data rows no longer produces
unexpected output.

A number of problems are now fixed in the {{mincom/mims}} library.
In particular, the screen dumps for MSM000A and MSM000B now look
as they should.

H2: Incompatibilities

The {{sdf2mimsus}} and {{sdf2qsdus}} aliases have been renamed
to {{sdf2mimsl}} and {{sdf2qsdl}} respectively.
sdf-2.001/doc/release/2000b12.sdf010064400042570001753000000157430661416550700157130ustar00iancmtr00000400000236H1: 2.000beta12

!subsections "Enhancements,Fixes,Incompatibilities"

H2: Enhancements

Note: The {{sdf2...}} wrapper scripts are no longer provided -
use the -2 option of the {{CMD:sdf}} command instead.

The major enhancements are:

!block sections
. Output format naming rationalisation
. Automatic figure format conversion
. Better HTML customisation and documentation
. New output formats
. Locales
. Template processing
. Paragraph text is now the default output
. Post filtering
!endblock

The minor enhancements are:

* when include files and figures are searched for, the directory
  containing the document is now searched after the current directory

* a Perl document catalog is now included (F)

* generation of non-MIF outputs is now slightly faster.

Further details on the major enhancements are provided below.

H3: Output format naming rationalisation

As SDF occasionally provides several ways to generate an output:

* a convention has been introduced for output format names
  (i.e. the parameter to the -2 option)
* a mapping table has been added to F so
  that sites can customise the mapping from logical format names
  to actual format names.

As a result, it is now easy to change F so that PostScript
generation (i.e. {{-2ps}}) is via POD format rather than via FrameMaker, say.
Furthermore, regardless of the default setup for PostScript generation:

* PostScript via FrameMaker can be explicitly requested via {{-2ps_fm}}, and
* PostScript via POD can be explicitly requested via {{-2ps_pod}}.

Generally speaking, a name of {{xxx_yyy}} means format {{xxx}} via {{yyy}}.
Likewise, a name of {{xxx_}} means format {{xxx}} directly.

H3: Automatic figure format conversion

As requested (many years ago, in fact), SDF will now automatically
convert figure formats for you if it needs to. In particular,
if you have a {{prn}} file on the search path, {{CMD:sdf}} will convert
it to {{gif}} for HTML and {{eps}} for PostScript. Likewise, if you
have an {{eps}} for PostScript, sdf will convert this to {{gif}} when
you generate HTML.

Creating a {{prn}} file as a easy as printing to a PostScript file
from most Windows apps including MS-Office and Rational Rose.
As a result, figure management should no longer be the hassle its
been in the past.

The conversion rules are stored in F.
Feel free to have a look and/or forward me any additions/enhancements
to the rules. One of the rules uses a new program supplied in
SDF called {{CMD:prn2ps}}. This new command makes the output from
a Windows 95/NT "print PostScript to a file" command acceptable to
Ghostscript's {{CMD:ps2epsi}}.

H3: Better HTML customisation and documentation

A large number of HTML customisation features already existed,
but were poorly documented. The new customisation features in
this release are:

* HTML_PRE_HEADER/HTML_POST_FOOTER support
* HTML_TEXT_* support
* HTML_SECTION_LEVEL/HTML_PRE_SECTION support.

See the new tutorial titled {{DOC: Generating HTML Using SDF}} for details.

H3: New output formats

SDF can now be converted to SGML like this:

>  sdf -2sgml mydoc.sdf

By default, the {{linuxdoc}} DTD is used.
Alternatively, the SGML_DTD variable can be used to change the DTD to
{{qwertz}}, say, like this:

>  !define SGML_DTD "qwertz"

If {{SGML-Tools}} 1.02 or later is installed, you can also generate
the formats given below.

!block table
Command          Output_format   Via
sdf -2latex_sgml LaTeX           SGML-Tools
sdf -2dvi_sgml   DVI             SGML-Tools and LaTeX
sdf -2ps_sgml    PostScript      SGML-Tools and LaTeX
sdf -2rtf_sgml   RTF             SGML-Tools
sdf -2info_sgml  GNU info        SGML-Tools
sdf -2lyx_sgml   LyX             SGML-Tools
!endblock

H3: Locales

SDF now has better support for non-English languages via locales.
The -L option of the {{CMD:sdf}} command can be used to specify a locale.
The default locale name is specified in {{FILE:sdf.ini}}.
Locale naming follows POSIX conventions (i.e. language_country), so
the locale name for American english is {{en_us}}.
The information for each locale is stored in the F directory,
so you'll need to have to look in there to see what locales are
available. (As the default locale can be set in F, this
isn't as ugly as it first sounds.)

At the moment, a locale file simply contains a list of language
specific strings, although it should ultimately be extended to
support localisation of date and time formats.
Feel free to send me new locales so I can include them in
future versions of SDF.

H3: Template processing

SDF can now also be used as a generic template processor, i.e.
you can create C source, say, with ! macros and E<2[>..E<2]> expressions
within it and use {{CMD:sdf}} to process it. For example, if you have
a file called F like this:

!block verbatim
    !if DATE
        
    
        The date is [[DATE:DOC_START]].
    !else
        
    
        The time is [[TIME:DOC_START]].
    !endif
!endblock

you can process it like this:

>  sdf xx.sdt | less
>  sdf -DDATE xx.sdt | less

If the file doesn't have a {{sdt}} extension, you need to specify
template processing like this:

>  sdf -ptemplate myskel.cpp | less

H3: Paragraph text is now the default output

If you run the {{CMD:sdf}} program on a file without giving a target,
the text of each paragraph is output. Therefore, you can now do things
like:

  sdf mydoc.sdf | spell -b

H3: Post filtering

It is now possible to post filter the output of a format driver before
the results are written to disk. The -y option of the {{CMD:sdf}} command
can now be used to specify a post filter name. A post filter called
{{xxx}} maps to a routine called {{xxx_PostFilter}} in the file
F.

Note: This feature is only useful for SDF developers who want to create a
new output format which is very simliar to an existing one.


H2: Fixes

Heading numbering in HTML and text outputs should be fixed now.

The file and line number in messages should generally be right now.
Certain filters may still lead to incorrect line numbers being reported,
but messages containing '$fullname', line number 0 or -1 should
no longer appear.

Man page generation now works again. Previously, {{CMD:pod2man}}
fell over unless a DOC_PROJECT and DOC_RELEASE was defined.

MIMS HTX and F6 Help formats should be working correctly now.
The MIMS_CLIENT_CODE variable must now be specified on the
command line when generating MIMS F6 help.

The APIs for SDF's Perl libraries are now present again in the
{{DOC:SDF Guru Guide}}.


H2: Incompatibilities

The {{sdf2...}} wrapper scripts are no longer provided -
use the -2 option of the {{CMD:sdf}} command instead.

Given the rationalisation of output format naming, some of
the previously used names (e.g. fmrtf, sgmllatex) have
been changed. If the {{CMD:sdf}} command complains about
an unknown alias, have a look in F to see what
the new name is.

The interface to {{SUBR:FindFile}}, a subroutine which some users
override to integrate SDF into their CM system, has changed.
See the {{SUBR:FindFile}} documentation for details.
sdf-2.001/doc/release/2000b6b.html010064400042570001753000000036450672242655100161650ustar00iancmtr00000400000236






SDF 2.001: SDF Release Notes: 2.000beta6b




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    16. 2.000beta6b
    

    Enhancements | Fixes | Incompatibilities
    

    

    16.1. Enhancements
    

    Tables now have a new style called box that simply puts a thin-line around the table.
    

    The cover page generated for the mincom look has been improved.
    

    

    16.2. Fixes
    

    If a look library and a configuration library had the same name, only one was begin loaded. This has now been fixed.
    

    Nested jumps within HTML files no longer cause problems - the inner jump is now ignored.
    

    

    16.3. Incompatibilities
    

    None.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/release/2000b6.sdf010064400042570001753000000105450635011350400156140ustar00iancmtr00000400000236H1: 2.000beta6

!subsections "Enhancements,Fixes,Incompatibilities"

H2: Enhancements

H3: Easier Usage

{{sdfcvt}} is now called {{CMD:sdf}}.
Furthermore, a -2 option has been added which simply maps through to
the relevant alias. i.e.

E:   sdfcvt +sdf2ps abc.sdf

can now be specfied via:

E:   sdf -2ps abc.sdf

As a side effect of this, the {{FILE:sdfcvt.ini}} file has
disappeared - its contents have been merged into {{FILE:sdf.ini}}.

The {{CMD:sdf2...}} wrapper scripts are still available, but are no
longer documented.

The -2 option may {{eventually}} support a list of formats. e.g.

E:   sdf -2ps,html abc.sdf

H3: FrameMaker 5 Support

[[FrameMaker]] 5 can now be used instead of [[FrameMaker]] 4.
This has several advantages:

* a larger range of figure types can now be imported
* book generation via {{CMD:fmbatch}} no longer causes a core dump
* useful [[PDF]] can be generated (see below).

The main disadvantage is that [[FrameMaker]] 5 has a bug in calculating
the last page number in books.

H3: Easier Figures

As [[FrameMaker]] 5 supports a larger range of figure types, the
search rules for figures without an extension have now been expanded.
The new rules are given below.

!block table
Format      Extensions
html        gif
hlp         bmp
other       eps, then eps, then bmp
!endblock

To take advantage of these rules, specify the figure file without
an extension. e.g.

E:   !import "sdfarch"

H3: PDF Support

[[PDF]] can now be generated from the [[PostScript]] output
from [[FrameMaker]] 5 by using the appropriate [[Adobe]] software.
A {{contents panel}} is generated for normal documents.

Note: [[FrameMaker]] 5 has a bug which prevents the necessary information
for a contents panel being included in the [[PostScript]] when
a book is printed to file via {{CMD:fmbatch}}. If you want a
contents panel for a book, it is currently necessary to use [[FrameMaker]]
manually to set the {{Include Acrobat Data}} option and print the file.

H3: Direct Conversion of Text Files

Plain text files can now be directly generated from SDF - [[FrameMaker]]
is no longer required. As a result, the conversion process is much
quicker and the output looks much better.

H3: POD Support

SDF documents can now be converted to POD, the file format used by
the [[Perl]] community. The Perl 5 distribution includes {{pod2man}}
and {{pod2latex}}, so SDF files can now be indirectly converted to
these formats too.

H3: HTML Headers, Footers, Colors and Backgrounds

Headers and footers to place at the top and bottom of each HTML
page can now be defined. Colors and background images can also
be specified. See the {{FILE:sdf.sdm}} for examples.

H3: Delphi Help Enhancements

A large number of fixes and improvements have been made to this.
See the {{FILE:samples/delphi}} stuff for examples.

H3: Topics Mode

When generating HTML, it is often useful to create a table of contents
and a large number of small pages, rather than a monolithic document.
This release includes a prototype version of {{topics mode}} which
illustrates how this might work. To try it, define each topic
as a separate file and use the following command:

E:   sdf -2html -ftopics *.sdf

The main document will be converted to a table of contents.
The remaining documents will be converted to topics.

Note: If the -ftopics option is not provided, a monolithic document
will be generated.

H3: Configuration Reporting

Reference documentation for an SDF module can now be automatically
generated by using the following command:

E:   sdf -2html mymodule.sdm

A summary of the terms, references, organisations and products, if any,
will be included in the generated documentation. As a result, the
reference documentation for a project library serves as a
glossary and bibliography for the project.

H3: fm2ps

An alias has been added for {{CMD:sdfbatch}} called {{CMD:fm2ps}}.
This command converts [[FrameMaker]] documents to [[PostScript]].
It can be called via eiher way below:

E:   sdfbatch +fm2ps abc.doc
E:   fm2ps abc.doc

H2: Fixes

Unknown variables in restricted families (like DOC, OPT, etc) are
now flagged as unknown (rather than read-only).

A page break is added by {{MAC:build_title}} when [[PostScript]]
is being generated.

A number of pretty-printing bugs have been removed.

The escaping of special characters (<, >, &) has been fixed in HTML.

Spacing inside table cells (for Netscape) has been improved.

H2: Incompatibilities

None.
sdf-2.001/doc/release/2000b8a.sdf010064400042570001753000000114520635011350400157550ustar00iancmtr00000400000236H1: 2.000beta8a

!subsections "Enhancements,Fixes,Incompatibilities"

H2: Enhancements

H3: Overview

The enhancements are:

!block sections
* List formatting changes
* Multiple records per row in a table
* Programming languages filters
* Dynamic filter loading
* Variable access in where attributes
* Generalised file extensions for references columns
* New images
* Class value functions
* Component directory files
* The catalog macro
* MIMS specific formats
* Reporting.
!endblock

Further details are provided below.

H3: List formatting changes

Following readability feedback:

* the default list item indent has been reduced to 18 points
* the size of bullets has been increased
* dashes are now used for 2nd level list items (and 4th and 6th).

H3: Multiple records per row in a table

The {{FILT:table}} filter now supports the {{wrap}} attribute which
puts multiple physical records into a single row.
The wrap attribute is also supported by class filters.

This feature is useful for producing online HTML indexes.

H3: Programming languages filters

If a filter matches the name of a programming language, 
the text is formatted as an example in that language, e.g.

E:!block C
E:int i;
E:!endblock

is now implicitly:

E:!block example; lang='C'
E:int i;
E:!endblock

H3: Dynamic filter loading

If a filter is not found, SDF now looks for a file called
{{filter_name}}.sdp and dynamically loads the filter from
that file if it can. See the {{FILE:stdlib/module.sdp}} file
for an example.

H3: Variable access in where attributes

Variables can now be accessed in the where attribute of the
{{FILT:table}} filter and class filters.
For example:

E: !define MODULE_CODE "XYZ"
E: ...
E: !include "../document.reg"; references; compact; \
E:   where='$o{"Reference"} =~ /$var{"MODULE_CODE"}/'; \
E:   columns="PS,REF:Reference,DOC:Document,CONCISE:Date"

H3: Generalised file extensions for references columns

If a reference attribute is all uppercase (e.g. TXT), a clickable image
for a file with that (lowercase) extension (e.g. mydoc.txt) is generated,
using an image matching the extension name (e.g. txt.gif).
Likewise, an all uppercase attribute with a leading underscore (e.g. _DIR)
generates an image for a HTML file with that suffix (e.g. mydoc_dir.html)
using an image matching the extension name (e.g. dir.gif).

This feature has been added so that SDF doesn't need to be extended
every time a new file type needs to be included in a document catalog.

H3: New images

The following images have been added to the images library:

!block table
File        Comments
dir.gif     for _dir.html files (see below)
htx.gif     for [[MIMS]] .htx files
mf6.gif     for [[MIMS]] F6 help files
!endblock

H3: Class value functions

Calculation functions can now be defined for a class.
(Previously, calculation functions were only supported for
an attribute-class combination.)

This feature is used to support arbitary file extensions
for the references class (see above).

H3: Component directory files

As large documents often contain lots of topics,
SDF now provides an option for generating a HTML
file which displays the topic directory tree for a document.

The command is:

E:   sdf -2_dir mydoc

This creates a file called mydoc_dir.html.
A web browser can then be used to view the
topic hierarchy and view the SDF files used to
build a document.

Note: Once a browser has downloaded an SDF file,
it is easy to load it into your preferred editor.
However, if you wish to change the master copy of
an SDF file, you will need to save your changes
to the appropriate location (on the server, say).

H3: The catalog macro

The new catalog macro can be used to build a catalog
of loaded objects. Filtering is provided on the name
making it easy to produce online HTML indexes.

H3: MIMS specific formats

The following output formats are now supported:

* {{mf6}} - [[MIMS]] F6 help
* {{htx}} - [[MIMS]] HTX files.

H3: Reporting

SDF now supports a generalised mechanism for producing a report
on an SDF file. See the {{FILE:stdlib/sdf_dir.sdr}} report file
for an example.

This feature is used to support the -2_dir option (see above).

H2: Fixes

The word wrapping algorithm used by txt format has been fixed so
that really long words (e.g. URLs) that don't fit on any line no
longer wrap onto the next line unless doing so is better that
leaving the word on the current line.

Formatting of title blocks for txt format is better.

The label attribute now works for headings in txt format.

The objects attribute for the {{FILT:table}} filter has been added back
in as an alias for the coltags attribute.

H2: Incompatibilities

The changes to list formatting mean that documents with
lists will be formatted differently, e.g. a given document
might have page breaks in different places.

The SDF logo images are now named sdflogo.gif and sdflogo.bmp,
rather than sdf.gif and sdf.bmp.
sdf-2.001/doc/release/2000b7a.html010064400042570001753000000044360672242653600161670ustar00iancmtr00000400000236






SDF 2.001: SDF Release Notes: 2.000beta7a




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    13. 2.000beta7a
    

    Enhancements | Fixes | Incompatibilities
    

    

    13.1. Enhancements
    

    The background colour of a table can now be set via the bgcolor parameter of the table filter.
    

    The COLOR_GREY variable is now supported.
    

    Headings at level 6 are now supported.
    

    The QSD front cover template now supports footers. (This is used within the MIMS documentation to show the MIMS version number.)
    

    

    13.2. Fixes
    

    Text output (txt) works again.
    

    Memo title blocks are formatted correctly again.
    

    The HTML generation of Delphi documents now has the "Description" heading in it, as requested by John Benders. (Previously, the heading was removed for all non-hlp targets. It is now kept for all non-ps targets.)
    

    Topics mode now works for headings containing commas.
    

    The box table style is now available inside QSD templates.
    

    

    13.3. Incompatibilities
    

    None.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/release/2000b7c.sdf010064400042570001753000000041640622022216600157610ustar00iancmtr00000400000236H1: 2.000beta7c

!subsections "Enhancements,Fixes,Incompatibilities"

H2: Enhancements

The aliases {{CC}} and {{cc}} have been added for C++ pretty printing.
This makes it easier to pretty print files with these extensions.
Pretty printing of CORBA IDL is also now supported.

A number of improvements have been made to improve the
formatting of document catalogs:

* the {{TXT}} field has been added for text documents

* the {{DOC}} field has been added for [[Word]] documents

* {{I:REFNUMONLY:Reference}} can now be used to display just
  the code and version parts of a reference code

* the {{Printer}} field has been renamed to {{Printdoc}} to
  match the name of the script in {{FILE:cgi-bin}} (the
  old name is still supported for backwards compatibility).

If you use the {{Printdoc}} field, the following variables 
control parameter values passed to the script:

* {{PRINTDOC_ROOT}} (mandatory) - the absolute URL of the directory
  containing the documents
* {{PRINTDOC_BACK}} (optional) - the absolute URL of the file to
  jump back to. (If not set, the html file matching the input file
  in the {{PRINTDOC_ROOT}} directory is used.)

Within the {{MAC:subsections}} macro, an empty section name now
causes a new-line to be added at that point in the {{jump line}}
output for HTML.

The text of a phrase can now be changed by setting the {{text}}
attribute. (This is occasionally useful in event processing.)

H2: Fixes

If a file doesn't exist, empty output files are no longer created.
Some bugs associated with filenames containing dots have also
been fixed.

The {{nl}} character now works for {{ps}} and {{mif}} targets.

Several bugs were fixed in the formatting of document catalogs:

* if a file doesn't exist, an empty date is now output
* detection of special file formats (e.g. PDF, TXT) has been improved
* the page count for [[PostScript]] generated by {{PRD:Word}} is no longer 0
* the {{back}} parameter to the {{printdoc}} script is no longer hard-coded.

Memos converted to {{html}} no longer have a table of contents
unless one is explicitly requested.

N:REF[qsd] now works for any mincom document.

H2: Incompatibilities

None.
sdf-2.001/doc/release/2000b6.html010064400042570001753000000172340672242655700160300ustar00iancmtr00000400000236






SDF 2.001: SDF Release Notes: 2.000beta6




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    18. 2.000beta6
    

    Enhancements | Fixes | Incompatibilities
    

    

    18.1. Enhancements
    

    18.1.1. Easier Usage
    

    sdfcvt is now called sdf. Furthermore, a -2 option has been added which simply maps through to the relevant alias. i.e.
    

       sdfcvt +sdf2ps abc.sdf

    

    can now be specfied via:
    

       sdf -2ps abc.sdf

    

    As a side effect of this, the sdfcvt.ini file has disappeared - its contents have been merged into sdf.ini.
    

    The sdf2... wrapper scripts are still available, but are no longer documented.
    

    The -2 option may eventually support a list of formats. e.g.
    

       sdf -2ps,html abc.sdf

    

    18.1.2. FrameMaker 5 Support
    

    FrameMaker 5 can now be used instead of FrameMaker 4. This has several advantages:
    

      

    • a larger range of figure types can now be imported

    • book generation via fmbatch no longer causes a core dump

    • useful PDF can be generated (see below).
    

    The main disadvantage is that FrameMaker 5 has a bug in calculating the last page number in books.
    

    18.1.3. Easier Figures
    

    As FrameMaker 5 supports a larger range of figure types, the search rules for figures without an extension have now been expanded. The new rules are given below.
    

    

    

Format


Extensions


    

    

html


gif


    

    

hlp


bmp


    

    

other


eps, then eps, then bmp


    

    


    To take advantage of these rules, specify the figure file without an extension. e.g.
    

       !import "sdfarch"

    

    18.1.4. PDF Support
    

    PDF can now be generated from the PostScript output from FrameMaker 5 by using the appropriate Adobe software. A contents panel is generated for normal documents.
    

    
Note: FrameMaker 5 has a bug which prevents the necessary information for a contents panel being included in the PostScript when a book is printed to file via fmbatch. If you want a contents panel for a book, it is currently necessary to use FrameMaker manually to set the Include Acrobat Data option and print the file.

    

    18.1.5. Direct Conversion of Text Files
    

    Plain text files can now be directly generated from SDF - FrameMaker is no longer required. As a result, the conversion process is much quicker and the output looks much better.
    

    18.1.6. POD Support
    

    SDF documents can now be converted to POD, the file format used by the Perl community. The Perl 5 distribution includes pod2man and pod2latex, so SDF files can now be indirectly converted to these formats too.
    

    18.1.7. HTML Headers, Footers, Colors and Backgrounds
    

    Headers and footers to place at the top and bottom of each HTML page can now be defined. Colors and background images can also be specified. See the sdf.sdm for examples.
    

    18.1.8. Delphi Help Enhancements
    

    A large number of fixes and improvements have been made to this. See the samples/delphi stuff for examples.
    

    18.1.9. Topics Mode
    

    When generating HTML, it is often useful to create a table of contents and a large number of small pages, rather than a monolithic document. This release includes a prototype version of topics mode which illustrates how this might work. To try it, define each topic as a separate file and use the following command:
    

       sdf -2html -ftopics *.sdf

    

    The main document will be converted to a table of contents. The remaining documents will be converted to topics.
    

    
Note: If the -ftopics option is not provided, a monolithic document will be generated.

    

    18.1.10. Configuration Reporting
    

    Reference documentation for an SDF module can now be automatically generated by using the following command:
    

       sdf -2html mymodule.sdm

    

    A summary of the terms, references, organisations and products, if any, will be included in the generated documentation. As a result, the reference documentation for a project library serves as a glossary and bibliography for the project.
    

    18.1.11. fm2ps
    

    An alias has been added for sdfbatch called fm2ps. This command converts FrameMaker documents to PostScript. It can be called via eiher way below:
    

       sdfbatch +fm2ps abc.doc
   fm2ps abc.doc

    

    

    18.2. Fixes
    

    Unknown variables in restricted families (like DOC, OPT, etc) are now flagged as unknown (rather than read-only).
    

    A page break is added by build_title when PostScript is being generated.
    

    A number of pretty-printing bugs have been removed.
    

    The escaping of special characters (<, >, &) has been fixed in HTML.
    

    Spacing inside table cells (for Netscape) has been improved.
    

    

    18.3. Incompatibilities
    

    None.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



pt when a book is printed to file via fmbatch. If you want a contents panel for a book, it is currently necessary to use FrameMaker manually to set the Include Acrobat Data option and print the file.

    

    






SDF 2.001: SDF Release Notes




    

    

    Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    SDF Release Notes
    

    MTR-SDF-0008.001 (Final)
    

    Ian Clatworthy
    

    25 May 1999
    

    

    

    

    

    Table of Contents
    


    

    

    

    Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/release/2000b7.sdf010064400042570001753000000165250635675342400156420ustar00iancmtr00000400000236H1: 2.000beta7

!subsections "Enhancements,Fixes,Incompatibilities"

H2: Enhancements

There are lots of new things in this version including:

!block sections
. Topics mode for HTML
. HTML headers and footers
. HTML control variables
. Macros inside tables
. Wide tables
. Figure enhancements
. Special characters
. Cross-references
. Other goodies
!endblock

Details are given below.

H3: Topics mode for HTML

SDF can now generate a set of HTML topics, rather than a single
HTML file. The command is:

E:   sdf -2topics myfile.sdf

If you want to manually control how a document is split into
topics, simply include other sdf files which contain headings.
These manual topics, if any, can be supplemented with automatically
generated topics. By default, level 1 headings are used as topic
breaks, in addition to the manual ones. The -n option can be used
to change this:

* -n0 disables autosplitting
* -n2 uses level 1-2 headings to autosplit
* -n3 uses level 1-3 headings to autosplit
* etc.

To make it easy to navigate around the topics, SDF generates a
default header and footer for a topic which supports jumping to the:

* main topic (i.e. the contents)
* parent topic
* previous topic
* next topic.

H3: HTML headers and footers

These macros give you total control over the headers and footers used:

* HTML_HEADER - header on a HTML document (or main topic)
* HTML_FOOTER - footer on a HTML document (or main topic)
* HTML_TOPIC_HEADER - header on a HTML topic
* HTML_TOPIC_FOOTER - footer on a HTML topic.

The default implementation of these macros is in {{FILE:html.sdm}}
in the {{FILE:kernel}} library.
The default versions of these macros use the variables below, if they
are set. On most occasions, useful headers and footers can be obtained
by simply setting these variables:

* HTML_URL_HOME - URL of the home page
* HTML_URL_CATALOG - URL of the catalog
* HTML_URL_SEARCH - URL of the search facilities.

H3: HTML control variables

To fine tune HTML output, the following variables are useful:

* HTML_BG_COLOR - the background colour of the page
* HTML_BG_IMAGE - the background image of the page
* HTML_TEXT_COLOR - the colour of normal text
* HTML_LINK_COLOR - the colour of unvisited links
* HTML_VLINK_COLOR - the colour of visited links.

To set a colour, use the RGB (red-green-blue) value as used by [[HTML]].
For example:

E:   !define HTML_BG_COLOR "ffffff"

For convenience, a number of variables are defined for common colours:

. COLOR_WHITE
. COLOR_BLACK
. COLOR_RED
. COLOR_GREEN
. COLOR_BLUE
. COLOR_YELLOW
. COLOR_CYAN
. COLOR_MAGENTA.

These are used as follows:

E:   !define HTML_BG_COLOR COLOR_WHITE

H3: Macros inside tables

Macros can now be used inside tables. In particular:

* rows can now be conditionally included or excluded
* rows can be marked as changed.

For example:

!block example
!block table
Code    Description
BTW     By the way
!block changed
RTFM    Read the (fine) manual
!endblock
!if ALL_TERMS
SOS     Save our souls
!endif
!endblock
!endblock

H3: Wide tables

The {{FILT:table}} filter now supports a new attribute called {{wide}}.
When it is used, the table spans the side-head in addition to the
text column.

H3: Figure enhancements

The {{MAC:import}} macro now supports an {{align}} attribute,
which is passed into the generated HTML. This can be used
in combination with the {{MAC:clear}} macro to control how
figures are aligned with text in HTML.

For example:

!block example
!import "mylogo"; align="right"
Some text.
!clear
!endblock

HTML's {{alt}} attribute is now also supported by the
{{MAC:import}} macro.

H3: Special characters

Special characters can now be entered using E<2{>CHAR:xxxE<2}>
where {{xxx}} is either:

* a symbolic name
* a character code (HTML only).

The symbolic names supported are given below.

!block table
Name            Description
bullet
c               copyright symbol
cent
dagger
doubledagger
emdash          a hyphen which is the width of the point size
endash          a hyphen which is half the width of the point size
emspace         a space which is the width of the point size
enspace         a space which is half the width of the point size
nbdash          a non-breaking hyphen
nbspace         a non-breaking space
nl              newline
pound
r               registered trademark
tab             tab character
tm              trademark
yen
!endblock

For convenience, variables with the same name are predefined.
This makes it easy to include a special character. For example:

E:   Copyright [\[c]\] 1996, Us Pty Ltd.

Note: Some target formats do not yet support all of these characters.
For example, HTML does not yet support Em or En spaces.
In these cases, {{CMD:sdf}} will do the best it can (e.g. use a
normal space for enpsace and emspace).

H3: Cross-references

Cross-references are now supported via the {{xref}} phrase attribute.
For example:

V: Refer to page {{N[xref="pagenum"] Samples}} for more samples.

The value specifies the cross-reference style to use.
The phrase text is used to find the target location.
The predefined styles are given below.

!block table
Name            Value
pagenum         the page number
paratext        the paragraph text
paratag         the (FrameMaker) paragraph tag
paranum         the paragraph number (e.g. Appendix A)
paranumonly     the paragraph number only (e.g. A)
section         section {{paranumonly}}, {{paratext}}, on page {{pagenum}}
!endblock

New styles can be added by using the {{xrefs}} configuration filter.
See {{FILE:mif.sdm}} in the {{FILE:kernel}} directory for examples.

Note: Other than [[PostScript]], most targets ignore cross-references.

H3: Other goodies

New macros include:

* {{MAC:output}} - dynamically change the output file used

New filters include:

* {{FILT:changed}} - mark a block as changed (shorthand for {{sdf; changed}})
* {{FILT:topics}} - include a set of sub-topics
* {{FILT:sections}} - create section jumps for html and hlp outputs
* {{FILT:note}} - format a note
* {{FILT:quote}} - format a quotation
* {{FILT:address}} - format an address
* {{FILT:ascii_graphic}} - format an ASCII graphic.

The current directory is now searched first for the configuration
library, i.e. if OPT_CONFIG is {{abc}}, {{CMD:sdf}} first looks
for {{./abc.sdm}} before searching for {{abc.sdm}} in a directory
called {{abc}} on the search path.

H2: Fixes

The copy number field on the mincom cover page has been fixed.

The {{Limitations & Future Directions}} heading in {{FILE:sdfget.sdm}}
has been changed to {{Limitations and future directions}}.

H2: Incompatibilities

The {{objects}} attribute of the {{FILT:table}} filter is now
called {{tags}}.

The {{FILT:sections}} filter now generates SECT jumps for
each paragraph within the block, provided the output is html or hlp.
To include sub-topics (sub-sections), use the new {{FILT:topics}}
filter.

When pretty-printing files using {{CMD:sdf}}, use the -N option
to control line numbering. The -n option is now used to specify
the level when autosplitting into [[HTML]] topics.

The {{MAC:message}} macro has been simplified - the message type
is now an optional second parameter.

The {{obj*}} configuration filters have been renamed to
{{phrase*}} to better reflect their purpose. (This shouldn't
affect normal documents.)

The {{cfg_lang}} configuration filter has been renamed to
{{FILT:langdefs}}.

# ??????? WILL THIS STUFF THINGS UP ???????
#
#The output extension (i.e. OPT_OUT) is now used as the extension
#for {{.html}} jumps.
sdf-2.001/doc/release/2000b6c.html010064400042570001753000000032420672242654700161640ustar00iancmtr00000400000236






SDF 2.001: SDF Release Notes: 2.000beta6c




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    15. 2.000beta6c
    

    Enhancements | Fixes | Incompatibilities
    

    

    15.1. Enhancements
    

    A template directory has been added. This contains skeleton SDF files for different document types.
    

    Prefilters now have their own subdirectory under lib.
    

    

    15.2. Fixes
    

    None.
    

    

    15.3. Incompatibilities
    

    None.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/release/2000b9a.sdf010064400042570001753000000040360635017455000157660ustar00iancmtr00000400000236H1: 2.000beta9a

!subsections "Enhancements,Fixes,Incompatibilities"

H2: Enhancements

A series of LOGO_BASE variables have been introduced so that
the browser-time location of HTML images can be different
to the compile-time location. For example, by defining:

E:!define DOC_LOGO      "mylogo"
E:!define DOC_LOGO_BASE "/images/"

the URL of the logo image will be "/images/mylogo.gif".

New aliases have been introduced to make it easier to
rebuild topics (+mt) and chapters (+mc) in the MIMS documentation.
For example, to build the PostScript for the MIMS topic called
3201_msm200a.sdf, the command is:

E:       sdf -2ps +mt 3201_msm200a

H2: Fixes

Perl 5.004 introduced a warning about an odd number of elements
in a hash list which previous versions of SDF occasionally triggered.
The cause of the warning has now been fixed.

The {{label}} parameter on the {{FILT:note}} filter now works.

Some minor documentation corrections have been made. In particular,
the URL for the Ultimate editor is now correct.

Lines now appear above and below notes in HTML.

H2: Incompatibilities

The {{FILT:box}} filter has been changed to do what people expect.
The old behaviour is available by adding the {{lines}} parameter.

H2: Future Incompatibilities!

The {{B:next}} version of SDF is probably going to be (almost)
upwardly compatible with Perl5's POD format. As a result,
the = character will be a multi-line macro invocation,
rather than being a shorthand for E:. If you are currently
using =, please replace it with E: in preparation for the
next release.

Making SDF upwardly compatible with POD will undoubtedly
introduce a few other incompatibility problems. However,
I'll do what I can to minimise these. The goal is to make
it possible to use SDF for Perl5 module documentation when
POD is not sufficient.

If you have any feedback on the idea of making SDF upwardly
compatible with POD, send some email to the SDF users
mailing list ({{EMAIL:sdf-users@mincom.com}}).

This release will also be the last one supporting Perl 4.036.
Future releases will require Perl 5.
"Enhancements,Fixes,Incompatibilities"

H2: Enhancements

A series of LOGO_BASE variables have been introduced so that
the browser-time location of HTML images can be different
to the compile-time location. For example, by defining:

E:!define DOC_LOGO      "mylogo"
E:!define DOC_LOGO_BASE "/images/"

the URL of the logo image will be "/images/mylogo.gif".

New aliases have been introduced to make it easier to
rebuild topics (+mt) and chapters (+mc) in the MIMS documentation.
Fsdf-2.001/doc/release/2000b7b.html010064400042570001753000000143700672242653400161640ustar00iancmtr00000400000236






SDF 2.001: SDF Release Notes: 2.000beta7b




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    12. 2.000beta7b
    

    Enhancements | Fixes | Incompatibilities
    

    

    12.1. Enhancements
    

    The new features in this version are:
    


    Details are given below.
    

    12.1.1. Object catalog formatting
    

    The user can now control how a catalog of objects (e.g. a table of references) is presented by setting the columns and compact parameters. columns is a comma-separated list of:
    

       [tag":"]attribute

    

    where:
    

      

    • tag is a phrase style (or expression format)

    • attribute is the name of an attribute of the class.
    

    compact is a boolean flag which reduces the spacing between the rows in the table.
    

    This feature is extremely useful for building "project overview" Web pages. See the SDF document catalog for an example.
    

    12.1.2. Subsections support
    

    The new subsections macro can now be used to specify the subsections in a topic. This has several advantages:
    

      

    • subsections can be given a hypertext id which contains the current topic name (making them unique)

    • for HTML, a "jump line" can be generated.
    

    For example:
    

       H1: MyApp
   !subsections "Purpose,Usage,Description,Examples"

    

    In this case, the subsections macro changes the id generated for the headings listed to:
    

       MyApp - heading

    

    For HTML, it will also generate a line of jumps to the headings.
    

    12.1.3. Appending text to phrases
    

    Event processing on phrases has now been extended to support appending text to a phrase, i.e. prepending text to the rest of the paragraph. Text is appended by setting $append. For example:
    

       !on phrase 'PRD';; $append .= '(tm)'

    

    
Note: This feature is used to provide "qsd-style" (document name and code) expansion for REF phrases.

    

    12.1.4. New figure attributes
    

    The IMPORT phrase style and the import macro now support new attributes:
    

      

    • base - the prefix to prepend to the figure pathname to get the location needed for the HTML output

    • jump - the URL to jump to

    • border - the border width in pixels.
    

    These attributes are currently only supported for HTML output.
    

    12.1.5. Other 2.000beta7b goodies
    

    The table filter now supports new attributes:
    

      

    • cellpadding - the pixels between the cell boundary and contents

    • cellspacing - the pixels between cells.
    

    These attributes are currently only supported for HTML output.
    

    In topics mode, the default header for the main topic now contains jumps to the next and previous topics.
    

    The Values subroutine can now be used to lookup the value of an attribute for an object in a class.
    

    Calculation subroutines can now be defined for attributes in a class. See perllib/sdf/values.pl for examples.
    

    

    12.2. Fixes
    

    Unzipping SDF 2.000beta7a on MS-DOS caused problems as symbolic links on Un*x were not being unzipped correctly. This should now be fixed - the new distribution does not contain symbolic links for files, just directories.
    

    SECT phrases are now output again in PostScript documents. (However, there is a still a bug in the cross reference support which caused this problem.)
    

    A number of obscure errors in formatting list items for HTML are now fixed.
    

    Warnings are now produced again for unknown parameters to filters. (This was broken by the performance enhancements added in 2.000beta5, I think.)
    

    An error is now output for tables which have repeated headings. Previously, columns were silently "ignored".
    

    A "noheadings" table with no data rows no longer produces unexpected output.
    

    A number of problems are now fixed in the mincom/mims library. In particular, the screen dumps for MSM000A and MSM000B now look as they should.
    

    

    12.3. Incompatibilities
    

    The sdf2mimsus and sdf2qsdus aliases have been renamed to sdf2mimsl and sdf2qsdl respectively.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/release/2000b10.html010064400042570001753000000445560672242645500161070ustar00iancmtr00000400000236






SDF 2.001: SDF Release Notes: 2.000beta10




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6. 2.000beta10
    

    Enhancements | Fixes | Incompatibilities
    

    

    6.1. Introduction
    

    The primary objectives of this release are:
    

      

    1. To provide a "working prototype" for a POD-friendly SDF.

    2. To rationalise SDF's escaping mechanisms and stabilise it's syntax.

    3. To provide greatly improved man page generation (via pod2man).

    4. To provide PostScript generation without needing a commercial tool.
    

    I still need to fix up some bugs and loose ends with respect to the POD stuff, but there's enough working to be useful (in my opinion, at least). In particular, the core POD documentation provided with Perl 5.004 can be:
    

      

    1. Converted to SDF and back to POD with a high degree of success (99.95% if the perltoc.pod file is excluded).

    2. Converted to HTML and plain text using the sdf program.
    

    If you're an existing POD user, please read the SDF for POD Users tutorial. If you find a bug not listed in the PODNOTES file, email the details to sdf-bugs@mincom.com.
    

    If you're an existing SDF user, please note that most of the documentation doesn't yet reflect the changes outlined below. You will also need to take care with the Incompatibilities outlined below.
    

    

    6.2. Enhancements
    

    The enhancements are:
    


    Further details are provided below.
    

    6.2.1. SDF is now POD-friendly
    

    POD users can now use SDF or migrate to SDF when POD isn't powerful enough. In particular:
    

      

    • POD can now be converted to SDF and vice versa

    • SDF can now be nested inside POD and vice versa

    • SDF is now largely upwardly compatible with POD in terms of syntax and functionality.
    

    A poddiff program is provided so that users can translate POD -> SDF -> POD and compare the generated POD with the original.
    

    6.2.2. Syntax Enhancements
    

    Any SDF macro can now be called via POD's = syntax, i.e. if a macro call starts with an = character, the call is terminated by the next blank line.
    

    As a consequence of its new meaning, = is no longer available as a shorthand for the E paragraph tag. However, the > character can now be used as a shorthand for the V (verbatim) paragraph tag. See Verbatim paragraphs below.
    

    Any phrase style which is a single capital letter can now be specified using POD's [A-Z]<..> syntax. So, the following lines are equivalent:
    

       Hello {{B:world}}
   Hello B<world>

    

    Paragraph and phrase styles must now start with a capital letter, digit or underscore. As a result, the following SDF will now come out as expected.
    

      The following documents should be
  reviewed:

    

    Previously, SDF would warn about reviewed being an unknown paragraph style. As a special case, phrases which look like URLs are still assumed to be so.
    

    Outside of blocks and multi-line macros calls, a \ at the start of a line now escapes a special character or pattern, including itself. A \ can also be used to escape a ] character within a set of attributes.
    

    At the end of a !-style macro call line:
    

      

    • a single \ continues the macro onto the next line

    • exactly 2 backslashes means a single backslash (with no continuation)

    • N backslashes (N >= 3) means N-1 backslashes with continuation
    

    6.2.3. Verbatim paragraphs
    

    For fixed-width verbatim paragraphs, the > special tag or V paragraph style can now be used. For example:
    

    >  {{Hello world}}

    

    or
    

    V:  {{Hello world}}

    

    The result is:
    

      {{Hello world}}

    

    The new verbatim filter can be used to mark a block of text as verbatim.
    

    In fact, the interpolation of embedded characters within the text of any paragraph can be disabled by setting the verbatim paragraph attribute. For example:
    

      N[verbatim] {{Hello world}}

    

    The result is:
    

    {{Hello world}}
    

    6.2.4. Special symbol escapes
    

    SDF uses a number of special symbols inside paragraphs:
    

      

    • A-Z< and > - delimit concise phrases

    • {{ and }} - delimit verbose phrases

    • [[ and ]] - delimit expressions (e.g. variables).
    

    If you need to include one of these symbols in a paragraph, use the appropriate escape as shown below.
    

        Symbol      Escape
    <           E<lt>
    >           E<gt>
    {{          E<2{>
    }}          E<2}>
    [[          E<2[>
    ]]          E<2]>

    

    Note the following rules:
    

      

    1. It isn't necessary to escape any symbols within:
        

      • paragraphs tagged with the V style or > tag
        

      • paragraphs given the verbatim attribute
        

      • paragraphs within a verbatim block
      

    2. It is only necessary to escape a < when it appears after a capital letter.

    3. It is only necessary to escape a > inside a concise phrase. In particular, > is implicitly escaped within a verbose phrase.
    

    6.2.5. Enumerated lists
    

    In addition to bulleted, ordered and plain lists, SDF now supports enumerated lists, i.e. lists where each item is a label. Each enumerated list item is tagged with either:
    

      

    • a & special tag (& .. &&&&&& like the other lists), or

    • the LIn style, where n = 1 .. 6.
    

    For example:
    

    & BTW
. by the way
& FYI
. for your information
& RTFM
. read the flamin' manual

    

    The result is:
    

    BTW
    

      
by the way
    

    FYI
    

      
for your information
    

    RTFM
    

      
read the flamin' manual
    

    6.2.6. New macros
    

    All of POD's commands are now available as SDF macros. The new macros are:
    

    

    

Macro


Meaning


    

    

headn


level n heading (n = 1 .. 6)


    

    

over [N]


begins a list (N is the suggested indentation which is ignored)


    

    

item string


label for item in a list


    

    

back


ends a list


    

    

pod


does nothing


    

    

cut


ignore text until an = is found at the start of a line


    

    

for X Y


Y is target-specific output for X


    

    

begin X


begin target-specific output for X


    

    

end X


end target-specific output for X


    

    


    See the perlpod manpage for further details.
    

    6.2.7. New phrase styles
    

    All of POD's interior sequences are now available as SDF phrase styles. The new phrase styles are:
    

    

    

Style


Meaning


    

    

B


bold


    

    

C


code


    

    

E


special symbol or HTML escape


    

    

F


file


    

    

I


italics


    

    

L


POD-style link


    

    

S


text contains non-breaking spaces


    

    

X


an index entry


    

    

Z


does nothing


    

    


    See the perlpod manpage for further details on the meanings of these tags.
    

    
Note: The S and X tags are not yet working for most output formats.

    

    6.2.8. Manpage, LaTeX and fancy text support
    

    The sdf -2man ... command now generates a .out file in POD format and runs pod2man. The old man page generation software was limited in scope and quite buggy, so this will hopefully improve things in the short-to-medium term. The toman.pl output driver has been moved to the contrib/drivers directory just in case anyone really wants to use it instead.
    

    The sdf -2latex ... command now generates a .out file in POD format and runs pod2latex. This creates a .out.tex file which should probably be renamed to delete the .out bit.
    

    The sdf -2text ... command now generates a .out file in POD format and runs pod2text. For compatibility with pod2text, this sends the output to standard output.
    

    
Note: Plain text output is still available via the -2txt option.

    

    Hopefully, someone will provide fully functional manpage and LaTeX drivers (complete with table support) eventually.
    

    6.2.9. PostScript generation without a commercial tool
    

    SDF can now generate PostScript without needing a commercial tool. This can be done by:
    

      

    1. Using sdf -2podps ... which generates PostScript directly via the freely available pod2ps program.

    2. Using sdf -2man ... which generates a man page which can be converted to PostScript by using the appropriate (*roff) tools.

    3. Using sdf -2latex ... which generates a LaTeX document which can be converted to PostScript by using LaTeX.
    

    In general, the output via these methods isn't as good as the PostScript generated via FrameMaker, but it may be good enough. In particular, certain looks (e.g. infomap) are not available.
    

    6.2.10. POD to SDF conversion
    

    A pod2sdf program is now available which is a wrapper around  a Perl module called Pod::Sdf. The SDF generated is more or less identical to the input POD, except that verbatim lines are tagged with a leading ">". The usage of pod2sdf is:
    

      pod2sdf [-m] podfile > outfile

    

    If the -m option is provided, the document is converted as a main document, rather than a topic, i.e. the NAME section is converted to a build_title macro rather than a head1 macro.
    

    POD authors can escape to SDF if and when they need to by using the "=for sdf" and/or "=begin/end sdf" command pair. For example:
    

      =for sdf
  !block table
  Name    Meaning
  POD     Plain Old Documentation
  SDF     Simple Document Format
  !endblock

    

    If you want the rest of a POD file to be in SDF, simply put in an "=begin sdf" - the closing "=end sdf" isn't necessary.
    

    6.2.11. Nesting of POD within SDF
    

    POD can now be nested inside SDF via the new pod filter (which is another wrapper around the Pod::Sdf module). e.g.
    

       !block pod
   =head2 My B<heading>

      Some verbatim text
   !endblock

    

    
Note: Within the pod filter, all lines before the first command is ignored and leading whitespace implies a verbatim paragraph.

    

    The pod filter can also be specified to the include and execute macros. For example:
    

      !include "perlre.pod"; pod
  !execute "getpod 'hello.c'"; pod

    

    where getpod is a fictitious program which outputs POD to standard output.
    

    6.2.12. Automatic translation of POD files
    

    If a file with a .pod, .pm or .PL extension is provided as an argument to the sdf command, the pod filter is implicitly applied. So
    

      
sdf -2html perlre.pod
    

    will generate HTML for perlre.pod using SDF's HTML output driver. You can also explicitly request pod prefiltering via the -p option. e.g.
    

      
sdf -2html -ppod abc.pd
    

    When pod prefiltering happens, the output is assumed to be a main document.
    

    6.2.13. Configuration library for Perl documentation
    

    A configuration library for building Perl's documentation is provided. The main thing which this provides is semi-intelligent hypertext link generation between Perl's standard documentation and its library documentation. Within this library, the HTML root directory (equivalent to pod2html's --htmlroot flag) can be controlled via the PERL_HTML_ROOT variable. The default value is /perl. Typical usage is:
    

      sdf -2html -cperl -DPERL_HTML_ROOT=/nmanual/perl perl*.pod

    

    At the moment, this library is only required for HTML generation.
    

    6.2.14. Topic previewing
    

    When editing a topic within a large document, it can be useful to only compile that topic in order to preview its appearance. The new -H option can be used to adjust the initial heading level like this:
    

      sdf -2ps -H3 -kinfomap mytopic.sdf

    

    Without the -H3 option, the H1s within mytopic.sdf would come out as level 1 headings, rather than level 3 headings.
    

    6.2.15. Easier text width control
    

    The width of text output can now be controlled from the command line by using the new -w option to the sdf program.
    

    

    6.3. Fixes
    

    Special characters in headings (like [) no longer cause problems.
    

    The POD output driver has been fixed. In particular, the generation of list items has been fixed.
    

    Some bugs in the pretty printing of source code have been fixed:
    

      

    • 80 character lines should now fit

    • The >> character sequence is no longer lost

    • form feeds become page breaks.
    

    Handling of multi-line macro calls within a block or macro has been fixed.
    

    The box filter no longer centers the contents of the box unless the lines parameters is provided.
    

    

    6.4. Incompatibilities
    

    This release now requires Perl 5. If you are still using Perl 4.036, you will need to upgrade.
    

    As paragraph and phrase styles can no longer start with a lowercase character, you will need to rename any user-defined styles which violate this rule.
    

    Lines within paragraphs which begin with the > or & character will now need to be escaped by a leading \.
    

    Wide example now use a slightly smaller font.
    

    The default values for the DOC_DISTRIBUTION and DOC_STATUS variables are now empty strings. Previously, they were "COMMERCIAL IN CONFIDENCE" and "Draft" respectively.
    

    Making SDF POD-friendly has introduced a number of incompatibilities. These are summarised below:
    

      

    • The = character is no longer a shorthand for E: - it is now used for multi-line macro calls.

    • Existing paragraphs which contain the sequence [A-Z]<..> (i.e. a POD-like phrase) as text will need to be changed.

    • The S (strong) and E (example) phrase styles have been renamed to ST and EX respectively. S and E now have the same meaning as their POD counterparts, i.e. "text contains non-breaking spaces" and "escape" respectively. As the S tag was often used for "symbols" (i.e. variables, subroutines) within a library, a Y tag has been introduced for this purpose.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



D>
Meaning

    		

    

    

headn


level n heading (n = 1 .. 6)


    

    

over [N]







SDF 2.001: SDF Release Notes: 2.000beta8a




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    9. 2.000beta8a
    

    Enhancements | Fixes | Incompatibilities
    

    

    9.1. Enhancements
    

    9.1.1. Overview
    

    The enhancements are:
    


    Further details are provided below.
    

    9.1.2. List formatting changes
    

    Following readability feedback:
    

      

    • the default list item indent has been reduced to 18 points

    • the size of bullets has been increased

    • dashes are now used for 2nd level list items (and 4th and 6th).
    

    9.1.3. Multiple records per row in a table
    

    The table filter now supports the wrap attribute which puts multiple physical records into a single row. The wrap attribute is also supported by class filters.
    

    This feature is useful for producing online HTML indexes.
    

    9.1.4. Programming languages filters
    

    If a filter matches the name of a programming language, the text is formatted as an example in that language, e.g.
    

    !block C
int i;
!endblock

    

    is now implicitly:
    

    !block example; lang='C'
int i;
!endblock

    

    9.1.5. Dynamic filter loading
    

    If a filter is not found, SDF now looks for a file called filter_name.sdp and dynamically loads the filter from that file if it can. See the stdlib/module.sdp file for an example.
    

    9.1.6. Variable access in where attributes
    

    Variables can now be accessed in the where attribute of the table filter and class filters. For example:
    

     !define MODULE_CODE "XYZ"
 ...
 !include "../document.reg"; references; compact; \
   where='$o{"Reference"} =~ /$var{"MODULE_CODE"}/'; \
   columns="PS,REF:Reference,DOC:Document,CONCISE:Date"

    

    9.1.7. Generalised file extensions for references columns
    

    If a reference attribute is all uppercase (e.g. TXT), a clickable image for a file with that (lowercase) extension (e.g. mydoc.txt) is generated, using an image matching the extension name (e.g. txt.gif). Likewise, an all uppercase attribute with a leading underscore (e.g. _DIR) generates an image for a HTML file with that suffix (e.g. mydoc_dir.html) using an image matching the extension name (e.g. dir.gif).
    

    This feature has been added so that SDF doesn't need to be extended every time a new file type needs to be included in a document catalog.
    

    9.1.8. New images
    

    The following images have been added to the images library:
    

    

    

File


Comments


    

    

dir.gif


for _dir.html files (see below)


    

    

htx.gif


for MIMS .htx files


    

    

mf6.gif


for MIMS F6 help files


    

    


    9.1.9. Class value functions
    

    Calculation functions can now be defined for a class. (Previously, calculation functions were only supported for an attribute-class combination.)
    

    This feature is used to support arbitary file extensions for the references class (see above).
    

    9.1.10. Component directory files
    

    As large documents often contain lots of topics, SDF now provides an option for generating a HTML file which displays the topic directory tree for a document.
    

    The command is:
    

       sdf -2_dir mydoc

    

    This creates a file called mydoc_dir.html. A web browser can then be used to view the topic hierarchy and view the SDF files used to build a document.
    

    
Note: Once a browser has downloaded an SDF file, it is easy to load it into your preferred editor. However, if you wish to change the master copy of an SDF file, you will need to save your changes to the appropriate location (on the server, say).

    

    9.1.11. The catalog macro
    

    The new catalog macro can be used to build a catalog of loaded objects. Filtering is provided on the name making it easy to produce online HTML indexes.
    

    9.1.12. MIMS specific formats
    

    The following output formats are now supported:
    

      

    • mf6 - MIMS F6 help

    • htx - MIMS HTX files.
    

    9.1.13. Reporting
    

    SDF now supports a generalised mechanism for producing a report on an SDF file. See the stdlib/sdf_dir.sdr report file for an example.
    

    This feature is used to support the -2_dir option (see above).
    

    

    9.2. Fixes
    

    The word wrapping algorithm used by txt format has been fixed so that really long words (e.g. URLs) that don't fit on any line no longer wrap onto the next line unless doing so is better that leaving the word on the current line.
    

    Formatting of title blocks for txt format is better.
    

    The label attribute now works for headings in txt format.
    

    The objects attribute for the table filter has been added back in as an alias for the coltags attribute.
    

    

    9.3. Incompatibilities
    

    The changes to list formatting mean that documents with lists will be formatted differently, e.g. a given document might have page breaks in different places.
    

    The SDF logo images are now named sdflogo.gif and sdflogo.bmp, rather than sdf.gif and sdf.bmp.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/release/2000b8.sdf010064400042570001753000001021710647021675000156250ustar00iancmtr00000400000236H1: 2.000beta8

!subsections "Enhancements,Fixes,Incompatibilities"

H2: Enhancements

There are lots of new things in this version.
The general enhancements are:

!block sections
. Easier enumerated values
. Look improvements
. Style rationalisation
. More build_title control variables
. Miscellaneous things.
!endblock

The table enhancements are:

!block sections
. Easier column widths
. Heading/footing rows for tables
. Table positioning
. Table filtering and sorting
. Landscape tables
. Column alignment
. Cell attributes
. Spreadsheet calculations.
!endblock

The page formatting enhancements are:

!block sections
. Arbitrary page sizes
. Headers and footers
. Header/footer special tags
. Header/footer borders
. Page backgrounds
. Page layout variables
. Page control within a book.
!endblock

The configuration enhancements are:

!block sections
. FrameMaker templates are no longer required
. Event processing enhancements.
!endblock

Details are given below.

Note: For {{html}} and {{txt}} targets, this release is slightly faster
than the previous one. For {{mif}} (and {{ps}}), this release may be
slightly slower (as SDF templates, not FrameMaker ones, are
now used).


H3: Easier enumerated values

Enumerated values no longer need to be quoted.
In a set of name-value pairs, if an expression is a single word where:

* the first character is uppercase
* the remaining characters are lowercase

then the word is assumed to be an enemerated value and
it is automatically converted to a string. For example,
the following two lines are now equivalent:

E:   P1[align="Center"] My Title
E:   P1[align=Center] My Title


H3: Look improvements

The overall appearance (i.e. look) of an SDF document can be
controlled via the -k option or the OPT_LOOK variable.
SDF now supports the following looks:

* {{simple}} - the default look, useful for general documentation

* {{fancy}} - QSD-like look, but without any logos

* {{infomap}} - look based on Information Mapping[[tm]]

* {{overhead}} - look suitable for overhead transparencies.

Note: For backwards compatibility, {{plain}} is now an alias for
{{simple}}.

H3: Style rationalisation

SDF now supports the styles (i.e. document types) below.

!block table; groups
Style           Purpose
General:
document        a normal document
manual          a manual
paper           a technical paper
Administration:
admin           generic administration document
fax             a fascimile
memo            a memorandum
newslttr        a newsletter
minutes         minutes of a meeting
Miscellaneous:
listing         a source code listing
!endblock

The {{MAC:build_title}} macro is used to build the cover page
for the general styles.
The {{FILT:title}} filter is used to build the title block
for the administation styles.
The miscellaneous styles do not have a title.

Adding new styles for a look is now much easier than it
was previously. Furthermore, {{manual}} is now just another
style rather than a special mode.


H3: More build_title control variables

{{MAC:build_title}} now supports the following variable:

* {{DOC_COVER}} - the logical name of the cover page to use.

Supported DOC_COVER values and their meanings are given below:

!block table
Value       Meaning
original    SDF's original cover page layout
project     a cover page useful for project documentation
manual      the cover page used when OPT_STYLE is manual
paper       the cover page used when OPT_STYLE is paper
!endblock

The {{manual}} cover supports a new macro called {{DOC_OFFICES}},
i.e. if DOC_OFFICES is defined, its contents are appended after
the inside cover page.


H3: Miscellaneous things

The {{SDF What's Planned}} document and {{bugs.html}}
have been replaced by the {{DOC:SDF Bug Database}}.
In fact, the organisation of the documentation has
been improved quite a bit.

Any document can now be converted to a FrameMaker book, i.e.
it is no longer necessary to specially organise files in
order to create a FrameMaker book.

Tables of style {{columns}} (the default) now have
a thin line above group rows.

Tables can now be specified as list items by using the {{listitem}}
parameter of the {{FILT:table}} filter. The value is the logical
indent of the list (e.g. 1, 2, etc.). When generating HTML
which contains a table within a numbered list, the {{listitem}}
parameter is necessary in order to prevent the numbering from
resetting.

#The new {{MAC:continued}} macro can be used to continue a heading
#onto another page (as is standard practice within Information Mapping).

The new {{box}} filter can be used to place a box around one or
more lines of text.

The new {{center}} filter can be used to center a region of text.

The new paragraph attribute called {{wide}} can be used to
specify that a paragraph straddles the side-head area in addition
to the main text area. Likewise. class filters (e.g. terms, references, etc.)
now also support the {{wide}} attribute.

By default, SDF automatically generates an {{id}} attribute for
all headings in the table of contents. However, it is occasionally
necessary to disable this, particularly when the same heading
appears multiple times in a file.
The new paragraph attribute {{noid}} can be used to prevent an
{{id}} being generated for a paragraph.

The title for an administration-style document can now be changed
by either setting the DOC_TYPE variable or by using the new {{type}}
parameter to the {{FILT:title}} filter. For example, if you want
the title "Urgent Memo" rather than the default "MEMORANDUM" for
a memo, you can now do the following:

E:!init OPT_STYLE="memo"
E:!block title; type="Urgent Memo"
E:{{usual name-values pairs go here ...}}
E:!endblock

The {{FILT:title}} filter now also supports a {{format}} parameter
which can be used to tune the column widths, when necessary.

RTF can now be generated via FrameMaker by using the new {{sdf2fmrtf}}
alias, i.e. the command is (say):

E:   sdf -2fmrtf myfile.sdf

When RTF is generated via FrameMaker, Word's standard style names are
used, where possible. This makes it easier to import the RTF file
into an existing Word document.

Lists of tables and lists of figures can now be generated for normal
documents, i.e. it is no longer necessary to use a FrameMaker book
to build these lists.

The new variable {{TXT_MARGIN}} can be used to control the width
for {{txt}} output. Likewise, the new variable {{POD_MARGIN}} can
be used to control the width of tables for {{pod}} format.

The new {{bugtrack}} module can be used to build a simple
bug tracking system like SDF's bug database.

The new {{namevalues}} macro can be used to output a set of
name-value pairs for an object. The parameters are:

* the class name
* the object name
* a comma-separated list of attribute names.

For example:

E:!namevalues 'bugs'; 'sd0001'; 'Priority,Status,Type'

Finer control over object catalog formatting is now available
via the new {{style}} and {{headings}} attributes. {{style}}
is the table style to use. The default value is {{plain}}.
If {{headings}} is set, column headings are output.
(By default, they are not.)


H3: Easier column widths

SDF now supports {{dynamic}} column widths for paper documentation, i.e.
if a width is not specified for a column, then the column is
sized based on the text within it and the space available.
Proportional column widths are also supported.

The {{format}} attribute of the {{FILT:table}} filter is either:

* a single number, in which case each digit represents 10% of the
  width available to the table, or

* a comma-separated list of column width specifications.

Examples of the column width specifications now supported are given below.

!block table
Value       Meaning
30pt        an exact size (other supported units are cm, mm, " and in)
30%         a percentage of the size available
30          a percentage of the size available (% is implicit)
10-20       dynamic size between 10% and 20% of the total width
-20         dynamic size between 0% and 20% of the total width
10-         dynamic size between 10% and 100% of the total width
-           dynamic size between 0% and 100% of the total width
3*          3 units of the remaining space
*           same as 1*
!endblock

For example, in the table below, the second column will be
twice the size of the last column.

!block example
!block  table; format="20,2*,10,*"
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock
!endblock

The output is:

!block  table; format="20,2*,10,*"
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock

If a column is not given a size, the following rules are used:

^ The last unspecified column size is implicitly '*' (i.e. the rest),
  unless the {{narrow}} attribute is set, in which case the size
  is implicitly '-' (i.e. as much as needed).

+ The other unknown sizes are implicitly '-'.

For example, the first and third columns in the table below
will be dynamically sized. The first column will take as
much space as required and the last column will expand so
that the table takes the full width of the text area.

!block example
!block  table; format=",30,,10"
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock
!endblock

The output is:

!block  table; format=",30,,10"
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock

However, in the example below, each column will only take
as much space is required, making the table narrower
than it would be otherwise.

!block example
!block  table; narrow
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock
!endblock

The output is:

!block  table; narrow
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock

If an = character is used in place of a - character for a column
width, then those columns will be equalised in size.
For example, the second and forth columns in the table
below will be made equal in size.

!block example
!block  table; format="20,5=30,10,="
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock
!endblock

The output is:

!block  table; format="20,5=30,10,="
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock

Note: As previously, the {{format}} parameter has no impact on HTML
generation, i.e. all columns in HTML remain dynamically sized.
Dynamic sizing is also ignored for {{txt}} and {{pod}} targets.


H3: Heading/footing rows for tables

The {{FILT:table}} filter now supports the following attributes:

* {{headings}} - the number of heading rows at the top of the table
* {{footings}} - the number of footing rows at the end of the table.

If the {{headings}} attribute is not defined, then as previously done,
the column headings are generated using the column names given on
the {{parsing}} line. For example, the column headings in the table
below will be {{Name}} and {{Age}}:

!block example
!block table
Name    Age
Bill    42
!endblock
!endblock

Alternatively, if the {{headings}} attribute is defined,
then that number of {{data}} rows are used as the column headings,
i.e. the parsing line is not used to build the column headings.
For example, the column headings in the table below will be
{{"Title"}} and {{Age}} (remembering that a filter attribute is
implicitly given the value 1 is no value is supplied).

!block example
!block table; headings
A       B
"Title" Age
Bill    42
Sally   23
!endblock
!endblock

Likewise, the column headings below will be {{Preferred Title}} and
{{Likely Age}} with each heading taking 2 rows.

!block example
!block table; headings=2
A           B
Preferred   Likely
Title       Age
Bill        42
Sally       23
!endblock
!endblock

Collectively, these new attributes improve things in several ways:

* heading rows can now include non-alphanumeric characters
* macros (e.g. change bars) can be applied to heading rows
* multi-line heading and footing rows are now supported.


H3: Table positioning

The horizontal alignment and vertical placement of a table can be
controlled by setting the {{align}} and {{placement}} parameters
of the {{FILT:table}} filter respectively.
The permitted {{align}} values are:

!block table
Value       Meaning
Left        left-align the table
Center      center the table
Right       right-align the table
Inner       align the table with the inner margin
Outer       align the table with the outer margin
!endblock

Note: The {{wide}} parameter changes the left indent of a table
to include the sidehead of a page. Therefore, the {{wide}}
parameter will impact the horizontal positioning of any
table which is not right-aligned.

The permitted {{placement}} values are:

!block table
Value       Meaning
Float       next column if necessary
Pagetop     top of the next page
Columntop   top of the next column
Lefttop     top of the next left-hand page
Righttop    top of the next right-hand page
!endblock


H3: Table filtering and sorting

Tables can now be filtered and sorted by using the new {{where}}
and {{sort}} attributes of the {{FILT:table}} filter.
These attributes are also supported by the class filters (e.g.
terms, references).
In either case, filtering is done before sorting.

The {{where}} attribute takes an expression which is evaluated
for each record. Special symbols available are:

!block table
Symbol      Meaning
$_          the current record
$o{"xyz"}   the value of column xyz
!endblock

{{sort}} takes a comma-separated list of column names to sort on.
If no columns are specified, the data is sorted using
all columns in the order in which they appear. All sorting
is done alphabetically - numeric sorting is not supported.


H3: Landscape tables

Landscape tables are now supported via the {{landscape}} parameter of
the {{FILT:table}} filter. The value is the height allocated to
the area in which the table is placed. If a unit is not specified,
the value is assumed to be a percentage of the text column height.
For convenience, a value of 1 implies a full page table.
Some examples are given below.

!block table
Value               Meaning
landscape="50pt"    height allocated to table is 50 points
landscape="50%"     half page table
landscape=50        half page table (% is the default units)
landscape=1         full page table (1 implies 100%)
landscape           full page table (syntactic shorthand for above)
!endblock

Note: This feature is currently {{B:use at your own risk}}.
In particular, long tables and table titles confuse it badly.
Furthermore, the {{align}} and {{placement}} parameters are
effectively ignored for landscape tables.


H3: Column alignment

The {{colaligns}} parameter of the {{FILT:table}} filter can now be used
to control the alignment of text within columns of a table.
For example:

!block example
!block  table; colaligns="LCCR"
Name    Column2             Column3     Column4
A       B                   C           1.0
X       Hello dear world    Y           10.2
!endblock
!endblock

The output is:

!block  table; colaligns="LCCR"
Name    Column2             Column3     Column4
A       B                   C           1.0
X       Hello dear world    Y           10.2
!endblock

The value of {{colaligns}} is usually a sequence of the letters
{{L}}, {{C}} and {{R}} (which mean what one would expect).
If you prefer, a comma-separated list of the values {{Left}}, {{Center}}
and {{Right}} can be specified. For example:

!block example
!block  table; colaligns="Left,Center,Center,Right"
Name    Column2             Column3     Column4
A       B                   C           1.0
X       Hello dear world    Y           10.2
!endblock
!endblock


H3: Cell attributes

Cells within a table can now be given attributes by preceding the
cell value with a semicolon-separated list of name-value pairs
enclosed in square brackets. For example:

!block example
!block  table; colaligns="LCCR"
Name    Column2             Column3     Column4
A       [align=Left]B       C           [bgcolor=Green]1.0
X       Hello dear world    Y           [bgcolor=Red]10.2
!endblock
!endblock

The output is:

!block  table; colaligns="LCCR"
Name    Column2             Column3     Column4
A       [align=Left]B       C           [bgcolor=Green]1.0
X       Hello dear world    Y           [bgcolor=Red]10.2
!endblock

The cell attributes supported are given below.

!block table; groups
Name        Value
General:
align       horizontal alignment (Left, Center, Right)
valign      vertical alignment (Top, Middle, Bottom, Baseline)
cols        the number of columns this cell spans (default is 1)
rows        the number of rows this cell spans (default is 1)
bgcolor     background colour of cell (see below)
PS only:
fill        background colour fill percentage
truling     ruling setting for top of cell
bruling     ruling setting for bottom of cell
lruling     ruling setting for left of cell
rruling     ruling setting for right of cell
angle       angle of text (0, 90, 180, 270)
HTML only:
nowrap      disable word wrap for this cell
Special:
sdf         treat the cell text as SDF (rather than as phrase text)
tag         phrase tag to apply to cell text
paratag     paragraph style to apply to cell text
!endblock

For PS (i.e. MIF) generation, the supported colour values are
{{Black}}, {{White}}, {{Red}}, {{Green}},
{{Blue}}, {{Yellow}}, {{Cyan}} and {{Magenta}}.
If a different colour is specified, it is ignored.
The supported fill values are 100, 90, 70, 50, 30, 10 and 3.
If a fill value is not specified, 100% fill is used.

For HTML generation, any of the HTML colours names
(including those supported for PS generation) or the "#rrggbb" form
can be used.

The permitted ruling values are {{Vthin}}, {{Thin}}, {{Medium}},
{{Thick}} and {{Double}}.

The {{sdf}}, {{tag}} and {{paratag}} attributes control the way in which the
cell text is converted to SDF:

^ If {{sdf}} is set, the cell text is already SDF.
+ Otherwise if {{tag}} is set, the SDF paragraph is paratag:E<2{>tag:textE<2}>.
+ Otherwise, the paragraph is paratag:text.

{{tag}} is usually set via the {{tags}} or {{groups}} parameters
of the {{FILT:table}} filter.

Note: {{paratag}} is not yet implemented.


H3: Spreadsheet calculations

{{The spreadsheet expression evaluator and the documentation below
was written by Tim Hudson ({{EMAIL:tjh@cryptsoft.com}})}}.

Spreadsheet style calculations have been introduced into SDF using the
standard {{E<2[> E<2]>}} syntax with a prefix of {{+}} (or {{=}}) indicating
that the expression is to be evaluated by the calculation routines.

This extension has been loosely modelled on [[Microsoft]] {{Excel}}[[r]]
in terms of the initial functions supported and the syntax used.

Note: Calculation support for a table can be disabled by adding in 
an attribute of {{nocalcs}} (otherwise the pointers required to table
data that are needed when doing spreadsheet calculations occur for each
table cell).

Each {{cell}} in a table has an {{cellid}} which is made up of a
single uppercase letter indicating the column index and a number
indicating the row index (counting from 1 and excluding the
heading rows). The upper left {{cell}} is hence {{A1}}.

An example grid indicating {{cellid}}s:

!block table; narrow
Title1:Title2:Title3:Title4:Title5
A1:B1:C1:D1:E1
A2:B2:C2:D2:E2
A3:B3:C3:D3:E3
...:...:...:...:...
A100:B100:C100:D100:E100
!endblock

A range of {{cellid}}s is specified using the syntax {{:cellid1:cellid2}}.
For example: {{:A1:C1}} is exactly the same as {{A1,B1,C1}}

An expression consists of a combination of standard Perl operators
and spreadsheet functions and {{cellid}}s or {{cellid}} ranges.

Standard Perl operators include:

* + - * /

Spreadsheet functions use the syntax {{FUNCTION(ARG1,ARG2,...ARGN)}}.

The following functions are supported:

* {{AVERAGE}} - the average - SUM(ARGS)/COUNT(ARGS)
* {{SUM}} - the sum of the args - same as ARG1+ARG2+...+ARGN
* {{MIN}} - the minumum argument value 
* {{MAX}} - the maximum argument value
* {{COUNT}} - the number of arguments
* {{PRODUCT}} - the product of the args - same as ARG1*ARGN*...*ARGN
* {{ROWSUM}} - the {{SUM}} of all the cells in the row to the left of 
               the current cell
* {{ROWPROD}} - the {{PRODUCT}} of all the cells in the row to the 
                left of the current cell
* {{COLSUM}} - the {{SUM}} of all the cells in the column above the 
               current cell
* {{COLPROD}} - the {{PRODUCT}} of all the cells in the column above the 
                current cell

A simple example:

!block example
!block table; style="grid"
Count         Price        Total
10            5            [\[=A1*B1]\]
15            5.23         [\[=ROWPROD]\]
[\[=COLSUM]]   [\[=B1+B2]\]   [\[=COLSUM]\]
!endblock
!endblock

Which generates the result below. (Ok, summing two prices is
meaningless, but it illustrates the syntax.)

!block table; style="grid"
Count         Price        Total
10            5            [[=A1*B1]]
15            5.23         [[=ROWPROD]]
[[=COLSUM]]   [[=B1+B2]]   [[=COLSUM]]
!endblock

NB: 
values are available until the next table is processed so
you can refer to data inside {{normal}} paragraphs after 
the table like this [\[=A1]\] which evaluates to [[=A1]]
NE:

A spreadsheet expression will recursively evaluate any expressions
contained in {{cells}} that are used in an expression. In the example
above, the expression in {{cell}} {{C3}} depends on the results of the
expression in {{cell}} {{C1}} and {{C2}}.


H3: Arbitrary page sizes

Generally speaking, SDF can now support arbitrary page sizes.
The catch is that the page size must now be specified up front
via the OPT_PAGE_SIZE variable on the {{MAC:init}} line or via
{{CMD:sdf}}'s -S option. (Previously, the (no longer
supported) DOC_PAGE_SIZE variable could be
specified anywhere in the document.)

The supported values of OPT_PAGE_SIZE are given below.
The default page size is {{global}}.

!block table
Name    Width   Height  Comment
global  21.0cm  11.0in  will fit on either A4 or letter
A3      29.7cm  42.0cm 
A4      21.0cm  29.7cm
A5      14.8cm  21.0cm
B4      25.7cm  36.4cm
B5      17.6cm  25.0cm
letter  8.5in   11.0in
legal   8.5in   14.0in
tabloid 11.0in  17.0in
!endblock

Note: {{global}} is 0.23" narrower than {{letter}} and 1.76cm shorter
than {{A4}}.

New page sizes can be defined in {{FILE:sdf.ini}}.
A rotated version is also available for each page size.
Rotated sizes are named with an appended R.
For example, the rotated A4 size is called A4R.


H3: Headers and footers

SDF now provides 3 ways of controlling headers and footers:

* The OPT_HEADINGS variable (high level control)
* PAGE_{{page}}_{{HF}}_{{ICO}}{{n}} variables (medium level control)
* PAGE_{{page}}_{{HF}} macros (low level control)

:where:

* {{page}} is FIRST, RIGHT or LEFT
* {{HF}} is HEADER or FOOTER
* {{ICO}} is INNER, CENTER or OUTER
* {{n}} is the line number within the header or footer (usually 1 or 2).

The meaning of each page type is explained below.

!block table
Page    Usage
FIRST   the first page in the document
RIGHT   the page used for single-sided documents and the right hand side of double-sided documents
LEFT    the left hand side of double-sided documents; ignored for single-sided documents
!endblock

Supported OPT_HEADINGS values and their meanings are given below:

!block table
Value       Meaning
0           no header, no footer
1           single line header, single line footer
2           two line header and two line footer
3           two line header and three line footer
4           two line header and four line footer
!endblock


H3: Header/footer special tags

The following special tags are supported within headers and footers:

!block table
Tag             Meaning
PAGENUM         current page number
PAGECOUNT       highest page number
PARATEXT        paragraph text (e.g. Hardware requirements)
PARANUM         paragraph number (e.g. Appendix A)
PARANUMONLY     paragraph number only (e.g. A)
PARASHORT       value of {{short}} attribute of paragraph
PARALAST        text of last paragraph on page with the nominated style
!endblock

The {{PARA*}} tags require a comma separated list of paragraph styles
to be nominated as the text of the phrase, e.g. E<2{>PARATEXT:H1,A1,P1E<2}>.

The {{PARASHORT}} tag is useful for placing an alternative heading
in a header, say. For example, you might set up your header to include
E<2{>PARASHORT:H1E<2}> and have the following text in your document:

E:  H1[short='Getting started'] Getting started with SDF

The {{PARALAST}} tag is useful for producing dictionary-like headers.


H3: Header/footer borders

High level control over header/footer borders is provided by
the OPT_BORDERS variable. The supported values and their meanings
are given below:

!block table
Value       Meaning
0           no header/footer borders
1           line below header, line above footer
2           lines above and below header, line above footer
!endblock

Finer control is available by setting the following variables:

!block table
Name                         Value
PAGE_{{page}}_HEADER_BORDER  border specification string
PAGE_{{page}}_FOOTER_BORDER  border specification string
!endblock

where {{page}} is either FIRST, RIGHT or LEFT.

A {{border specification}} string is a comma-separated list
of attributes which collectively describe the border.
The format of each attribute is name[=value].
The supported attributes are:

* {{top}} - a line above the area
* {{bottom}} - a line below the area
* {{box}} - a box around the area
* {{radius}} - for a box, the radius of the corner.

For {{top}}, {{bottom}} and {{box}}, the value of the
attribute is the line width in points.


H3: Page backgrounds

In order to support fancy background images, SDF supports
the following variables:

!block table
Name                         Value
PAGE_{{page}}_BACKGROUND     the logical image name
!endblock

where {{page}} is either FIRST, RIGHT or LEFT.

When [[FrameMaker]] is being used to generate [[PostScript]],
the image name is mapped to a master page called {{backgrnd}} within a file
called {{backgrnd}}.mif.

Note: At the moment, objects from the master page
(excluding TextRects) are directly transferred to the
generated MIF file. This means that objects in the
lower right hand corner of an A4 master page will not
will be positioned nicely if the paper size is changed
to A5, say.


H3: Page layout variables

Page margins can now be controlled via the following variables:

!block table
Name                Value
OPT_MARGIN_TOP      size of the margin above the header, if any
OPT_MARGIN_BOTTOM   size of the margin below the footer, if any
OPT_MARGIN_INNER    size of the inner margin
OPT_MARGIN_OUTER    size of the outer margin
!endblock

The positioning of headers and footers can now be controlled via
the following variables:

!block table
Name                         Value
PAGE_{{page}}_HEADER_HEIGHT  height of the area allocated to the header
PAGE_{{page}}_HEADER_GAP     size of the gap between the header area and the text area
PAGE_{{page}}_FOOTER_HEIGHT  height of the area allocated to the footer
PAGE_{{page}}_FOOTER_GAP     size of the gap between the text area and the footer area
!endblock

where {{page}} is either FIRST, RIGHT or LEFT.

After the margins and header/footer are allocated, the remaining text
area contains 1 or more text columns and an optional side head.
The layout of these is controlled by the following variables:

!block table
Name                Value
OPT_COLUMNS         numbers of text columns
OPT_COLUMN_GAP      space between columns
OPT_SIDEHEAD_WIDTH  size allocated to the sidehead
OPT_SIDEHEAD_GAP    space between the side-head and first text column
!endblock

The following read-only variables provide information on the
page layout:

!block table
Name                    Value
DOC_PAGE_WIDTH          width of page
DOC_PAGE_HEIGHT         height of page
DOC_FULL_WIDTH          width of text area including the side-head
DOC_TEXT_WIDTH          width of text area available for text columns
DOC_TEXT_HEIGHT         height of text area
DOC_COLUMN_WIDTH        width of a text column
!endblock

All the information variables are in units of points.
The text area is the area allocated to text, excluding the header
and footer (if any) on the RIGHT page.


H3: Page control within a book

When a book is being generated, each component of the book
may have its own FIRST, RIGHT and LEFT pages, i.e. all of
the macros and variables above support an extended set of
{{page}} values {{component}}_{{FRL}} where:

* {{component}} is the name of the component
* {{FRL}} is FIRST, RIGHT or LEFT.

The component names supported are given below.

!block table
Name                Meaning
FRONT               the cover component
PRETOC              components before the contents
TOC                 the table of contents
LOF                 the list of figures
LOT                 the list of tables
PRECHAPTER          components before the chapters
CHAPTER             a normal chapter
APPENDIX            an appendix
PREIX               components before the index
IX                  the index
!endblock

If a component does not have a component-specific macro/variable
defined, then the generic macro/variable is used.


H3: FrameMaker templates are no longer required

Previously, SDF produced MIF documents by merging
generated MIF paragraphs into FrameMaker templates.
This approach was easy to implement but maintaining
the FrameMaker templates was difficult as
every look required several templates for {{each}} page size!

FrameMaker templates can still be used but are no longer
needed, nor recommended. Instead, the definitions of
paragraph styles, phrase styles, table styles and graphic
(border) frames is now done via {{SDF templates}}.
SDF templates have the following advantages:

^ Templates can be parameterised so that
  a single template can support any number of page sizes.

+ Each look only requires a single template, rather than
  a template for each component of a FrameMaker book.

+ Templates can inherit definitions from other templates,
  making it much easier to create and maintain templates.

+ Each definition supports inheritance, so a new paragraph
  style, say, can be defined in terms of the differences
  between it and a parent style.

The new {{sdtgen}} command can be used to build an SDF
template from a FrameMaker one. Typically, {{sdtgen}} is
used to create an initial template which is then simplified via
definition inheritance and template inheritance.


H3: Event processing enhancements

The following new symbols are now available within event processing
for paragraphs:

!block table
Symbol      Meaning
$level      the current heading level ({{before}} this paragraph)
$prev_style the style of the previous paragraph
$prev_text  the text of the previous paragraph
%prev_attr  the attributes of the previous paragraph
!endblock

These symbols make it much easier to do some really nice things.
For example, the following rule can be used 
to put level 2 headings on a new page unless
the heading is the first one within a chapter:

!block example
!on paragraph '[HAP]2';; if ($level != 1) {$attr{'top'} = 1}
!endblock


H2: Fixes

Tim Hudson has contributed a number of fixes to this release including:

* this version should now work with Perl 5 again - the previous
  version triggered a Perl 5 syntax error

* the {{IMPORT}} pragma now supports filename extension adding ala
  the {{MAC:import}} macro

* centred figures now work as expected in HTML

* numerous Windows help generation fixes/enhancements.

Other fixes include:

* the renaming of xx.out.ps to xx.ps is now done by {{CMD:sdfbatch}},
  so failures (due to lack of disk space, say) are now handled much
  better than they previously were

* topics mode now generates an error if the heading of a topic
  is duplicated within a file (see {{SECT:Miscellaneous things}} above)

* headings containing a ? character should no longer cause problems

* some bugs in {{CMD:sdfget}}'s extraction of documentation from C code
  have been fixed (thanks to Keith Ponting).

H2: Incompatibilities

As the default page size is now {{global}} rather than {{A4}},
page breaks may occur slightly earlier than they previously did.
The advantage of changing to {{global}} is that documents
should now print successfully on US letter paper.

Memos, faxes, minutes and newsletters no longer have the company
address in the top right hand corner. (I'll fix this soon, but it
is not a high priority at the moment.)

As {{txt}} and {{pod}} outputs use a different algorithm for
deciding column widths when a table does not have a format parameter,
some table cells may no longer fit when these output formats are used.

The table attribute previously called {{headings}} has been
renamed to {{parseline}} to better reflect its purpose and to
make way for the new meaning.

The DOC_TOCTEXT variable has been renamed to DOC_TOC_TITLE.
The DOC_TOCGRAPHIC variable has been renamed to DOC_TOC_GRAPHIC.

The {{newsletter}} style has been renamed to {{newslttr}}.

{{overhead}} is now a look, rather than a style. The overhead look
is untested and rarely used, so use it at your own risk.

The aliases {{sdf2htmls}} and {{sdf2txts}} have been renamed to
{{sdf2fmhtml}} and {{sdf2fmtxt}} respectively.

{{FILE:/usr/local/bin/perl5}} is now the default perl interpreter used.
side of double-sided documents; ignored for single-sided documents
!endblock

Supported OPT_HEADINGS values and their meanings are given below:

!block table
Value       Meaning
0           no header, no footer
1           single line header, single line footer
2           two line header and two line footer
3           two line header and three line footer
4           two line header andsdf-2.001/doc/release/2000b7.html010064400042570001753000000266740672242654500160360ustar00iancmtr00000400000236






SDF 2.001: SDF Release Notes: 2.000beta7




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    14. 2.000beta7
    

    Enhancements | Fixes | Incompatibilities
    

    

    14.1. Enhancements
    

    There are lots of new things in this version including:
    


    Details are given below.
    

    14.1.1. Topics mode for HTML
    

    SDF can now generate a set of HTML topics, rather than a single HTML file. The command is:
    

       sdf -2topics myfile.sdf

    

    If you want to manually control how a document is split into topics, simply include other sdf files which contain headings. These manual topics, if any, can be supplemented with automatically generated topics. By default, level 1 headings are used as topic breaks, in addition to the manual ones. The -n option can be used to change this:
    

      

    • -n0 disables autosplitting

    • -n2 uses level 1-2 headings to autosplit

    • -n3 uses level 1-3 headings to autosplit

    • etc.
    

    To make it easy to navigate around the topics, SDF generates a default header and footer for a topic which supports jumping to the:
    

      

    • main topic (i.e. the contents)

    • parent topic

    • previous topic

    • next topic.
    

    14.1.2. HTML headers and footers
    

    These macros give you total control over the headers and footers used:
    

      

    • HTML_HEADER - header on a HTML document (or main topic)

    • HTML_FOOTER - footer on a HTML document (or main topic)

    • HTML_TOPIC_HEADER - header on a HTML topic

    • HTML_TOPIC_FOOTER - footer on a HTML topic.
    

    The default implementation of these macros is in html.sdm in the kernel library. The default versions of these macros use the variables below, if they are set. On most occasions, useful headers and footers can be obtained by simply setting these variables:
    

      

    • HTML_URL_HOME - URL of the home page

    • HTML_URL_CATALOG - URL of the catalog

    • HTML_URL_SEARCH - URL of the search facilities.
    

    14.1.3. HTML control variables
    

    To fine tune HTML output, the following variables are useful:
    

      

    • HTML_BG_COLOR - the background colour of the page

    • HTML_BG_IMAGE - the background image of the page

    • HTML_TEXT_COLOR - the colour of normal text

    • HTML_LINK_COLOR - the colour of unvisited links

    • HTML_VLINK_COLOR - the colour of visited links.
    

    To set a colour, use the RGB (red-green-blue) value as used by HTML. For example:
    

       !define HTML_BG_COLOR "ffffff"

    

    For convenience, a number of variables are defined for common colours:
    

      
COLOR_WHITE

      
COLOR_BLACK

      
COLOR_RED

      
COLOR_GREEN

      
COLOR_BLUE

      
COLOR_YELLOW

      
COLOR_CYAN

      
COLOR_MAGENTA.
    

    These are used as follows:
    

       !define HTML_BG_COLOR COLOR_WHITE

    

    14.1.4. Macros inside tables
    

    Macros can now be used inside tables. In particular:
    

      

    • rows can now be conditionally included or excluded

    • rows can be marked as changed.
    

    For example:
    

    !block table
Code    Description
BTW     By the way
!block changed
RTFM    Read the (fine) manual
!endblock
!if ALL_TERMS
SOS     Save our souls
!endif
!endblock

    

    14.1.5. Wide tables
    

    The table filter now supports a new attribute called wide. When it is used, the table spans the side-head in addition to the text column.
    

    14.1.6. Figure enhancements
    

    The import macro now supports an align attribute, which is passed into the generated HTML. This can be used in combination with the clear macro to control how figures are aligned with text in HTML.
    

    For example:
    

    !import "mylogo"; align="right"
Some text.
!clear

    

    HTML's alt attribute is now also supported by the import macro.
    

    14.1.7. Special characters
    

    Special characters can now be entered using {{CHAR:xxx}} where xxx is either:
    

      

    • a symbolic name

    • a character code (HTML only).
    

    The symbolic names supported are given below.
    

    

    

Name


Description


    

    

bullet


 


    

    

c


copyright symbol


    

    

cent


 


    

    

dagger


 


    

    

doubledagger


 


    

    

emdash


a hyphen which is the width of the point size


    

    

endash


a hyphen which is half the width of the point size


    

    

emspace


a space which is the width of the point size


    

    

enspace


a space which is half the width of the point size


    

    

nbdash


a non-breaking hyphen


    

    

nbspace


a non-breaking space


    

    

nl


newline


    

    

pound


 


    

    

r


registered trademark


    

    

tab


tab character


    

    

tm


trademark


    

    

yen


 


    

    


    For convenience, variables with the same name are predefined. This makes it easy to include a special character. For example:
    

       Copyright [\[c]\] 1996, Us Pty Ltd.

    

    
Note: Some target formats do not yet support all of these characters. For example, HTML does not yet support Em or En spaces. In these cases, sdf will do the best it can (e.g. use a normal space for enpsace and emspace).

    

    14.1.8. Cross-references
    

    Cross-references are now supported via the xref phrase attribute. For example:
    

     Refer to page {{N[xref="pagenum"] Samples}} for more samples.

    

    The value specifies the cross-reference style to use. The phrase text is used to find the target location. The predefined styles are given below.
    

    

    

Name


Value


    

    

pagenum


the page number


    

    

paratext


the paragraph text


    

    

paratag


the (FrameMaker) paragraph tag


    

    

paranum


the paragraph number (e.g. Appendix A)


    

    

paranumonly


the paragraph number only (e.g. A)


    

    

section


section paranumonly, paratext, on page pagenum


    

    


    New styles can be added by using the xrefs configuration filter. See mif.sdm in the kernel directory for examples.
    

    
Note: Other than PostScript, most targets ignore cross-references.

    

    14.1.9. Other goodies
    

    New macros include:
    

      

    • output - dynamically change the output file used
    

    New filters include:
    

      

    • changed - mark a block as changed (shorthand for sdf; changed)

    • topics - include a set of sub-topics

    • sections - create section jumps for html and hlp outputs

    • note - format a note

    • quote - format a quotation

    • address - format an address

    • ascii_graphic - format an ASCII graphic.
    

    The current directory is now searched first for the configuration library, i.e. if OPT_CONFIG is abc, sdf first looks for ./abc.sdm before searching for abc.sdm in a directory called abc on the search path.
    

    

    14.2. Fixes
    

    The copy number field on the mincom cover page has been fixed.
    

    The Limitations & Future Directions heading in sdfget.sdm has been changed to Limitations and future directions.
    

    

    14.3. Incompatibilities
    

    The objects attribute of the table filter is now called tags.
    

    The sections filter now generates SECT jumps for each paragraph within the block, provided the output is html or hlp. To include sub-topics (sub-sections), use the new topics filter.
    

    When pretty-printing files using sdf, use the -N option to control line numbering. The -n option is now used to specify the level when autosplitting into HTML topics.
    

    The message macro has been simplified - the message type is now an optional second parameter.
    

    The obj* configuration filters have been renamed to phrase* to better reflect their purpose. (This shouldn't affect normal documents.)
    

    The cfg_lang configuration filter has been renamed to langdefs.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



gure enhancements

    
sdf-2.001/doc/release/2000b7c.html010064400042570001753000000074450672242653100161670ustar00iancmtr00000400000236






SDF 2.001: SDF Release Notes: 2.000beta7c




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    11. 2.000beta7c
    

    Enhancements | Fixes | Incompatibilities
    

    

    11.1. Enhancements
    

    The aliases CC and cc have been added for C++ pretty printing. This makes it easier to pretty print files with these extensions. Pretty printing of CORBA IDL is also now supported.
    

    A number of improvements have been made to improve the formatting of document catalogs:
    

      

    • the TXT field has been added for text documents

    • the DOC field has been added for Word documents

    • REFNUMONLY:Reference can now be used to display just the code and version parts of a reference code

    • the Printer field has been renamed to Printdoc to match the name of the script in cgi-bin (the old name is still supported for backwards compatibility).
    

    If you use the Printdoc field, the following variables control parameter values passed to the script:
    

      

    • PRINTDOC_ROOT (mandatory) - the absolute URL of the directory containing the documents

    • PRINTDOC_BACK (optional) - the absolute URL of the file to jump back to. (If not set, the html file matching the input file in the PRINTDOC_ROOT directory is used.)
    

    Within the subsections macro, an empty section name now causes a new-line to be added at that point in the jump line output for HTML.
    

    The text of a phrase can now be changed by setting the text attribute. (This is occasionally useful in event processing.)
    

    

    11.2. Fixes
    

    If a file doesn't exist, empty output files are no longer created. Some bugs associated with filenames containing dots have also been fixed.
    

    The nl character now works for ps and mif targets.
    

    Several bugs were fixed in the formatting of document catalogs:
    

      

    • if a file doesn't exist, an empty date is now output

    • detection of special file formats (e.g. PDF, TXT) has been improved

    • the page count for PostScript generated by Word is no longer 0

    • the back parameter to the printdoc script is no longer hard-coded.
    

    Memos converted to html no longer have a table of contents unless one is explicitly requested.
    

    REF[qsd] now works for any mincom document.
    

    

    11.3. Incompatibilities
    

    None.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/release/2000b11.html010064400042570001753000000205050672242644400160720ustar00iancmtr00000400000236






SDF 2.001: SDF Release Notes: 2.000beta11




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    5. 2.000beta11
    

    Enhancements | Fixes | Incompatibilities
    

    

    5.1. Enhancements
    

    The enhancements are:
    


    Further details are provided below.
    

    5.1.1. Documentation improvements
    

    The documentation has been improved in the following ways:
    

      

    • it is now supplied in PDF format (in addition to PostScript and HTML)

    • the white paper, quick reference and tutorials are now single HTML documents, rather than sets of topics

    • the home page has been improved

    • the FAQ has been expanded and added to the catalog.
    

    5.1.2. Better Perl documentation
    

    The new mkpldocs program can be used to build the Perl documentation suite. Usage is:
    

      cd <perl_distribution_directory>
  mkpldocs all

    

    The perl configuration library now generates better looking HTML with relative URLs. As such, the documentation can be easily moved after it is generated.
    

    See http://www.mincom.com/mtr/perl/pod/perl.html for a publicly available version of the HTML generated by SDF for Perl 5.004_01. If you want a local copy, you can download it in either tar.gz or zip format. The URLs are:
    


    5.1.3. Multi-line records in tables
    

    Records in tables can now be continued onto the next line by terminating the line with a backslash. Like !-style macros:
    

      

    • exactly 2 terminating backslashes means a real backslash

    • N (N >= 3) terminating backslashes means N-1 real backslashes with continuation.
    

    5.1.4. Better man page support
    

    The -2man option nows sends output to standard output, rather than to a .man file. This improves compatibility with pod2man and makes it easier to do things like:
    

      sdf -2man faq.sdf | nroff -man | less

    

    The following variables can now be used to change the headers and footers generated for man pages:
    

    

    

Variable


Meaning


    

    

DOC_PRODUCT


the center string in the header (e.g. Simple Document Format)


    

    

DOC_PROJECT


the release name for the product (e.g. SDF 2.000beta11)


    

    

DOC_SECTION


the section this man page is in


    

    


    These variables are typically defined in a configuration library. You can also provide them on the command line using the -D and/or -f options like this:
    

      sdf -2man -DDOC_SECTION=3 ...
  sdf -2man -fsection=3 ...

    

    5.1.5. Better PDF support
    

    PDF support has been improved. To generate PostScript (via FrameMaker) and distill it to PDF, the new -2pdf option can be used like this:
    

      sdf -2pdf mydoc.sdf

    

    If PostScript is being generated via a FrameMaker book or via pod2ps, the -zpdf option can be used like this:
    

      sdf -2book -zpdf mydoc.sdf
  sdf -2podps -zpdf mydoc.pdf

    

    
Note: The -2pdf option assumes that you have Adobe Acrobat's distill program on your path.

    

    5.1.6. More flexible embedded documentation support
    

    Mark Stavar's enhancements to SDF's embedded documentation support have now been integrated, but are not yet documented. These enhancements make it possible to put documentation into buffers which are formatted independently of the main one. Amongst other things, this makes it possible to have subtopics for each procedure/method/function in a library, each with its own set of Interface, Description, Examples, etc.
    

    When time permits, I'll put together a tutorial explaining the different ways SDF can be used for embedded documentation. Until then, if you need further information on the multiple buffer approach, send me some email.
    

    5.1.7. SDF expressions within inline blocks
    

    SDF expressions are now supported within text processed by the inline filter thanks to a patch from Tim MacKenzie. For example,
    

    !define VERB "is"
...
!block inline; expand
<P>
This HTML [[VERB]] expanded.
!endblock

    

    

    5.2. Fixes
    

    Most of the links within the Perl documentation should now work correctly.
    

    S phrases (i.e. phrases with non-breaking spaces) now work correctly for HTML and MIF formats. The nbsp variable has also been introduced as another way to insert non-breaking spaces.
    

    HTML escapes (E phrases and CHAR phrases) are now supported by the mif and plain text drivers.
    

    The default language used for pretty printing .h files is now C++, rather than C.
    

    Non-last multi-line cells are now working correctly for delimited format (but aren't yet supported for fixed-width format).
    

    Included some patches from Tim MacKenzie for:
    

      

    • handling filenames with non-alphanumeric characters like -

    • removing the need to have mif2rtf and sdfbatch on your path

    • improving compatibility with FrameMaker 4

    • better packaging of Pod:Sdf.pm.
    

    To fix the formatting of MIMS specifications, the +ms option has been introduced.
    

    When a FrameMaker book is generated:
    

      

    • the list of figures, list of tables and index, if any, should now appear in the table of contents

    • the last chapter now has a terminating line for infomap documents.
    

    Missing libraries and modules now create a warning rather than an error.
    

    The default footer for manuals has been changed to:
    

      

    • include the project name, if any

    • exclude the status if it's Final.
    

    

    5.3. Incompatibilities
    

    None.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/release/2000.sdf010064400042570001753000000136500647630644200154020ustar00iancmtr00000400000236H1: 2.000

!subsections "Enhancements,Fixes,Incompatibilities"

H2: Enhancements

As this is the first public production release of SDF,
the focus has been to fix bugs and improve the documentation.
The enhancements are:

!block sections
^ Better documentation
+ Better packaging
+ Better support for non-English languages
+ Table enhancements
+ Object management enhancements
+ Example/verbatim enhancements
+ Miscellaneous things.
!endblock

H3: Better documentation

The following documents have been improved:

* {{DOC: The SDF Document Development System}}
* {{DOC: SDF Reference}}.

The {{DOC: SDF Web Site}} has also been improved by the addition of
the following sections:

* {{DOC: SDF Latest News}}
* {{DOC: SDF Template Catalog}}
* {{DOC: SDF Resource Center}}
* {{DOC: SDF Sample Showcase}}.

H3: Better packaging

The PostScript and PDF versions of the documentation have been
removed from the core distribution making it substantially smaller.
The PostScript and PDF documents can still be accessed as needed from
{{URL:http://www.mincom.com/mtr/sdf/catalog.html}}.

The SDF distribution is now CPAN-compliant, thanks to the
efforts of Achim Bonnet ({{EMAIL:ach@mpe.mpg.de}}). As a result,
several things have changed:

* installation is much easier
* the SDFHOME environment variable is no longer used to find files:
  - Perl libraries are now assumed to be available on Perl's library path
  - configuration files, including {{FILE:sdf.ini}}, are now located
    within the {{FILE:sdf/home}} directory somewhere on Perl's library path.
* the {{test}} directory has been renamed to {{t}}
* the {{CMD:sdftest}} script is now located within the {{t}} directory.

H3: Better support for non-English languages

Russian characters (and characters from other non-English languages)
are now hopefully better handled for users running on Perl 5.004 or later.
(Thanks to Nikolaj Logvinov for this fix.)

A German locale (de_de.sdl) has also been added.
(Thanks to Andreas Lohrum for this.)

H3: Table enhancements

The {{FILT:table}} filter now supports some new parameters:
  * {{colvaligns}} - a comma-separated list of vertical alignments 
    values (Top, Middle, Bottom, Baseline) for columns. For the lazy
    people, a single word containing the letters T, M, B and L can
    be used for the value as well.
  * {{select}} - a comma-separated list of columns to display.
  * {{delete}} - a comma-separated list of columns to delete.

The {{delete}} parameter is particularly useful if
you want to sort or filter a table
(using the {{sort}} and {{where}} parameters, respectively) using
a column which you don't want in the output.

H3: Object management enhancements

Class filters also support the {{colaligns}}, {{colvaligns}}, {{select}}
and {{delete}} parameters provided by the {{FILT:table}} filter.

A new feature called {{object views}} has been introduced. See
{{[jump="../ref/in_claif.html"] Understanding Class Interfaces}}
within the {{DOC: SDF Reference}} for details.

The {{MAC:catalog}} macro can now apply the filtering mask to
an attribute other than the name. To specify the attribute,
use a mask of the format:

>       attribute":"mask_pattern

H3: Example/verbatim enhancements

The {{FILT:verbatim}} and {{FILT:example}} filters now support
a {{listitem}} attribute (ala the {{FILT:table}} filter), although
this attribute currently only indents the text for these filters.

The {{skipheader}} attribute of the {{FILT:example}} and {{FILT:verbatim}}
filters now uses the {{lang}} attribute, if any, to determine the commenting
conventions. Previously, it assumed comments began with # and were
terminated by the end of line.

H3: Miscellaneous things

A module with support for Use Cases has been added (stdlib/usecases.sdm).

The {{MAC:insert}} macro can now be used to insert/execute a macro
which may not be defined.


H2: Fixes

{{CMD:sdftest}} on Windows/DOS systems now works.

For plain text output, unwanted lines between consecutive example
paragraphs have been removed.

File handling on the Macintosh should now be fixed.
(Thanks to David Schooley.)

Within {{CMD:sdfget}} reports, * processing now works again.

When generating an {{rtf}} file via [[FrameMaker]], the intermediate
{{mif}} file is now deleted.

{{Inner}} and {{Outer}} no longer produce warnings as unknown values
for the {{align}} parameter for the {{FILT:table}} or {{FILT:box}}
filter.

Consecutive normal paragraphs within a {{FILT:box}} filter or a
multi-paragraph table cell no longer run together when HTML is generated.

The {{FILT:about}} filter works correctly again for HTML output.

The {{FILE}} phrase style is now mapped to TT for HTML output.

The {{OPT_PAGE_SIZE}} and {{OPT_WIDTH}} variables are no longer
ignored if they are set via the {{MAC:init}} macro.

Generating PostScript and DVI via SGML-Tools 1.02 or later
should now work.

Column alignments within tables are no longer ignored when SGML
is generated.

{{None}} is now a legal value for cell rulings within tables.
(Thanks to Cliff Krumvieda for this fix.)

H2: Incompatibilities

Configuration files are now located differently.
See {{SECT:Better packaging}}, above, for details.

The scripts in the {{FILE:bin}} directory
now use {{FILE:/usr/local/bin/perl}}, rather than
{{FILE:/usr/local/bin/perl5}}, i.e. the default version
of Perl installed at a site is now assumed to be 5.003 or later.

The PDF and PostScript versions of the documentation are no longer
shipped with the SDF package. Instead, the document catalog points
to PDF and PostScript files on SDF's web site. (This change was made
to reduce the size of the SDF distribution.)

If you are generating outputs via SGML-Tools, you now need SGML-Tools
1.02 or later (rather than 0.99 or later).

The {{paper}} document style now leaves headings as they are defined.
Previously, it implicitly changed H-style headings to P-style
headings and slid them down one level.

The {{sdtgen}} script has been renamed {{CMD:sdngen}} to reflect the
fact that {{sdn}} is the extension now used for tuning modules.
sdf.ini}}, are now located
    within the {{FILE:sdf/home}} directory somewhere on Perl'sdf-2.001/doc/release/2000b9.sdf010064400042570001753000000065250647527564400156500ustar00iancmtr00000400000236H1: 2.000beta9

!subsections "Enhancements,Fixes,Incompatibilities"

H2: Enhancements

H3: Overview

The {{contrib}} directory now contains an SDF mode for Emacs and
a rudimentary RTF to SDF converter. Like other things in the
{{contrib}} directory, these are unsupported but may be useful.

The other enhancements are:

!block sections
. Improved documentation
. Improved text tables
. New filters
. Citation support.
!endblock

Further details are provided below.


H3: Improved documentation

The documentation has been improved in a number of ways:

^ The {{DOC:SDF User Guide}} has been revised and updated.
+ The {{DOC:SDF Guru Guide}} now has a chapter on extending SDF.
+ The manuals provided with SDF now have an index.
+ The {{SDF 2.000 Migration Guide}} is no longer provided in
  the standard distribution (as it is only useful for SDF 1.x
  users within {{ORG:Mincom}}).


H3: Improved text tables

Thanks to Tim MacKenzie ({{EMAIL:Tim.MacKenzie@fulcum.com.au}}):
tables output in txt format have been improved:

* all cells are now word wrapped (not just the last one in each row)
* cell alignment is now supported
* Line paragraph styles within cells are now supported
* heading underlining has been improved.

H3: New filters

Thanks to Tim Hudson ({{EMAIL:tjh@cryptsoft.com}}), a number
of new filters are now available:

!block table; groups
Name            Description
built-in:
nofill          format a set of lines
simple          generic filter for building other filters
defines.sdm:
product_defines define products and variables for each
section_defines define section names as variables
testcase.sdm:
testcases       collect testcases from A3s into a table at the end of document
!endblock


H3: Citation support

References can now be easily numbered and the numbers can be
inserted in paragraph text. The new features which make this possible are:

* the references class now supports a {{Cite}} attribute which
  produces a string of the form [n]
* the REF phrase style now supports a {{cite}} attribute which
  inserts the reference number using the syntax [n].

For example:

!block example; pure
H1: References

!include "doc.reg"; references; columns='Cite,Document'

H1: Some heading

Refer to {{REF[cite]ABC}} and {{REF[cite]ME2}}.
!endblock

If you want to put the reference table at the back of the document,
it is necessary to forward declare which documents will be cited
by using the {{cited}} parameter of the {{CLASS:references}} filter.
The table of cited references can then be built later by using
the {{MAC:catalog}} macro. For example:

!block example; pure
!include "doc.reg"; references; cited

H1: Some heading

Refer to {{REF[cite]ABC}} and {{REF[cite]ME2}}.

H1: References

!catalog references 'cited'; columns='Cite,Document'
!endblock


H2: Fixes

FrameMaker 4.x compatibility has been improved thanks to a patch
from Tim MacKenzie ({{EMAIL:Tim.MacKenzie@fulcum.com.au}}).

The document control section (on the inside of the front cover)
of project documents has been improved. (In fact, it is now much
easier to customise output of the {{MAC:build_title}} macro.)

The {{FILT:about}} filter was fixed to work better with documents
formatted using the {{infomap}} look.

For Windows 3.x/MS-DOS users:

* the sdftest.bat file has been fixed
* the sdfget.bat file has been added.

Date formatting for years >= 2000 has been fixed.

H2: Incompatibilities

None.
sdf-2.001/doc/release/2000b9a.html010064400042570001753000000071650672242645700161750ustar00iancmtr00000400000236






SDF 2.001: SDF Release Notes: 2.000beta9a




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    7. 2.000beta9a
    

    Enhancements | Fixes | Incompatibilities
    

    

    7.1. Enhancements
    

    A series of LOGO_BASE variables have been introduced so that the browser-time location of HTML images can be different to the compile-time location. For example, by defining:
    

    !define DOC_LOGO      "mylogo"
!define DOC_LOGO_BASE "/images/"

    

    the URL of the logo image will be "/images/mylogo.gif".
    

    New aliases have been introduced to make it easier to rebuild topics (+mt) and chapters (+mc) in the MIMS documentation. For example, to build the PostScript for the MIMS topic called 3201_msm200a.sdf, the command is:
    

           sdf -2ps +mt 3201_msm200a

    

    

    7.2. Fixes
    

    Perl 5.004 introduced a warning about an odd number of elements in a hash list which previous versions of SDF occasionally triggered. The cause of the warning has now been fixed.
    

    The label parameter on the note filter now works.
    

    Some minor documentation corrections have been made. In particular, the URL for the Ultimate editor is now correct.
    

    Lines now appear above and below notes in HTML.
    

    

    7.3. Incompatibilities
    

    The box filter has been changed to do what people expect. The old behaviour is available by adding the lines parameter.
    

    

    7.4. Future Incompatibilities!
    

    The next version of SDF is probably going to be (almost) upwardly compatible with Perl5's POD format. As a result, the = character will be a multi-line macro invocation, rather than being a shorthand for E:. If you are currently using =, please replace it with E: in preparation for the next release.
    

    Making SDF upwardly compatible with POD will undoubtedly introduce a few other incompatibility problems. However, I'll do what I can to minimise these. The goal is to make it possible to use SDF for Perl5 module documentation when POD is not sufficient.
    

    If you have any feedback on the idea of making SDF upwardly compatible with POD, send some email to the SDF users mailing list (sdf-users@mincom.com).
    

    This release will also be the last one supporting Perl 4.036. Future releases will require Perl 5.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/release/2000b8.html010064400042570001753000001370460672242652600160320ustar00iancmtr00000400000236






SDF 2.001: SDF Release Notes: 2.000beta8




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    10. 2.000beta8
    

    Enhancements | Fixes | Incompatibilities
    

    

    10.1. Enhancements
    

    There are lots of new things in this version. The general enhancements are:
    


    The table enhancements are:
    


    The page formatting enhancements are:
    


    The configuration enhancements are:
    


    Details are given below.
    

    
Note: For html and txt targets, this release is slightly faster than the previous one. For mif (and ps), this release may be slightly slower (as SDF templates, not FrameMaker ones, are now used).

    

    10.1.1. Easier enumerated values
    

    Enumerated values no longer need to be quoted. In a set of name-value pairs, if an expression is a single word where:
    

      

    • the first character is uppercase

    • the remaining characters are lowercase
    

    then the word is assumed to be an enemerated value and it is automatically converted to a string. For example, the following two lines are now equivalent:
    

       P1[align="Center"] My Title
   P1[align=Center] My Title

    

    10.1.2. Look improvements
    

    The overall appearance (i.e. look) of an SDF document can be controlled via the -k option or the OPT_LOOK variable. SDF now supports the following looks:
    

      

    • simple - the default look, useful for general documentation

    • fancy - QSD-like look, but without any logos

    • infomap - look based on Information Mapping™ 

    • overhead - look suitable for overhead transparencies.
    

    
Note: For backwards compatibility, plain is now an alias for simple.

    

    10.1.3. Style rationalisation
    

    SDF now supports the styles (i.e. document types) below.
    

    

    

Style


Purpose


    

    

General:


 


    

    

document


a normal document


    

    

manual


a manual


    

    

paper


a technical paper


    

    

Administration:


 


    

    

admin


generic administration document


    

    

fax


a fascimile


    

    

memo


a memorandum


    

    

newslttr


a newsletter


    

    

minutes


minutes of a meeting


    

    

Miscellaneous:


 


    

    

listing


a source code listing


    

    


    The build_title macro is used to build the cover page for the general styles. The title filter is used to build the title block for the administation styles. The miscellaneous styles do not have a title.
    

    Adding new styles for a look is now much easier than it was previously. Furthermore, manual is now just another style rather than a special mode.
    

    10.1.4. More build_title control variables
    

    build_title now supports the following variable:
    

      

    • DOC_COVER - the logical name of the cover page to use.
    

    Supported DOC_COVER values and their meanings are given below:
    

    

    

Value


Meaning


    

    

original


SDF's original cover page layout


    

    

project


a cover page useful for project documentation


    

    

manual


the cover page used when OPT_STYLE is manual


    

    

paper


the cover page used when OPT_STYLE is paper


    

    


    The manual cover supports a new macro called DOC_OFFICES, i.e. if DOC_OFFICES is defined, its contents are appended after the inside cover page.
    

    10.1.5. Miscellaneous things
    

    The SDF What's Planned document and bugs.html have been replaced by the SDF Bug Database. In fact, the organisation of the documentation has been improved quite a bit.
    

    Any document can now be converted to a FrameMaker book, i.e. it is no longer necessary to specially organise files in order to create a FrameMaker book.
    

    Tables of style columns (the default) now have a thin line above group rows.
    

    Tables can now be specified as list items by using the listitem parameter of the table filter. The value is the logical indent of the list (e.g. 1, 2, etc.). When generating HTML which contains a table within a numbered list, the listitem parameter is necessary in order to prevent the numbering from resetting.
    

    The new box filter can be used to place a box around one or more lines of text.
    

    The new center filter can be used to center a region of text.
    

    The new paragraph attribute called wide can be used to specify that a paragraph straddles the side-head area in addition to the main text area. Likewise. class filters (e.g. terms, references, etc.) now also support the wide attribute.
    

    By default, SDF automatically generates an id attribute for all headings in the table of contents. However, it is occasionally necessary to disable this, particularly when the same heading appears multiple times in a file. The new paragraph attribute noid can be used to prevent an id being generated for a paragraph.
    

    The title for an administration-style document can now be changed by either setting the DOC_TYPE variable or by using the new type parameter to the title filter. For example, if you want the title "Urgent Memo" rather than the default "MEMORANDUM" for a memo, you can now do the following:
    

    !init OPT_STYLE="memo"
!block title; type="Urgent Memo"
usual name-values pairs go here ...
!endblock

    

    The title filter now also supports a format parameter which can be used to tune the column widths, when necessary.
    

    RTF can now be generated via FrameMaker by using the new sdf2fmrtf alias, i.e. the command is (say):
    

       sdf -2fmrtf myfile.sdf

    

    When RTF is generated via FrameMaker, Word's standard style names are used, where possible. This makes it easier to import the RTF file into an existing Word document.
    

    Lists of tables and lists of figures can now be generated for normal documents, i.e. it is no longer necessary to use a FrameMaker book to build these lists.
    

    The new variable TXT_MARGIN can be used to control the width for txt output. Likewise, the new variable POD_MARGIN can be used to control the width of tables for pod format.
    

    The new bugtrack module can be used to build a simple bug tracking system like SDF's bug database.
    

    The new namevalues macro can be used to output a set of name-value pairs for an object. The parameters are:
    

      

    • the class name

    • the object name

    • a comma-separated list of attribute names.
    

    For example:
    

    !namevalues 'bugs'; 'sd0001'; 'Priority,Status,Type'

    

    Finer control over object catalog formatting is now available via the new style and headings attributes. style is the table style to use. The default value is plain. If headings is set, column headings are output. (By default, they are not.)
    

    10.1.6. Easier column widths
    

    SDF now supports dynamic column widths for paper documentation, i.e. if a width is not specified for a column, then the column is sized based on the text within it and the space available. Proportional column widths are also supported.
    

    The format attribute of the table filter is either:
    

      

    • a single number, in which case each digit represents 10% of the width available to the table, or

    • a comma-separated list of column width specifications.
    

    Examples of the column width specifications now supported are given below.
    

    

    

Value


Meaning


    

    

30pt


an exact size (other supported units are cm, mm, " and in)


    

    

30%


a percentage of the size available


    

    

30


a percentage of the size available (% is implicit)


    

    

10-20


dynamic size between 10% and 20% of the total width


    

    

-20


dynamic size between 0% and 20% of the total width


    

    

10-


dynamic size between 10% and 100% of the total width


    

    

-


dynamic size between 0% and 100% of the total width


    

    

3*


3 units of the remaining space


    

    

*


same as 1*


    

    


    For example, in the table below, the second column will be twice the size of the last column.
    

    !block  table; format="20,2*,10,*"
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock

    

    The output is:
    

    

    

Name


Column2


Column3


Column4


    

    

A


B


C


D


    

    

X


Hello dear world


Y


Z


    

    


    If a column is not given a size, the following rules are used:
    

      

    1. The last unspecified column size is implicitly '*' (i.e. the rest), unless the narrow attribute is set, in which case the size is implicitly '-' (i.e. as much as needed).

    2. The other unknown sizes are implicitly '-'.
    

    For example, the first and third columns in the table below will be dynamically sized. The first column will take as much space as required and the last column will expand so that the table takes the full width of the text area.
    

    !block  table; format=",30,,10"
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock

    

    The output is:
    

    

    

Name


Column2


Column3


Column4


    

    

A


B


C


D


    

    

X


Hello dear world


Y


Z


    

    


    However, in the example below, each column will only take as much space is required, making the table narrower than it would be otherwise.
    

    !block  table; narrow
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock

    

    The output is:
    

    

    

Name


Column2


Column3


Column4


    

    

A


B


C


D


    

    

X


Hello dear world


Y


Z


    

    


    If an = character is used in place of a - character for a column width, then those columns will be equalised in size. For example, the second and forth columns in the table below will be made equal in size.
    

    !block  table; format="20,5=30,10,="
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock

    

    The output is:
    

    

    

Name


Column2


Column3


Column4


    

    

A


B


C


D


    

    

X


Hello dear world


Y


Z


    

    


    
Note: As previously, the format parameter has no impact on HTML generation, i.e. all columns in HTML remain dynamically sized. Dynamic sizing is also ignored for txt and pod targets.

    

    10.1.7. Heading/footing rows for tables
    

    The table filter now supports the following attributes:
    

      

    • headings - the number of heading rows at the top of the table

    • footings - the number of footing rows at the end of the table.
    

    If the headings attribute is not defined, then as previously done, the column headings are generated using the column names given on the parsing line. For example, the column headings in the table below will be Name and Age:
    

    !block table
Name    Age
Bill    42
!endblock

    

    Alternatively, if the headings attribute is defined, then that number of data rows are used as the column headings, i.e. the parsing line is not used to build the column headings. For example, the column headings in the table below will be "Title" and Age (remembering that a filter attribute is implicitly given the value 1 is no value is supplied).
    

    !block table; headings
A       B
"Title" Age
Bill    42
Sally   23
!endblock

    

    Likewise, the column headings below will be Preferred Title and Likely Age with each heading taking 2 rows.
    

    !block table; headings=2
A           B
Preferred   Likely
Title       Age
Bill        42
Sally       23
!endblock

    

    Collectively, these new attributes improve things in several ways:
    

      

    • heading rows can now include non-alphanumeric characters

    • macros (e.g. change bars) can be applied to heading rows

    • multi-line heading and footing rows are now supported.
    

    10.1.8. Table positioning
    

    The horizontal alignment and vertical placement of a table can be controlled by setting the align and placement parameters of the table filter respectively. The permitted align values are:
    

    

    

Value


Meaning


    

    

Left


left-align the table


    

    

Center


center the table


    

    

Right


right-align the table


    

    

Inner


align the table with the inner margin


    

    

Outer


align the table with the outer margin


    

    


    
Note: The wide parameter changes the left indent of a table to include the sidehead of a page. Therefore, the wide parameter will impact the horizontal positioning of any table which is not right-aligned.

    

    The permitted placement values are:
    

    

    

Value


Meaning


    

    

Float


next column if necessary


    

    

Pagetop


top of the next page


    

    

Columntop


top of the next column


    

    

Lefttop


top of the next left-hand page


    

    

Righttop


top of the next right-hand page


    

    


    10.1.9. Table filtering and sorting
    

    Tables can now be filtered and sorted by using the new where and sort attributes of the table filter. These attributes are also supported by the class filters (e.g. terms, references). In either case, filtering is done before sorting.
    

    The where attribute takes an expression which is evaluated for each record. Special symbols available are:
    

    

    

Symbol


Meaning


    

    

$_


the current record


    

    

$o{"xyz"}


the value of column xyz


    

    


    sort takes a comma-separated list of column names to sort on. If no columns are specified, the data is sorted using all columns in the order in which they appear. All sorting is done alphabetically - numeric sorting is not supported.
    

    10.1.10. Landscape tables
    

    Landscape tables are now supported via the landscape parameter of the table filter. The value is the height allocated to the area in which the table is placed. If a unit is not specified, the value is assumed to be a percentage of the text column height. For convenience, a value of 1 implies a full page table. Some examples are given below.
    

    

    

Value


Meaning


    

    

landscape="50pt"


height allocated to table is 50 points


    

    

landscape="50%"


half page table


    

    

landscape=50


half page table (% is the default units)


    

    

landscape=1


full page table (1 implies 100%)


    

    

landscape


full page table (syntactic shorthand for above)


    

    


    
Note: This feature is currently use at your own risk. In particular, long tables and table titles confuse it badly. Furthermore, the align and placement parameters are effectively ignored for landscape tables.

    

    10.1.11. Column alignment
    

    The colaligns parameter of the table filter can now be used to control the alignment of text within columns of a table. For example:
    

    !block  table; colaligns="LCCR"
Name    Column2             Column3     Column4
A       B                   C           1.0
X       Hello dear world    Y           10.2
!endblock

    

    The output is:
    

    

    

Name


Column2


Column3


Column4


    

    

A


B


C


1.0


    

    

X


Hello dear world


Y


10.2


    

    


    The value of colaligns is usually a sequence of the letters L, C and R (which mean what one would expect). If you prefer, a comma-separated list of the values Left, Center and Right can be specified. For example:
    

    !block  table; colaligns="Left,Center,Center,Right"
Name    Column2             Column3     Column4
A       B                   C           1.0
X       Hello dear world    Y           10.2
!endblock

    

    10.1.12. Cell attributes
    

    Cells within a table can now be given attributes by preceding the cell value with a semicolon-separated list of name-value pairs enclosed in square brackets. For example:
    

    !block  table; colaligns="LCCR"
Name    Column2             Column3     Column4
A       [align=Left]B       C           [bgcolor=Green]1.0
X       Hello dear world    Y           [bgcolor=Red]10.2
!endblock

    

    The output is:
    

    

    

Name


Column2


Column3


Column4


    

    

A


B


C


1.0


    

    

X


Hello dear world


Y


10.2


    

    


    The cell attributes supported are given below.
    

    

    

Name


Value


    

    

General:


 


    

    

align


horizontal alignment (Left, Center, Right)


    

    

valign


vertical alignment (Top, Middle, Bottom, Baseline)


    

    

cols


the number of columns this cell spans (default is 1)


    

    

rows


the number of rows this cell spans (default is 1)


    

    

bgcolor


background colour of cell (see below)


    

    

PS only:


 


    

    

fill


background colour fill percentage


    

    

truling


ruling setting for top of cell


    

    

bruling


ruling setting for bottom of cell


    

    

lruling


ruling setting for left of cell


    

    

rruling


ruling setting for right of cell


    

    

angle


angle of text (0, 90, 180, 270)


    

    

HTML only:


 


    

    

nowrap


disable word wrap for this cell


    

    

Special:


 


    

    

sdf


treat the cell text as SDF (rather than as phrase text)


    

    

tag


phrase tag to apply to cell text


    

    

paratag


paragraph style to apply to cell text


    

    


    For PS (i.e. MIF) generation, the supported colour values are Black, White, Red, Green, Blue, Yellow, Cyan and Magenta. If a different colour is specified, it is ignored. The supported fill values are 100, 90, 70, 50, 30, 10 and 3. If a fill value is not specified, 100% fill is used.
    

    For HTML generation, any of the HTML colours names (including those supported for PS generation) or the "#rrggbb" form can be used.
    

    The permitted ruling values are Vthin, Thin, Medium, Thick and Double.
    

    The sdf, tag and paratag attributes control the way in which the cell text is converted to SDF:
    

      

    1. If sdf is set, the cell text is already SDF.

    2. Otherwise if tag is set, the SDF paragraph is paratag:{{tag:text}}.

    3. Otherwise, the paragraph is paratag:text.
    

    tag is usually set via the tags or groups parameters of the table filter.
    

    
Note: paratag is not yet implemented.

    

    10.1.13. Spreadsheet calculations
    

    The spreadsheet expression evaluator and the documentation below was written by Tim Hudson (tjh@cryptsoft.com).
    

    Spreadsheet style calculations have been introduced into SDF using the standard [[ ]] syntax with a prefix of + (or =) indicating that the expression is to be evaluated by the calculation routines.
    

    This extension has been loosely modelled on Microsoft Excel®  in terms of the initial functions supported and the syntax used.
    

    
Note: Calculation support for a table can be disabled by adding in an attribute of nocalcs (otherwise the pointers required to table data that are needed when doing spreadsheet calculations occur for each table cell).

    

    Each cell in a table has an cellid which is made up of a single uppercase letter indicating the column index and a number indicating the row index (counting from 1 and excluding the heading rows). The upper left cell is hence A1.
    

    An example grid indicating cellids:
    

    

    

Title1


Title2


Title3


Title4


Title5


    

    

A1


B1


C1


D1


E1


    

    

A2


B2


C2


D2


E2


    

    

A3


B3


C3


D3


E3


    

    

...


...


...


...


...


    

    

A100


B100


C100


D100


E100


    

    


    A range of cellids is specified using the syntax cellid1:cellid2. For example: A1:C1 is exactly the same as A1,B1,C1
    

    An expression consists of a combination of standard Perl operators and spreadsheet functions and cellids or cellid ranges.
    

    Standard Perl operators include:
    

      

    • + - * /
    

    Spreadsheet functions use the syntax FUNCTION(ARG1,ARG2,...ARGN).
    

    The following functions are supported:
    

      

    • AVERAGE - the average - SUM(ARGS)/COUNT(ARGS)

    • SUM - the sum of the args - same as ARG1+ARG2+...+ARGN

    • MIN - the minumum argument value

    • MAX - the maximum argument value

    • COUNT - the number of arguments

    • PRODUCT - the product of the args - same as ARG1*ARGN*...*ARGN

    • ROWSUM - the SUM of all the cells in the row to the left of the current cell

    • ROWPROD - the PRODUCT of all the cells in the row to the left of the current cell

    • COLSUM - the SUM of all the cells in the column above the current cell

    • COLPROD - the PRODUCT of all the cells in the column above the current cell
    

    A simple example:
    

    !block table; style="grid"
Count         Price        Total
10            5            [\[=A1*B1]\]
15            5.23         [\[=ROWPROD]\]
[\[=COLSUM]]   [\[=B1+B2]\]   [\[=COLSUM]\]
!endblock

    

    Which generates the result below. (Ok, summing two prices is meaningless, but it illustrates the syntax.)
    

    

    

Count


Price


Total


    

    

10


5


50.00


    

    

15


5.23


78.45


    

    

25.00


10.23


128.45


    

    


    
Note: values are available until the next table is processed so you can refer to data inside normal paragraphs after the table like this [\[=A1]\] which evaluates to 10.00
    

    

    A spreadsheet expression will recursively evaluate any expressions contained in cells that are used in an expression. In the example above, the expression in cell C3 depends on the results of the expression in cell C1 and C2.
    

    10.1.14. Arbitrary page sizes
    

    Generally speaking, SDF can now support arbitrary page sizes. The catch is that the page size must now be specified up front via the OPT_PAGE_SIZE variable on the init line or via sdf's -S option. (Previously, the (no longer supported) DOC_PAGE_SIZE variable could be specified anywhere in the document.)
    

    The supported values of OPT_PAGE_SIZE are given below. The default page size is global.
    

    

    

Name


Width


Height


Comment


    

    

global


21.0cm


11.0in


will fit on either A4 or letter


    

    

A3


29.7cm


42.0cm


 


    

    

A4


21.0cm


29.7cm


 


    

    

A5


14.8cm


21.0cm


 


    

    

B4


25.7cm


36.4cm


 


    

    

B5


17.6cm


25.0cm


 


    

    

letter


8.5in


11.0in


 


    

    

legal


8.5in


14.0in


 


    

    

tabloid


11.0in


17.0in


 


    

    


    
Note: global is 0.23" narrower than letter and 1.76cm shorter than A4.

    

    New page sizes can be defined in sdf.ini. A rotated version is also available for each page size. Rotated sizes are named with an appended R. For example, the rotated A4 size is called A4R.
    

    10.1.15. Headers and footers
    

    SDF now provides 3 ways of controlling headers and footers:
    

      

    • The OPT_HEADINGS variable (high level control)

    • PAGE_page_HF_ICOn variables (medium level control)

    • PAGE_page_HF macros (low level control)
    

    where:
    

      

    • page is FIRST, RIGHT or LEFT

    • HF is HEADER or FOOTER

    • ICO is INNER, CENTER or OUTER

    • n is the line number within the header or footer (usually 1 or 2).
    

    The meaning of each page type is explained below.
    

    

    

Page


Usage


    

    

FIRST


the first page in the document


    

    

RIGHT


the page used for single-sided documents and the right hand side of double-sided documents


    

    

LEFT


the left hand side of double-sided documents; ignored for single-sided documents


    

    


    Supported OPT_HEADINGS values and their meanings are given below:
    

    

    

Value


Meaning


    

    

0


no header, no footer


    

    

1


single line header, single line footer


    

    

2


two line header and two line footer


    

    

3


two line header and three line footer


    

    

4


two line header and four line footer


    

    


    10.1.16. Header/footer special tags
    

    The following special tags are supported within headers and footers:
    

    

    

Tag


Meaning


    

    

PAGENUM


current page number


    

    

PAGECOUNT


highest page number


    

    

PARATEXT


paragraph text (e.g. Hardware requirements)


    

    

PARANUM


paragraph number (e.g. Appendix A)


    

    

PARANUMONLY


paragraph number only (e.g. A)


    

    

PARASHORT


value of short attribute of paragraph


    

    

PARALAST


text of last paragraph on page with the nominated style


    

    


    The PARA* tags require a comma separated list of paragraph styles to be nominated as the text of the phrase, e.g. {{PARATEXT:H1,A1,P1}}.
    

    The PARASHORT tag is useful for placing an alternative heading in a header, say. For example, you might set up your header to include {{PARASHORT:H1}} and have the following text in your document:
    

      H1[short='Getting started'] Getting started with SDF

    

    The PARALAST tag is useful for producing dictionary-like headers.
    

    10.1.17. Header/footer borders
    

    High level control over header/footer borders is provided by the OPT_BORDERS variable. The supported values and their meanings are given below:
    

    

    

Value


Meaning


    

    

0


no header/footer borders


    

    

1


line below header, line above footer


    

    

2


lines above and below header, line above footer


    

    


    Finer control is available by setting the following variables:
    

    

    

Name


Value


    

    

PAGE_page_HEADER_BORDER


border specification string


    

    

PAGE_page_FOOTER_BORDER


border specification string


    

    


    where page is either FIRST, RIGHT or LEFT.
    

    A border specification string is a comma-separated list of attributes which collectively describe the border. The format of each attribute is name[=value]. The supported attributes are:
    

      

    • top - a line above the area

    • bottom - a line below the area

    • box - a box around the area

    • radius - for a box, the radius of the corner.
    

    For top, bottom and box, the value of the attribute is the line width in points.
    

    10.1.18. Page backgrounds
    

    In order to support fancy background images, SDF supports the following variables:
    

    

    

Name


Value


    

    

PAGE_page_BACKGROUND


the logical image name


    

    


    where page is either FIRST, RIGHT or LEFT.
    

    When FrameMaker is being used to generate PostScript, the image name is mapped to a master page called backgrnd within a file called backgrnd.mif.
    

    
Note: At the moment, objects from the master page (excluding TextRects) are directly transferred to the generated MIF file. This means that objects in the lower right hand corner of an A4 master page will not will be positioned nicely if the paper size is changed to A5, say.

    

    10.1.19. Page layout variables
    

    Page margins can now be controlled via the following variables:
    

    

    

Name


Value


    

    

OPT_MARGIN_TOP


size of the margin above the header, if any


    

    

OPT_MARGIN_BOTTOM


size of the margin below the footer, if any


    

    

OPT_MARGIN_INNER


size of the inner margin


    

    

OPT_MARGIN_OUTER


size of the outer margin


    

    


    The positioning of headers and footers can now be controlled via the following variables:
    

    

    

Name


Value


    

    

PAGE_page_HEADER_HEIGHT


height of the area allocated to the header


    

    

PAGE_page_HEADER_GAP


size of the gap between the header area and the text area


    

    

PAGE_page_FOOTER_HEIGHT


height of the area allocated to the footer


    

    

PAGE_page_FOOTER_GAP


size of the gap between the text area and the footer area


    

    


    where page is either FIRST, RIGHT or LEFT.
    

    After the margins and header/footer are allocated, the remaining text area contains 1 or more text columns and an optional side head. The layout of these is controlled by the following variables:
    

    

    

Name


Value


    

    

OPT_COLUMNS


numbers of text columns


    

    

OPT_COLUMN_GAP


space between columns


    

    

OPT_SIDEHEAD_WIDTH


size allocated to the sidehead


    

    

OPT_SIDEHEAD_GAP


space between the side-head and first text column


    

    


    The following read-only variables provide information on the page layout:
    

    

    

Name


Value


    

    

DOC_PAGE_WIDTH


width of page


    

    

DOC_PAGE_HEIGHT


height of page


    

    

DOC_FULL_WIDTH


width of text area including the side-head


    

    

DOC_TEXT_WIDTH


width of text area available for text columns


    

    

DOC_TEXT_HEIGHT


height of text area


    

    

DOC_COLUMN_WIDTH


width of a text column


    

    


    All the information variables are in units of points. The text area is the area allocated to text, excluding the header and footer (if any) on the RIGHT page.
    

    10.1.20. Page control within a book
    

    When a book is being generated, each component of the book may have its own FIRST, RIGHT and LEFT pages, i.e. all of the macros and variables above support an extended set of page values component_FRL where:
    

      

    • component is the name of the component

    • FRL is FIRST, RIGHT or LEFT.
    

    The component names supported are given below.
    

    

    

Name


Meaning


    

    

FRONT


the cover component


    

    

PRETOC


components before the contents


    

    

TOC


the table of contents


    

    

LOF


the list of figures


    

    

LOT


the list of tables


    

    

PRECHAPTER


components before the chapters


    

    

CHAPTER


a normal chapter


    

    

APPENDIX


an appendix


    

    

PREIX


components before the index


    

    

IX


the index


    

    


    If a component does not have a component-specific macro/variable defined, then the generic macro/variable is used.
    

    10.1.21. FrameMaker templates are no longer required
    

    Previously, SDF produced MIF documents by merging generated MIF paragraphs into FrameMaker templates. This approach was easy to implement but maintaining the FrameMaker templates was difficult as every look required several templates for each page size!
    

    FrameMaker templates can still be used but are no longer needed, nor recommended. Instead, the definitions of paragraph styles, phrase styles, table styles and graphic (border) frames is now done via SDF templates. SDF templates have the following advantages:
    

      

    1. Templates can be parameterised so that a single template can support any number of page sizes.

    2. Each look only requires a single template, rather than a template for each component of a FrameMaker book.

    3. Templates can inherit definitions from other templates, making it much easier to create and maintain templates.

    4. Each definition supports inheritance, so a new paragraph style, say, can be defined in terms of the differences between it and a parent style.
    

    The new sdtgen command can be used to build an SDF template from a FrameMaker one. Typically, sdtgen is used to create an initial template which is then simplified via definition inheritance and template inheritance.
    

    10.1.22. Event processing enhancements
    

    The following new symbols are now available within event processing for paragraphs:
    

    

    

Symbol


Meaning


    

    

$level


the current heading level (before this paragraph)


    

    

$prev_style


the style of the previous paragraph


    

    

$prev_text


the text of the previous paragraph


    

    

%prev_attr


the attributes of the previous paragraph


    

    


    These symbols make it much easier to do some really nice things. For example, the following rule can be used to put level 2 headings on a new page unless the heading is the first one within a chapter:
    

    !on paragraph '[HAP]2';; if ($level != 1) {$attr{'top'} = 1}

    

    

    10.2. Fixes
    

    Tim Hudson has contributed a number of fixes to this release including:
    

      

    • this version should now work with Perl 5 again - the previous version triggered a Perl 5 syntax error

    • the IMPORT pragma now supports filename extension adding ala the import macro

    • centred figures now work as expected in HTML

    • numerous Windows help generation fixes/enhancements.
    

    Other fixes include:
    

      

    • the renaming of xx.out.ps to xx.ps is now done by sdfbatch, so failures (due to lack of disk space, say) are now handled much better than they previously were

    • topics mode now generates an error if the heading of a topic is duplicated within a file (see Miscellaneous things above)

    • headings containing a ? character should no longer cause problems

    • some bugs in sdfget's extraction of documentation from C code have been fixed (thanks to Keith Ponting).
    

    

    10.3. Incompatibilities
    

    As the default page size is now global rather than A4, page breaks may occur slightly earlier than they previously did. The advantage of changing to global is that documents should now print successfully on US letter paper.
    

    Memos, faxes, minutes and newsletters no longer have the company address in the top right hand corner. (I'll fix this soon, but it is not a high priority at the moment.)
    

    As txt and pod outputs use a different algorithm for deciding column widths when a table does not have a format parameter, some table cells may no longer fit when these output formats are used.
    

    The table attribute previously called headings has been renamed to parseline to better reflect its purpose and to make way for the new meaning.
    

    The DOC_TOCTEXT variable has been renamed to DOC_TOC_TITLE. The DOC_TOCGRAPHIC variable has been renamed to DOC_TOC_GRAPHIC.
    

    The newsletter style has been renamed to newslttr.
    

    overhead is now a look, rather than a style. The overhead look is untested and rarely used, so use it at your own risk.
    

    The aliases sdf2htmls and sdf2txts have been renamed to sdf2fmhtml and sdf2fmtxt respectively.
    

    /usr/local/bin/perl5 is now the default perl interpreter used.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



D>
PAGE_page_BACKGROUND
    		

the logical image name


    

    


    where page is either FIRST, RIGHT or LEFT.
    

    When FrameMaker is being used to generate PostScript, the image name is mapped to a master page called backgrnd within a file called backgrnd.mif.
    

    
Note: Asdf-2.001/doc/release/2001.sdf010075500042570001753000000247470672242547700154230ustar00iancmtr00000400000236H1: 2.001

!subsections "Enhancements,Fixes,Incompatibilities"

H2: Enhancements

The enhancements are:

!block sections
. Level 0 headings
. New command line options
. Table enhancements
. HTMLDOC support
. Improved LaTeX support
. HTML formatting enhancements
. HTML meta information and stylesheet support
. Stylesheet-friendly HTML generation
. Embedded documentation enhancements
. Miscellaneous stuff
!endblock

H3: Level 0 headings

H0, A0 and P0 are now supported as paragraph styles. Level 0 headings
are implicitly converted to:

> !define DOC_NAME "text of heading"
> !build_title

This feature makes it easier to structure large documents as topics
each of which begins with H1. To format a particular topic as a
document, {{CMD:sdf}}'s -H option can be used to set the initial
heading level to zero like this:

>       sdf -2html -H0 mytopic.sdf

H3: New command line options

The {{CMD:sdf}} program has some new command line options: -O, -g and -K.

The -O option specifies an explicit output directory.
If the -O option is specified without a parameter, the input file's
directory is used. For example, to convert F to
HTML and put the output in the same directory as the original file,
the command is:

>       sdf -2html -O mydir1/mydir2/myfile

Note: The -O option doesn't always work.
In particular, HTML topics generation doesn't support it yet.

The -g option prefilters the input files by executing {{CMD:sdfget}}
using the default report (default.sdg). To change the report used,
specify the report name as the parameter.
If the report name doesn't include an extension, sdg is assumed.

The -K option sets the look of headings.
Sensible parameter values are H, A and P.
For example, to get the embedded documentation out of a script, make the
headings plain, generate a document (rather than a topic) and convert it
to HTML, the command line is:

>       sdf -g -KP -H0 -2html myscript

H3: Table enhancements

The predefined table style names (columns, rows, grid, plain and shade)
now have edit-case aliases (i.e. Columns, Rows, Grid, Plain and Shade).
If the edit-case versions are used, quotes are not needed, e.g.

>  !block table; style=Plain
>  !endblock

The {{keepindents}} parameter has been introduced for the {{FILT:table}}
filter. If set, leading whitespace in cells is kept, e.g.

!block verbatim
!block table; keepindents
Directory     Description
sdf           top level directory
   bin        scripts
      bat     batch file wrappers around scripts
   perllib
      sdf     sdf libraries
      Pod     pod libraries
!endblock
!endblock

The output is:

!block table; keepindents
Directory     Description
sdf           top level directory
   bin        scripts
      bat     batch file wrappers around scripts
   perllib
      sdf     sdf libraries
      Pod     pod libraries
!endblock

H3: HTMLDOC support

To convert a document to HTML ready for Michael Sweet's {{PRD:HTMLDOC}} program,
the command is:

>       sdf -2html -DHTMLDOC ...

Alternatively, {{CMD:sdf}} can call HTMLDOC itself in order to
generate PostScript or PDF. The commands to do this are:

>       sdf -2ps_html ...
>       sdf -2pdf_html ...

!block note
To maintain backwards compatibility, FrameMaker is still the default
back-end for generating PostScript and PDF. If you wish to make HTMLDOC the
default back-end, edit the {{FormatMappings}} sections of the F
file and change {{ps}} to mean {{ps_html}} and {{pdf}} to mean {{pdf_html}}.
Once this is done, the following commands will use HTMLDOC rather
than FrameMaker:

>       sdf -2ps ...
>       sdf -2pdf ...
!endblock

When {{CMD:sdf}} invokes HTMLDOC, it sets the appropriate HTMLDOC options
by using the following SDF variables: DOC_TITLE (build from DOC_NAME and
DOC_TYPE), DOC_TOC, DOC_TWO_SIDES, OPT_PAGE_SIZE, OPT_MARGIN_INNER,
OPT_MARGIN_OUTER, OPT_MARGIN_TOP and OPT_MARGIN_BOTTOM. In addition,
a new variable called HTMLDOC_OPTS can be used to pass additional
options through to the HTMLDOC command line, e.g.

>       sdf -2pdf_html "-DHTMLDOC_OPTS:--gray --jpeg" ...

To do: add support for AUTHOR, COPYRIGHT and DOCNUMBER.

At the moment, SDF headers and footers are not converted to their HTMLDOC
equivalents. To access HTMLDOC's header/footer support, it's currently
necessary to use the HTMLDOC_OPTS variable.

H3: Improved LaTeX support

Valerio Aimale's ({{EMAIL: mailto:valerio@publinet.it}}) LaTeX driver is
now part of the standard distribution. Refer to the file
F for usage details.

H3: HTML formatting enhancements

The following phrase attributes are now supported when generating HTML:
color, family, size, bold, italic, underline, bgcolor and changed.
A changed phrase or paragraph is shown with the background color given
by the HTML_CHANGED_COLOR variable. The default value is {{teal}}.

The following paragraph attributes are now supported when generating HTML:
align, first, left, right.

See the SDF files within the F directory for
examples of using these attributes.

H3: HTML meta information and stylesheet support

The {{meta}} filter can now be used to add META tags to the HEAD of
a HTML document. This filter expects a table with columns called Name
and Content, e.g.

!block verbatim
!block meta
Name|Content
description|Tools for building Java systems
keywords|Java,development tools
!endblock
!endblock

Stylesheets can be linked or embedded using the {{links}} and
{{stylesheet}} filters respectively. Here's a linked stylesheet:

>       !block links
>       Jump
>       test.css
>       !endblock

Here's how to embed the same stylesheet:

>       !include "test.css"; stylesheet

Phrases and paragraphs now support the following attributes:

* {{class}} - give this phrase or paragraph the nominated HTML CLASS attribute
* {{style}} - format this phrase or paragraph using the nominated style
  information.

Here's an example of applying a custom style:

>  [style='background-color: blue;; color: red']
>  A styled paragraph.

Note: SDF uses a single semi-colon to separate attributes, so attributes
values with embedded semi-colons need to use ';;' to mean ';'. (The
general rule is to use N+1 consecutive semi-colons to get N semi-colons).

H3: Stylesheet-friendly HTML generation

Generated HTML documents are now "stylesheet-friendly" in that:

* DIVs are placed around interesting parts of the document
* parts of the title are implicitly given classes
* tables are implicitly given classes.

Here are the document sections placed in DIVs:

!block table
Document_part           DIV_name
title section           title
table of contents       contents
main body               main
header section          header
footer section          footer
navigate section        navigate
!endblock

The navigate DIV is nested within header and footer.
(This makes it easy to format the navigation section regardless
of its location.)

Here's the list of classes placed on parts of the title:

!block table
Class           Comments
doc-title       title of document
doc-id          id of document
doc-author      author list
doc-status      document status
doc-modified    modification date
!endblock

Tables are implicitly given a class named after the SDF table style.
Heading and footing rows within tables are given classes of {{heading}}
and {{footing}} respectively.
Here's a set of Cascading Style Sheet (CSS) rules for a colorful
table:

>  TABLE.columns {background-color: yellow}
>  TABLE.columns TR.heading {background-color: aqua}
>  TABLE.columns STRONG {font-size: 20pt}
>  TABLE.columns TD {color: purple}

See the SDF files within the F directory for
more examples of using these features.

H3: Embedded documentation enhancements

A new filter called {{FILT:get}} has been added.

Support for embedded documentation in IDL has been improved (the IDL now
gets pretty-printed in the "Interface" section).

The {{MAC:getdoc}} and {{MAC:getcode}} macros now guess the get-rule
using the formatting extension.

The {{CMD:sdfget}} program has been enhanced in several ways:

* if specified without a parameter, the get-rule is now guessed from
  the file extension (see the {{CMD:sdfget}} documentation for details
  on how this is done)
* the new -v option enables verbose mode (which shows the get-rule guessed)
* a new option (-f) can be used to specify the
  the filename to use for formatting (which is useful when the text
  is coming from standard input)
* a new get-rule called {{bat}} is supported for DOS batch files
* if a report filename doesn't have an extension, sdg is assumed.

The {{default.sdg}} report has been enhanced to support new sections
called {{Notes}}, {{See_also}} and {{Authors}}.

A new SDG report called {{all.sdg}} has been added. This report
formats all embedded documentation sections (unlike {{default.sdg}}
which only extracts selected sections).

The {{default.sdg}} and {{all.sdg}} reports have been enhanced to
support the SDG_BEGIN and SDG_END macros. These macros are empty
by default so authors can override these to customise the
display of extracted documentation.

H3: Miscellaneous stuff

A new module called {{homepage}} has been added to make it easier to
build SDF-like home pages. For an example of usage, see the source for
SDF's home page (F).

A Russian locale (ru_ru) has been added thanks to
Alexey L. Popov ({{EMAIL:alpopov@elkamail.ru}}).

New macros called {{div}} and {{enddiv}} can be used to put divisions
in documents.

If {{CMD:sdf}}'s -p option is specified without a parameter, {{FILT:table}}
prefiltering is assumed.

H2: Fixes

Indented tables now work as expected, i.e. leading whitespace at the
beginning of the heading row is now accepted and remaining rows have
that amount of whitespace trimmed.

When generating txt output, leading cell whitespace now works as expected.
Previously, multiple spaces were converted to a single space.

Attribute values containing ;; no longer have the whitespace around
the character sequence trimmed.

Internally, unhandled internal directives no longer produce a warning.
(As a result, it's now easier to extend things without "breaking"
existing drivers.)

When generating HTML, the HTML_PRE_SECTION is no longer prepended unless
a table of contents is generated.


H2: Incompatibilities

When HTML is generated, the default footer no longer contains a line.
To get the old behaviour, set the HTML_OLD_FOOTERS variable, e.g.

>       sdf -2html -DHTML_OLD_FOOTERS ...

The HTML driver no longer uses special embedded comments to work out
where to put the table of contents.

The {{MAC:getcli}} macro no longer searches the include path: it just
executes the command.
sdf-2.001/doc/release/2000b4b.sdf010064400042570001753000000001140633403044200157440ustar00iancmtr00000400000236H1: 2.000beta4b

This is the first publicly available release of SDF 2.000.
sdf-2.001/doc/release/2000b12.html010064400042570001753000000244230672242644000160720ustar00iancmtr00000400000236






SDF 2.001: SDF Release Notes: 2.000beta12




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    4. 2.000beta12
    

    Enhancements | Fixes | Incompatibilities
    

    

    4.1. Enhancements
    

    
Note: The sdf2... wrapper scripts are no longer provided - use the -2 option of the sdf command instead.

    

    The major enhancements are:
    


    The minor enhancements are:
    

      

    • when include files and figures are searched for, the directory containing the document is now searched after the current directory

    • a Perl document catalog is now included (perl/catalog.sdf)

    • generation of non-MIF outputs is now slightly faster.
    

    Further details on the major enhancements are provided below.
    

    4.1.1. Output format naming rationalisation
    

    As SDF occasionally provides several ways to generate an output:
    

      

    • a convention has been introduced for output format names (i.e. the parameter to the -2 option)

    • a mapping table has been added to sdf.ini so that sites can customise the mapping from logical format names to actual format names.
    

    As a result, it is now easy to change sdf.ini so that PostScript generation (i.e. -2ps) is via POD format rather than via FrameMaker, say. Furthermore, regardless of the default setup for PostScript generation:
    

      

    • PostScript via FrameMaker can be explicitly requested via -2ps_fm, and

    • PostScript via POD can be explicitly requested via -2ps_pod.
    

    Generally speaking, a name of xxx_yyy means format xxx via yyy. Likewise, a name of xxx_ means format xxx directly.
    

    4.1.2. Automatic figure format conversion
    

    As requested (many years ago, in fact), SDF will now automatically convert figure formats for you if it needs to. In particular, if you have a prn file on the search path, sdf will convert it to gif for HTML and eps for PostScript. Likewise, if you have an eps for PostScript, sdf will convert this to gif when you generate HTML.
    

    Creating a prn file as a easy as printing to a PostScript file from most Windows apps including MS-Office and Rational Rose. As a result, figure management should no longer be the hassle its been in the past.
    

    The conversion rules are stored in bin/sdf.ini. Feel free to have a look and/or forward me any additions/enhancements to the rules. One of the rules uses a new program supplied in SDF called prn2ps. This new command makes the output from a Windows 95/NT "print PostScript to a file" command acceptable to Ghostscript's ps2epsi.
    

    4.1.3. Better HTML customisation and documentation
    

    A large number of HTML customisation features already existed, but were poorly documented. The new customisation features in this release are:
    

      

    • HTML_PRE_HEADER/HTML_POST_FOOTER support

    • HTML_TEXT_* support

    • HTML_SECTION_LEVEL/HTML_PRE_SECTION support.
    

    See the new tutorial titled Generating HTML Using SDF for details.
    

    4.1.4. New output formats
    

    SDF can now be converted to SGML like this:
    

      sdf -2sgml mydoc.sdf

    

    By default, the linuxdoc DTD is used. Alternatively, the SGML_DTD variable can be used to change the DTD to qwertz, say, like this:
    

      !define SGML_DTD "qwertz"

    

    If SGML-Tools 1.02 or later is installed, you can also generate the formats given below.
    

    

    

Command


Output format


Via


    

    

sdf -2latex_sgml


LaTeX


SGML-Tools


    

    

sdf -2dvi_sgml


DVI


SGML-Tools and LaTeX


    

    

sdf -2ps_sgml


PostScript


SGML-Tools and LaTeX


    

    

sdf -2rtf_sgml


RTF


SGML-Tools


    

    

sdf -2info_sgml


GNU info


SGML-Tools


    

    

sdf -2lyx_sgml


LyX


SGML-Tools


    

    


    4.1.5. Locales
    

    SDF now has better support for non-English languages via locales. The -L option of the sdf command can be used to specify a locale. The default locale name is specified in sdf.ini. Locale naming follows POSIX conventions (i.e. language_country), so the locale name for American english is en_us. The information for each locale is stored in the locale directory, so you'll need to have to look in there to see what locales are available. (As the default locale can be set in sdf.ini, this isn't as ugly as it first sounds.)
    

    At the moment, a locale file simply contains a list of language specific strings, although it should ultimately be extended to support localisation of date and time formats. Feel free to send me new locales so I can include them in future versions of SDF.
    

    4.1.6. Template processing
    

    SDF can now also be used as a generic template processor, i.e. you can create C source, say, with ! macros and [[..]] expressions within it and use sdf to process it. For example, if you have a file called xx.sdt like this:
    

        !if DATE
        <P>
        The date is [[DATE:DOC_START]].
    !else
        <P>
        The time is [[TIME:DOC_START]].
    !endif

    

    you can process it like this:
    

      sdf xx.sdt | less
  sdf -DDATE xx.sdt | less

    

    If the file doesn't have a sdt extension, you need to specify template processing like this:
    

      sdf -ptemplate myskel.cpp | less

    

    4.1.7. Paragraph text is now the default output
    

    If you run the sdf program on a file without giving a target, the text of each paragraph is output. Therefore, you can now do things like:
    

    sdf mydoc.sdf | spell -b
    

    4.1.8. Post filtering
    

    It is now possible to post filter the output of a format driver before the results are written to disk. The -y option of the sdf command can now be used to specify a post filter name. A post filter called xxx maps to a routine called xxx_PostFilter in the file perllib/sdf/post_xxx.pl.
    

    
Note: This feature is only useful for SDF developers who want to create a new output format which is very simliar to an existing one.

    

    

    4.2. Fixes
    

    Heading numbering in HTML and text outputs should be fixed now.
    

    The file and line number in messages should generally be right now. Certain filters may still lead to incorrect line numbers being reported, but messages containing '$fullname', line number 0 or -1 should no longer appear.
    

    Man page generation now works again. Previously, pod2man fell over unless a DOC_PROJECT and DOC_RELEASE was defined.
    

    MIMS HTX and F6 Help formats should be working correctly now. The MIMS_CLIENT_CODE variable must now be specified on the command line when generating MIMS F6 help.
    

    The APIs for SDF's Perl libraries are now present again in the SDF Guru Guide.
    

    

    4.3. Incompatibilities
    

    The sdf2... wrapper scripts are no longer provided - use the -2 option of the sdf command instead.
    

    Given the rationalisation of output format naming, some of the previously used names (e.g. fmrtf, sgmllatex) have been changed. If the sdf command complains about an unknown alias, have a look in sdf.ini to see what the new name is.
    

    The interface to FindFile, a subroutine which some users override to integrate SDF into their CM system, has changed. See the FindFile documentation for details.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



at naming rationalisation">Output format naming rationalisation

    
Automatic figure format conversion

    







SDF 2.001: SDF Release Notes: 2.001beta1




    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    2. 2.001beta1
    

    Enhancements | Fixes | Incompatibilities
    

    

    2.1. Enhancements
    

    The enhancements are:
    


    2.1.1. Better documentation
    

    The SDF Quick Reference has been greatly improved. It now documents 95% of SDF's features rather than the 10% of features most frequently used.
    

    2.1.2. build_title enhancements
    

    If DOC_CODE is set and DOC_NAME is not set, build_title will now lookup DOC_NAME via references data if it can.
    

    The separator between DOC_CODE and DOC_VERSION in DOC_ID can now be controlled by setting DOC_ID_SEP. The default value is '.'.
    

    2.1.3. Library search path
    

    Previously, libraries had to be placed in the perllib/sdf/home directory. Now, sdf's new -Y option can be used to specify a comma-separated list of directories to search for libraries. For example, if you want sdf to search c:\mysdflib and c:\ for libraries on a MS-DOS/Windows system, the command is:
    

      sdf -Yc:\mysdflib,c:\ ...

    

    If your search path for libraries is always the same, the SDFOPTS environment variable can be used, e.g. the following sequence of commands will have the same effect as above:
    

      set SDFOPTS=-Yc:\mysdflib,c:\
  sdf ...

    

    2.1.4. Improved searching rules
    

    Previously, libraries had to be placed in a fixed location but modules used the same search rules as normal files. Now that sdf supports a library search path, libraries, modules and normal files have different search rules. The new rules are:
    

    

    

File type


Directories searched


    

    

libraries


current directory, document's directory, directories on the library path, perllib/sdf/home


    

    

modules


current directory, document's directory, directories on the module path, perllib/sdf/home, perllib/sdf/home/stdlib


    

    

normal files


current directory, document's directory, directories on the include path, perllib/sdf/home


    

    


    The library path and the module path are initialised by sdf's -Y option. The include path is initialised by sdf's -I option. Inheriting a library (via a configuration library or the inherit macro) appends the library's directory to the module path and the include path.
    

    2.1.5. Pretty printing enhancements
    

    Language names are now case insensitive. The keywords for Perl, Java and IDL have also been improved. Python support has been added.
    

    2.1.6. Localisation improvements
    

    Strings within dates and times can now be localised using the datestrings filter. See en_au.sdl for an example.
    

    A Czech locale (cz_cz) is now provided (although it doesn't have localised date strings yet).
    

    2.1.7. New verbose levels and debug tracing
    

    sdf's -v option now supports additional verbose levels:
    

      
2 - show how names of files and libraries are resolved

      
3 - show the directories searched for libraries

      
4 - show the directories searched for modules

      
5 - show the directories searched for normal files.
    

    As before, level 1 shows the post-processing actions and leaves intermediate files around.
    

    In addition, sdf's new -T option can be used to switch on debug tracing. The parameter is a comma-separated list of name-value pairs where each name is a tracing group and each value is the level of tracing for that group. To get the trace output provided by the -v option, one can use the user group like this:
    

      sdf -Tuser=2 ...

    

    This is slightly different from the -v option in that intermediate files are not implicitly kept. Additional tracing groups will be added over time (probably one per output driver).
    

    2.1.8. Miscellaneous stuff
    

    Class filters now support a variables parameter which implicitly defines a variable for each object. The variable name is the same as the object name with non-alphanumeric characters replaced with '_'. (This feature should simplify configuration libraries for projects.)
    

    The jumps macro has been introduced as a more convenient form of the subsections macro. (This feature should simplify web pages for projects.)
    

    KP and KN have been added as paragraph styles. These are shorthands for N[keep_prev] and N[keep_next] respectively.
    

    SUB and SUP have been introduced as phrase styles for subscripts and superscripts respectively. (Consider these experimental features for now, as I haven't had a chance to test them.)
    

    

    2.2. Fixes
    

    The SDF Templates link on the home page included in the distribution now points to the SDF web site as it should.
    

    Mac filename handling should finally be ok now. (However, installation instructions for the Mac are yet to be added.)
    

    Minor corrections have been made to the SDF User Guide.
    

    The conversion of PRN files to GIF files has been improved: a margin is no longer added as ps2gif is prone to incorrectly make it black.
    

    Books generated with the fancy look now have a correctly formatted table of contents.
    

    Java pretty printing has been fixed.
    

    

    2.3. Incompatibilities
    

    The Improved search rules may introduce some unexpected incompatibilities, particularly if custom file searching was implemented. Previously, advanced users could customise the search rules (to integrate a configuration management system, say) by overriding the FindFile subroutine. The default FindFile subroutine no longer searches perllib/sdf/home/stdlib, but otherwise, the search rule for normal files has not changed so custom FindFile routines should still hopefully work. The new routine called FileModule will need to be overriden if your custom FindFile is also needed for finding modules (or similar things like sdg, sdr and sdp files).
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



>

    


    

    2. 2.001beta1
    

    Enhancements | Fixes | Incompatibilities
    

    

    2.1. Enhancements
    

    The enhancements are:
    

      
 directory.
Now, {{CMD:sdf}}'s new -Y option can be used to specify a
comma-separated list of directories to search for libraries.
For example, if you want {{CMD:sdf}} to search F and
F for libraries on a MS-DOS/Windows system, the command is:

>  sdf -Yc:\mysdflib,c:\ ...

If your search path for libraries is always the same, the C
environment variable can be used, e.g. the following sequence of
commands will have the same effect as above:

>  set SDFOPTS=-Yc:\mysdflib,c:\
>  sdf ...

H3: Improved searching rules

Previously, libraries had to be placed in a fixed location but modules
used the same search rules as normal files. Now that {{CMD:sdf}} supports
a library search path, libraries, modules and normal files have different
search rules. The new rules are:

!block table
File_type       Directories_searched
libraries       current directory, document's directory, directories \
                on the library path, F
modules         current directory, document's directory, directories \
                on the module path, F, \
                F
normal files    current directory, document's directory, directories \
                on the include path, F
!endblock

The library path and the module path are initialised by {{CMD:sdf}}'s -Y
option. The include path is initialised by {{CMD:sdf}}'s -I option.
Inheriting a library (via a configuration library or the
{{MAC:inherit}} macro) appends the library's directory to the
module path and the include path.

H3: Pretty printing enhancements

Language names are now case insensitive. The keywords for Perl, Java and
IDL have also been improved. Python support has been added.

H3: Localisation improvements

Strings within dates and times can now be localised using the
{{FILT:datestrings}} filter. See F for an example.

A Czech locale (cz_cz) is now provided (although it doesn't have
localised date strings yet).

H3: New verbose levels and debug tracing

{{CMD:sdf}}'s -v option now supports additional verbose levels:

. 2 - show how names of files and libraries are resolved
. 3 - show the directories searched for libraries
. 4 - show the directories searched for modules
. 5 - show the directories searched for normal files.

As before, level 1 shows the post-processing actions and leaves
intermediate files around.

In addition, {{CMD:sdf}}'s new -T option can be used to switch on
debug tracing. The parameter is a comma-separated list of name-value
pairs where each name is a {{tracing group}} and each value is the
level of tracing for that group. To get the trace output provided
by the -v option, one can use the {{user}} group like this:

>  sdf -Tuser=2 ...

This is slightly different from the -v option in that intermediate
files are not implicitly kept. Additional tracing groups will be
added over time (probably one per output driver).

H3: Miscellaneous stuff

Class filters now support a {{variables}} parameter which implicitly
defines a variable for each object. The variable name is the same as
the object name with non-alphanumeric characters replaced with '_'.
(This feature should simplify configuration libraries for projects.)

The {{MAC:jumps}} macro has been introduced as a more convenient form
of the {{MAC:subsections}} macro.
(This feature should simplify web pages for projects.)

KP and KN have been added as paragraph styles. These are shorthands
for N[keep_prev] and N[keep_next] respectively.

SUB and SUP have been introduced as phrase styles for subscripts and
superscripts respectively. (Consider these experimental features for
now, as I haven't had a chance to test them.)

H2: Fixes

The {{SDF Templates}} link on the home page included in the distribution
now points to the SDF web site as it should.

Mac filename handling should finally be ok now. (However, installation
instructions for the Mac are yet to be added.)

Minor corrections have been made to the {{DOC:SDF User Guide}}.

The conversion of PRN files to GIF files has been improved: a margin
is no longer added as ps2gif is prone to incorrectly make it black.

Books generated with the {{fancy}} look now have a correctly
formatted table of contents.

Java pretty printing has been fixed.

H2: Incompatibilities

The {{SECT: Improved search rules}} may introduce some unexpected
incompatibilities, particularly if custom file searching was implemented.
Previously, advanced users could customise the search rules (to integrate
a configuration management system, say) by overriding the {{SUBR:FindFile}}
subroutine. The default {{SUBR:FindFile}} subroutine no longer searches
F, but otherwise, the search rule for normal
files has not changed so custom {{SUBR:FindFile}} routines should still
hopefully work. The new routine called {{FileModule}}
will need to be overriden if your custom {{SUBR:FindFile}} is also
needed for finding modules (or similar things like {{sdg}}, {{sdr}} and
{{sdp}} files).
sdf-2.001/doc/release/2000b9.html010064400042570001753000000136750672242646300160340ustar00iancmtr00000400000236






SDF 2.001: SDF Release Notes: 2.000beta9




      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      8. 2.000beta9
      

      Enhancements | Fixes | Incompatibilities
      

      

      8.1. Enhancements
      

      8.1.1. Overview
      

      The contrib directory now contains an SDF mode for Emacs and a rudimentary RTF to SDF converter. Like other things in the contrib directory, these are unsupported but may be useful.
      

      The other enhancements are:
      


      Further details are provided below.
      

      8.1.2. Improved documentation
      

      The documentation has been improved in a number of ways:
      

        

      1. The SDF User Guide has been revised and updated.

      2. The SDF Guru Guide now has a chapter on extending SDF.

      3. The manuals provided with SDF now have an index.

      4. The SDF 2.000 Migration Guide is no longer provided in the standard distribution (as it is only useful for SDF 1.x users within Mincom).
      

      8.1.3. Improved text tables
      

      Thanks to Tim MacKenzie (Tim.MacKenzie@fulcum.com.au): tables output in txt format have been improved:
      

        

      • all cells are now word wrapped (not just the last one in each row)

      • cell alignment is now supported

      • Line paragraph styles within cells are now supported

      • heading underlining has been improved.
      

      8.1.4. New filters
      

      Thanks to Tim Hudson (tjh@cryptsoft.com), a number of new filters are now available:
      

      

      

Name


Description


      

      

built-in:


 


      

      

nofill


format a set of lines


      

      

simple


generic filter for building other filters


      

      

defines.sdm:


 


      

      

product_defines


define products and variables for each


      

      

section_defines


define section names as variables


      

      

testcase.sdm:


 


      

      

testcases


collect testcases from A3s into a table at the end of document


      

      


      8.1.5. Citation support
      

      References can now be easily numbered and the numbers can be inserted in paragraph text. The new features which make this possible are:
      

        

      • the references class now supports a Cite attribute which produces a string of the form [n]

      • the REF phrase style now supports a cite attribute which inserts the reference number using the syntax [n].
      

      For example:
      

      H1: References

!include "doc.reg"; references; columns='Cite,Document'

H1: Some heading

Refer to {{REF[cite]ABC}} and {{REF[cite]ME2}}.

      

      If you want to put the reference table at the back of the document, it is necessary to forward declare which documents will be cited by using the cited parameter of the references filter. The table of cited references can then be built later by using the catalog macro. For example:
      

      !include "doc.reg"; references; cited

H1: Some heading

Refer to {{REF[cite]ABC}} and {{REF[cite]ME2}}.

H1: References

!catalog references 'cited'; columns='Cite,Document'

      

      

      8.2. Fixes
      

      FrameMaker 4.x compatibility has been improved thanks to a patch from Tim MacKenzie (Tim.MacKenzie@fulcum.com.au).
      

      The document control section (on the inside of the front cover) of project documents has been improved. (In fact, it is now much easier to customise output of the build_title macro.)
      

      The about filter was fixed to work better with documents formatted using the infomap look.
      

      For Windows 3.x/MS-DOS users:
      

        

      • the sdftest.bat file has been fixed

      • the sdfget.bat file has been added.
      

      Date formatting for years >= 2000 has been fixed.
      

      

      8.3. Incompatibilities
      

      None.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/release/2000b4b.html010064400042570001753000000021750672242656600161660ustar00iancmtr00000400000236






SDF 2.001: SDF Release Notes: 2.000beta4b




      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      21. 2.000beta4b
      

      This is the first publicly available release of SDF 2.000.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/release/2000b4c.sdf010064400042570001753000000026570630476414200157730ustar00iancmtr00000400000236H1: 2.000beta4c

!subsections "Enhancements,General Fixes,HTML Fixes,HLP Fixes,Incompatibilities"

H2: Enhancements

None.

H2: General Fixes

If an imported figure is not given an extension, an
extension is added based on the target format:

* {{hlp}} for Windows help
* {{gif}} for [[HTML]]
* {{eps}} otherwise ({{2:not}} epsi).

The {{DOC:SDF User Guide}} had most of the {{Advanced Features}}
section commented out - this has now been fixed. The architecture
figure in {{SDF Getting Started}} has been updated to show
direct [[HTML]] generation.

All hypertext jumps throughout the documentation should now be working
correctly.

H2: HTML Fixes

Blank cells in tables no longer look ugly.

References and terms are now formatted as a table.

H2: HLP Fixes

URLs no longer come out in blue.

Bitmaps no longer need to be in the directory when {{CMD:hcp.exe}}
is executed, as the HPJ file now contains a search path.
The HPJ file can still be generated on a Unix box (even though
{{CMD:hcp.exe}} runs under [[Windows]]) as the search path is build
using a new optional variable called SDF_DOSHOME.

Any option in the HLP file (xxx, say) can be set via the matching
SDF variable called HLP_OPTIONS_xxx.

{{EMAIL:tim.hudson@mincom.com}} has fixed a number of bugs in
{{CMD:mif2rtf}} including:

* table titles now work
* formatted phrases at the beginning of a note or bulleted list now work
* notes now have a closing line.

H2: Incompatibilities

None.
sdf-2.001/doc/release/2000b6a.sdf010064400042570001753000000044620635011350400157560ustar00iancmtr00000400000236H1: 2.000beta6a

!subsections "Enhancements,Fixes,Incompatibilities"

H2: Enhancements

The documentation now includes a draft version of an overview paper
called {{DOC:The SDF Document Development System}}. This is
recommended reading for all SDF users.

For [[Mincom]] users, Mincom-style title pages can now be generated
for technical documents. To do this, initialise the {{VAR:OPT_LOOK}}
variable using the {{MAC:init}} macro on the top line of the document
like this:

E:   !init OPT_LOOK='mincom'

{{CMD:sdf}}'s -k option can also be used to override the default look.
For example:

E:   sdf -2ps -kmincom mydoc.sdf

The {{DOC:SDF Reference}} has been improved - most of the filters and
macros now have a description and an example.

The {{MAC:build_title}} macro now outputs the date the document was
last modified when the target is HTML.

Section jumps across documents are now supported via the {{doc}}
phrase attribute. For example:

!block example; pure
See {{SECT[doc='SDF User Guide'] Event Processing}}
in the {{DOC:SDF User Guide}} for further details.
!endblock

The default {{target}} for the {{FILT:inline}} filter is now {{html}}.

The {{FILT:namevalues}} filter can now be used to specify a table of
names and values. This is useful at the top of QSD procedures, etc.

The search order for figure importing into PostScript documents is
now eps, pct, gif and finally bmp.

H2: Fixes

Under certain circumstances, figure importing into [[PostScript]]
documents was broken by the previous version. It should now be
working again.

Tables with titles no longer cause blank pages to be appended to the
end of the document. This was a [FrameMaker]] 5.0 bug which I now
workaround by producing "simple" titles. As a result, table titles
are no longer repeated when a table crosses a page boundary.

{{Encapsulated PostScript}} figures output by {{PRD:Visio}} are now
correctly sized.

URLs in [[PostScript]] documents are no longer blue.

A large number of bugs in the QSD templates have been fixed. These had
been introduced by the upgrade from [[FrameMaker]] to version 5.

The {{MAC:build_title}} macro (as implemented in the {{plain}} library)
no longer outputs a page break after the {{Document control}} stuff.

Change bars no longer cause example text (e.g. source code) to be badly
formatted in HTML.

H2: Incompatibilities

None.
fied when the target is HTML.

Section jumps across documents are now supported via the {{doc}}
phrase attribute. For example:

!block example; pure
See {{SECT[doc='SDF User Guide'] Event Processing}}
in thsdf-2.001/doc/release/2000.html010064400042570001753000000223550672242643200155700ustar00iancmtr00000400000236






SDF 2.001: SDF Release Notes: 2.000




      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      3. 2.000
      

      Enhancements | Fixes | Incompatibilities
      

      

      3.1. Enhancements
      

      As this is the first public production release of SDF, the focus has been to fix bugs and improve the documentation. The enhancements are:
      

        

      1. Better documentation

      2. Better packaging

      3. Better support for non-English languages

      4. Table enhancements

      5. Object management enhancements

      6. Example/verbatim enhancements

      7. Miscellaneous things.
      

      3.1.1. Better documentation
      

      The following documents have been improved:
      


      The SDF Web Site has also been improved by the addition of the following sections:
      


      3.1.2. Better packaging
      

      The PostScript and PDF versions of the documentation have been removed from the core distribution making it substantially smaller. The PostScript and PDF documents can still be accessed as needed from http://www.mincom.com/mtr/sdf/catalog.html.
      

      The SDF distribution is now CPAN-compliant, thanks to the efforts of Achim Bonnet (ach@mpe.mpg.de). As a result, several things have changed:
      

        

      • installation is much easier

      • the SDFHOME environment variable is no longer used to find files:
          

        • Perl libraries are now assumed to be available on Perl's library path

        • configuration files, including sdf.ini, are now located within the sdf/home directory somewhere on Perl's library path.
        

      • the test directory has been renamed to t

      • the sdftest script is now located within the t directory.
      

      3.1.3. Better support for non-English languages
      

      Russian characters (and characters from other non-English languages) are now hopefully better handled for users running on Perl 5.004 or later. (Thanks to Nikolaj Logvinov for this fix.)
      

      A German locale (de_de.sdl) has also been added. (Thanks to Andreas Lohrum for this.)
      

      3.1.4. Table enhancements
      

      The table filter now supports some new parameters:
      

        

      • colvaligns - a comma-separated list of vertical alignments values (Top, Middle, Bottom, Baseline) for columns. For the lazy people, a single word containing the letters T, M, B and L can be used for the value as well.

      • select - a comma-separated list of columns to display.

      • delete - a comma-separated list of columns to delete.
      

      The delete parameter is particularly useful if you want to sort or filter a table (using the sort and where parameters, respectively) using a column which you don't want in the output.
      

      3.1.5. Object management enhancements
      

      Class filters also support the colaligns, colvaligns, select and delete parameters provided by the table filter.
      

      A new feature called object views has been introduced. See Understanding Class Interfaces within the SDF Reference for details.
      

      The catalog macro can now apply the filtering mask to an attribute other than the name. To specify the attribute, use a mask of the format:
      

             attribute":"mask_pattern

      

      3.1.6. Example/verbatim enhancements
      

      The verbatim and example filters now support a listitem attribute (ala the table filter), although this attribute currently only indents the text for these filters.
      

      The skipheader attribute of the example and verbatim filters now uses the lang attribute, if any, to determine the commenting conventions. Previously, it assumed comments began with # and were terminated by the end of line.
      

      3.1.7. Miscellaneous things
      

      A module with support for Use Cases has been added (stdlib/usecases.sdm).
      

      The insert macro can now be used to insert/execute a macro which may not be defined.
      

      

      3.2. Fixes
      

      sdftest on Windows/DOS systems now works.
      

      For plain text output, unwanted lines between consecutive example paragraphs have been removed.
      

      File handling on the Macintosh should now be fixed. (Thanks to David Schooley.)
      

      Within sdfget reports, * processing now works again.
      

      When generating an rtf file via FrameMaker, the intermediate mif file is now deleted.
      

      Inner and Outer no longer produce warnings as unknown values for the align parameter for the table or box filter.
      

      Consecutive normal paragraphs within a box filter or a multi-paragraph table cell no longer run together when HTML is generated.
      

      The about filter works correctly again for HTML output.
      

      The FILE phrase style is now mapped to TT for HTML output.
      

      The OPT_PAGE_SIZE and OPT_WIDTH variables are no longer ignored if they are set via the init macro.
      

      Generating PostScript and DVI via SGML-Tools 1.02 or later should now work.
      

      Column alignments within tables are no longer ignored when SGML is generated.
      

      None is now a legal value for cell rulings within tables. (Thanks to Cliff Krumvieda for this fix.)
      

      

      3.3. Incompatibilities
      

      Configuration files are now located differently. See Better packaging, above, for details.
      

      The scripts in the bin directory now use /usr/local/bin/perl, rather than /usr/local/bin/perl5, i.e. the default version of Perl installed at a site is now assumed to be 5.003 or later.
      

      The PDF and PostScript versions of the documentation are no longer shipped with the SDF package. Instead, the document catalog points to PDF and PostScript files on SDF's web site. (This change was made to reduce the size of the SDF distribution.)
      

      If you are generating outputs via SGML-Tools, you now need SGML-Tools 1.02 or later (rather than 0.99 or later).
      

      The paper document style now leaves headings as they are defined. Previously, it implicitly changed H-style headings to P-style headings and slid them down one level.
      

      The sdtgen script has been renamed sdngen to reflect the fact that sdn is the extension now used for tuning modules.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



HREF="#2.000 - Enhancements">Enhancements | Fixes | Incompatibilities
      

      

      3.1. Enhancements
      

      As this is the first public production release of SDF, thsdf-2.001/doc/release/2000b10.sdf010064400042570001753000000322300647531555400157030ustar00iancmtr00000400000236H1: 2.000beta10

!subsections "Enhancements,Fixes,Incompatibilities"

H2: Introduction

The primary objectives of this release are:

^ To provide a "working prototype" for a POD-friendly SDF.
+ To rationalise SDF's escaping mechanisms and stabilise it's syntax.
+ To provide greatly improved man page generation (via {{pod2man}}).
+ To provide PostScript generation without needing a commercial tool.

I still need to fix up some bugs and loose ends
with respect to the POD stuff, but there's enough working
to be useful (in my opinion, at least). In particular,
the core POD documentation provided with Perl 5.004 can be:

^ Converted to SDF and back to POD with a high degree of success
  (99.95% if the perltoc.pod file is excluded).
+ Converted to HTML and plain text using the {{CMD:sdf}} program.

If you're an existing POD user, please read the
{{DOC:SDF for POD Users}} tutorial. If you find
a bug not listed in the PODNOTES file,
email the details to {{EMAIL:sdf-bugs@mincom.com}}.

If you're an existing SDF user, please note that
most of the documentation doesn't yet reflect the
changes outlined below. You will also need to
take care with the {{SECT[jump="#2.000beta10 - Incompatibilities"]
Incompatibilities}} outlined below.

H2: Enhancements

The enhancements are:

!block sections
. SDF is now POD-friendly
. Syntax Enhancements
. Verbatim paragraphs
. Special symbol escapes
. Enumerated lists
. New macros
. New phrase styles
. Manpage, LaTeX and fancy text support
. PostScript generation without a commercial tool
. POD to SDF conversion
. Nesting of POD within SDF
. Automatic translation of POD files
. Configuration library for Perl documentation.
. Topic previewing
. Easier text width control
!endblock

Further details are provided below.

H3: SDF is now POD-friendly

POD users can now use SDF or migrate to SDF when
POD isn't powerful enough. In particular:

* POD can now be {{converted}} to SDF and vice versa
* SDF can now be {{nested}} inside POD and vice versa
* SDF is now largely upwardly compatible with POD in
  terms of syntax and functionality.

A {{CMD:poddiff}} program is provided so that users can
translate POD -> SDF -> POD and compare the generated
POD with the original.


H3: Syntax Enhancements

Any SDF macro can now be called via POD's = syntax, i.e.
if a macro call starts with an = character, the call is
terminated by the next blank line.

As a consequence of its new meaning, = is no longer available
as a shorthand for the E paragraph tag. However, the > character
can now be used as a shorthand for the V (verbatim) paragraph
tag. See {{SECT:Verbatim paragraphs}} below.

Any phrase style which is a single capital letter can now
be specified using POD's [A-Z]<..> syntax. So, the following
lines are equivalent:

>   Hello {{B:world}}
>   Hello B

Paragraph and phrase styles must now start with a capital letter,
digit or underscore. As a result, the following SDF will now come
out as expected.

V:  The following documents should be
V:  reviewed:

Previously, SDF would warn about {{reviewed}} being an unknown
paragraph style. As a special case, phrases which look like URLs
are still assumed to be so.

Outside of blocks and multi-line macros calls, a \ at the
start of a line now escapes a special character or pattern,
including itself. A \ can also be used to escape a ] character
within a set of attributes.

At the end of a !-style macro call line:

* a single \ continues the macro onto the next line
* exactly 2 backslashes means a single backslash (with no continuation)
* N backslashes (N >= 3) means N-1 backslashes with continuation


H3: Verbatim paragraphs

For fixed-width verbatim paragraphs, the > special tag or
V paragraph style can now be used. For example:

>>  {{Hello world}}

or

>V:  {{Hello world}}

The result is:

>  {{Hello world}}

The new {{verbatim}} filter can be used to mark a block
of text as verbatim.

In fact, the interpolation of embedded characters within
the text of any paragraph can be disabled by setting the
{{verbatim}} paragraph attribute. For example:

>  N[verbatim] {{Hello world}}

The result is:

N[verbatim] {{Hello world}}

H3: Special symbol escapes

SDF uses a number of special symbols inside paragraphs:

* A-ZE and > - delimit {{concise}} phrases
* E<2{> and E<2}> - delimit {{verbose}} phrases
* E<2[> and E<2]> - delimit expressions (e.g. variables).

If you need to include one of these symbols in a paragraph,
use the appropriate escape as shown below.

!block verbatim
    Symbol      Escape
    <           E
    >           E
    {{          E<2{>
    }}          E<2}>
    [[          E<2[>
    ]]          E<2]>
!endblock

Note the following rules:

^ It isn't necessary to escape any symbols within:
  - paragraphs tagged with the V style or > tag
  - paragraphs given the verbatim attribute
  - paragraphs within a verbatim block

+ It is only necessary to escape a < when it appears after
  a capital letter.

+ It is only necessary to escape a > inside a concise phrase.
  In particular, > is implicitly escaped within a verbose phrase.

H3: Enumerated lists

In addition to bulleted, ordered and plain lists, SDF now
supports enumerated lists, i.e. lists where each item is a label.
Each enumerated list item is tagged with either:

* a & special tag (& .. &&&&&& like the other lists), or
* the LIn style, where n = 1 .. 6.

For example:

!block verbatim
& BTW
. by the way
& FYI
. for your information
& RTFM
. read the flamin' manual
!endblock

The result is:

& BTW
. by the way
& FYI
. for your information
& RTFM
. read the flamin' manual

H3: New macros

All of POD's commands are now available as SDF macros.
The new macros are:

!block table
Macro           Meaning
head{{n}}       level {{n}} heading (n = 1 .. 6)
over [N]        begins a list (N is the suggested indentation which is ignored)
item string     label for item in a list
back            ends a list
pod             does nothing
cut             ignore text until an = is found at the start of a line
for X Y         Y is target-specific output for X
begin X         begin target-specific output for X
end X           end target-specific output for X
!endblock

See the perlpod manpage for further details.

H3: New phrase styles

All of POD's interior sequences are now available as SDF phrase styles.
The new phrase styles are:

!block table
Style           Meaning
B               bold
C               code
E               special symbol or HTML escape
F               file
I               italics
L               POD-style link
S               text contains non-breaking spaces
X               an index entry
Z               does nothing
!endblock

See the perlpod manpage for further details on the meanings
of these tags.

Note: The S and X tags are not yet working for most output formats. 

H3: Manpage, LaTeX and fancy text support

The {{sdf -2man ...}} command now generates a {{.out}} file in POD format and
runs {{CMD:pod2man}}. The old man page generation software was
limited in scope and quite buggy, so this will hopefully improve
things in the short-to-medium term.
The F output driver has been moved to the
F directory just in case anyone
really wants to use it instead.

The {{sdf -2latex ...}} command now generates a {{.out}} file
in POD format and runs {{CMD:pod2latex}}. This creates a {{.out.tex}}
file which should probably be renamed to delete the {{.out}} bit.

The {{sdf -2text ...}} command now generates a {{.out}} file
in POD format and runs {{CMD:pod2text}}. For compatibility with
{{CMD:pod2text}}, this sends the output to standard output.

Note: Plain text output is still available via the -2txt option.

Hopefully, someone will provide fully functional manpage and LaTeX
drivers (complete with table support) eventually.

H3: PostScript generation without a commercial tool

SDF can now generate PostScript without needing a commercial tool.
This can be done by:

^ Using {{sdf -2podps ...}} which generates PostScript directly via the
  freely available {{CMD:pod2ps}} program.

+ Using {{sdf -2man ...}} which generates a man page which can be
  converted to PostScript by using the appropriate (*roff) tools.

+ Using {{sdf -2latex ...}} which generates a LaTeX document which can be
  converted to PostScript by using LaTeX.

In general, the output via these methods isn't as good as the
PostScript generated via FrameMaker, but it may be good enough.
In particular, certain looks (e.g. infomap) are not available.

H3: POD to SDF conversion

A {{CMD:pod2sdf}} program is now available which is a wrapper
around  a Perl module called Pod::Sdf. The SDF generated is more or less
identical to the input POD, except that verbatim lines
are tagged with a leading ">". The usage of {{CMD:pod2sdf}} is:

>  pod2sdf [-m] podfile > outfile

If the -m option is provided, the document is converted as
a main document, rather than a topic, i.e. the NAME section is
converted to a {{MAC:build_title}} macro rather than a {{head1}}
macro.

POD authors can escape to SDF if and when they need to by
using the "=for sdf" and/or "=begin/end sdf" command pair.
For example:

>  =for sdf
>  !block table
>  Name    Meaning
>  POD     Plain Old Documentation
>  SDF     Simple Document Format
>  !endblock

If you want the rest of a POD file to be in SDF, simply put
in an "=begin sdf" - the closing "=end sdf" isn't necessary.

H3: Nesting of POD within SDF

POD can now be nested inside SDF via the new {{FILT:pod}} filter
(which is another wrapper around the Pod::Sdf module). e.g.

>   !block pod
>   =head2 My B
>
>      Some verbatim text
>   !endblock

Note: Within the pod filter, all lines before the first command
is ignored and leading whitespace implies a verbatim paragraph.

The pod filter can also be specified to the {{MAC:include}} and
{{MAC:execute}} macros. For example:

>  !include "perlre.pod"; pod
>  !execute "getpod 'hello.c'"; pod

where {{getpod}} is a fictitious program which outputs POD to standard output.

H3: Automatic translation of POD files

If a file with a {{.pod}}, {{.pm}} or {{.PL}} extension
is provided as an argument to the {{CMD:sdf}} command,
the {{FILT:pod}} filter is implicitly applied. So

. sdf -2html perlre.pod

will generate HTML for F using SDF's HTML output driver.
You can also explicitly request pod prefiltering via the -p option.
e.g.

. sdf -2html -ppod abc.pd

When pod prefiltering happens, the output is assumed to be a
main document.

H3: Configuration library for Perl documentation

A configuration library for building Perl's documentation
is provided. The main thing which this provides is
semi-intelligent hypertext link generation between Perl's
standard documentation and its library documentation.
Within this library, the HTML root directory (equivalent to
{{CMD:pod2html}}'s --htmlroot flag) can be controlled via the
PERL_HTML_ROOT variable. The default value is /perl.
Typical usage is:

>  sdf -2html -cperl -DPERL_HTML_ROOT=/nmanual/perl perl*.pod

At the moment, this library is only required for HTML generation.

H3: Topic previewing

When editing a topic within a large document, it can
be useful to only compile that topic in order to
preview its appearance. The new -H option can be used
to adjust the initial heading level like this:

>  sdf -2ps -H3 -kinfomap mytopic.sdf

Without the -H3 option, the H1s within F
would come out as level 1 headings, rather than level 3
headings.

H3: Easier text width control

The width of text output can now be controlled from the command
line by using the new -w option to the {{CMD:sdf}} program.


H2: Fixes

Special characters in headings (like [) no longer cause problems.

The POD output driver has been fixed. In particular, the generation
of list items has been fixed.

Some bugs in the pretty printing of source code have been fixed:

* 80 character lines should now fit
* The >> character sequence is no longer lost
* form feeds become page breaks.

Handling of multi-line macro calls within a block or macro
has been fixed.

The {{FILT:box}} filter no longer centers the contents of the box
unless the {{lines}} parameters is provided.


H2: Incompatibilities

This release now requires Perl 5. If you are still using Perl 4.036,
you will need to upgrade.

As paragraph and phrase styles can no longer start with a
lowercase character, you will need to rename any user-defined
styles which violate this rule.

Lines within paragraphs which begin with the > or & character
will now need to be escaped by a leading \.

Wide example now use a slightly smaller font.

The default values for the DOC_DISTRIBUTION and DOC_STATUS variables
are now empty strings. Previously, they were "COMMERCIAL IN CONFIDENCE"
and "Draft" respectively.

Making SDF POD-friendly has introduced a number of incompatibilities.
These are summarised below:

* The = character is no longer a shorthand for E: - it is now
  used for multi-line macro calls.

* Existing paragraphs which contain the sequence [A-Z]<..>
  (i.e. a POD-like phrase) as text will need to be changed.

* The S (strong) and E (example) phrase styles have been renamed to
  ST and EX respectively. S and E now have the same meaning as
  their POD counterparts, i.e. "text contains non-breaking spaces"
  and "escape" respectively. As the S tag was often used for
  "symbols" (i.e. variables, subroutines) within a library,
  a Y tag has been introduced for this purpose.
graphs tagged with the V style or > tag
  - paragraphs given the verbatim attribute
  - paragraphs within a verbatim block

+ It is only necessary to escape a < when it appears after
  a capital letter.

+ It is only necessary to escape a > inside a concise phrase.
  In particular, > is implicitly escaped within a verbose phrase.

H3: Enumerated lists

In adsdf-2.001/doc/release/2000b4c.html010064400042570001753000000064510672242656500161670ustar00iancmtr00000400000236






SDF 2.001: SDF Release Notes: 2.000beta4c




      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      20. 2.000beta4c
      

      Enhancements | General Fixes | HTML Fixes | HLP Fixes | Incompatibilities
      

      

      20.1. Enhancements
      

      None.
      

      

      20.2. General Fixes
      

      If an imported figure is not given an extension, an extension is added based on the target format:
      

        

      • hlp for Windows help

      • gif for HTML

      • eps otherwise (not epsi).
      

      The SDF User Guide had most of the Advanced Features section commented out - this has now been fixed. The architecture figure in SDF Getting Started has been updated to show direct HTML generation.
      

      All hypertext jumps throughout the documentation should now be working correctly.
      

      

      20.3. HTML Fixes
      

      Blank cells in tables no longer look ugly.
      

      References and terms are now formatted as a table.
      

      

      20.4. HLP Fixes
      

      URLs no longer come out in blue.
      

      Bitmaps no longer need to be in the directory when hcp.exe is executed, as the HPJ file now contains a search path. The HPJ file can still be generated on a Unix box (even though hcp.exe runs under Windows) as the search path is build using a new optional variable called SDF_DOSHOME.
      

      Any option in the HLP file (xxx, say) can be set via the matching SDF variable called HLP_OPTIONS_xxx.
      

      tim.hudson@mincom.com has fixed a number of bugs in mif2rtf including:
      

        

      • table titles now work

      • formatted phrases at the beginning of a note or bulleted list now work

      • notes now have a closing line.
      

      

      20.5. Incompatibilities
      

      None.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/release/index.html010044400042570001753000000041760672242656600163250ustar00iancmtr00000400000236






SDF 2.001: SDF Release Notes




      

      

      Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      SDF Release Notes
      

      MTR-SDF-0008.001 (Final)
      

      Ian Clatworthy
      

      25 May 1999
      

      

      

      

      

      Table of Contents
      


      

      

      

      Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/release/2000b6b.sdf010064400042570001753000000007640622022216600157610ustar00iancmtr00000400000236H1: 2.000beta6b

!subsections "Enhancements,Fixes,Incompatibilities"

H2: Enhancements

Tables now have a new style called {{box}} that simply puts a thin-line
around the table.

The cover page generated for the {{mincom}} look has been improved.

H2: Fixes

If a look library and a configuration library had the same name,
only one was begin loaded. This has now been fixed.

Nested jumps within [[HTML]] files no longer cause problems - the
inner jump is now ignored.

H2: Incompatibilities

None.
sdf-2.001/doc/release/2000b6a.html010064400042570001753000000102270672242655300161600ustar00iancmtr00000400000236






SDF 2.001: SDF Release Notes: 2.000beta6a




      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      17. 2.000beta6a
      

      Enhancements | Fixes | Incompatibilities
      

      

      17.1. Enhancements
      

      The documentation now includes a draft version of an overview paper called The SDF Document Development System. This is recommended reading for all SDF users.
      

      For Mincom users, Mincom-style title pages can now be generated for technical documents. To do this, initialise the OPT_LOOK variable using the init macro on the top line of the document like this:
      

         !init OPT_LOOK='mincom'

      

      sdf's -k option can also be used to override the default look. For example:
      

         sdf -2ps -kmincom mydoc.sdf

      

      The SDF Reference has been improved - most of the filters and macros now have a description and an example.
      

      The build_title macro now outputs the date the document was last modified when the target is HTML.
      

      Section jumps across documents are now supported via the doc phrase attribute. For example:
      

      See {{SECT[doc='SDF User Guide'] Event Processing}}
in the {{DOC:SDF User Guide}} for further details.

      

      The default target for the inline filter is now html.
      

      The namevalues filter can now be used to specify a table of names and values. This is useful at the top of QSD procedures, etc.
      

      The search order for figure importing into PostScript documents is now eps, pct, gif and finally bmp.
      

      

      17.2. Fixes
      

      Under certain circumstances, figure importing into PostScript documents was broken by the previous version. It should now be working again.
      

      Tables with titles no longer cause blank pages to be appended to the end of the document. This was a [FrameMaker]] 5.0 bug which I now workaround by producing "simple" titles. As a result, table titles are no longer repeated when a table crosses a page boundary.
      

      Encapsulated PostScript figures output by Visio are now correctly sized.
      

      URLs in PostScript documents are no longer blue.
      

      A large number of bugs in the QSD templates have been fixed. These had been introduced by the upgrade from FrameMaker to version 5.
      

      The build_title macro (as implemented in the plain library) no longer outputs a page break after the Document control stuff.
      

      Change bars no longer cause example text (e.g. source code) to be badly formatted in HTML.
      

      

      17.3. Incompatibilities
      

      None.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/release/2000b7a.sdf010064400042570001753000000015420622022216600157540ustar00iancmtr00000400000236H1: 2.000beta7a

!subsections "Enhancements,Fixes,Incompatibilities"

H2: Enhancements

The background colour of a table can now be set via the {{bgcolor}}
parameter of the {{FILT:table}} filter.

The COLOR_GREY variable is now supported.

Headings at level 6 are now supported.

The QSD front cover template now supports footers.
(This is used within the MIMS documentation to show the
MIMS version number.)

H2: Fixes

Text output (txt) works again.

Memo title blocks are formatted correctly again.

The HTML generation of Delphi documents now has the "Description"
heading in it, as requested by John Benders. (Previously,
the heading was removed for all non-hlp targets. It is
now kept for all non-ps targets.)

Topics mode now works for headings containing commas.

The {{box}} table style is now available inside QSD templates.

H2: Incompatibilities

None.

sdf-2.001/doc/release/2000b11.sdf010064400042570001753000000124730636331362600157050ustar00iancmtr00000400000236H1: 2.000beta11

!subsections "Enhancements,Fixes,Incompatibilities"

H2: Enhancements

The enhancements are:

!block sections
. Documentation improvements
. Better Perl documentation
. Multi-line records in tables
. Better man page support
. Better PDF support
. More flexible embedded documentation support
. SDF expressions within inline blocks.
!endblock

Further details are provided below.


H3: Documentation improvements

The documentation has been improved in the following ways:

* it is now supplied in PDF format (in addition to PostScript and HTML)
* the white paper, quick reference and tutorials are now
  single HTML documents, rather than sets of topics
* the home page has been improved
* the FAQ has been expanded and added to the catalog.

H3: Better Perl documentation

The new {{CMD:mkpldocs}} program can be used to build the Perl
documentation suite. Usage is:

>  cd 
>  mkpldocs all

The {{perl}} configuration library now generates better looking HTML
with relative URLs. As such, the documentation can be easily moved
after it is generated.

See {{http://www.mincom.com/mtr/perl/pod/perl.html}} for a publicly
available version of the HTML generated by SDF for Perl 5.004_01.
If you want a local copy, you can download it in either {{tar.gz}} or
{{zip}} format. The URLs are:

. {{ftp://ftp.mincom.com/pub/mtr/sdf/perl/perlshtml-5.004_01.tar.gz}}
. {{ftp://ftp.mincom.com/pub/mtr/sdf/perl/psh50041.zip}}


H3: Multi-line records in tables

Records in tables can now be continued onto the next line by
terminating the line with a backslash. Like !-style macros:

* exactly 2 terminating backslashes means a real backslash
* N (N >= 3) terminating backslashes means N-1 real backslashes with
  continuation.


H3: Better man page support

The -2man option nows sends output to standard output, rather than
to a .man file. This improves compatibility with {{CMD:pod2man}}
and makes it easier to do things like:

>  sdf -2man faq.sdf | nroff -man | less

The following variables can now be used to change the headers and
footers generated for man pages:

!block table
Variable        Meaning
DOC_PRODUCT     the center string in the header (e.g. Simple Document Format)
DOC_PROJECT     the release name for the product (e.g. SDF 2.000beta11)
DOC_SECTION     the section this man page is in
!endblock

These variables are typically defined in a configuration library.
You can also provide them on the command line using the -D and/or
\-f options like this:

>  sdf -2man -DDOC_SECTION=3 ...
>  sdf -2man -fsection=3 ...


H3: Better PDF support

PDF support has been improved. To generate PostScript (via FrameMaker)
and distill it to PDF, the new -2pdf option can be used like this:

>  sdf -2pdf mydoc.sdf

If PostScript is being generated via a FrameMaker book or via
{{CMD:pod2ps}}, the -zpdf option can be used like this:

>  sdf -2book -zpdf mydoc.sdf
>  sdf -2podps -zpdf mydoc.pdf

Note: The -2pdf option assumes that you have 
[[Adobe]] {{PRD:Acrobat}}'s {{CMD:distill}} program on your path.


H3: More flexible embedded documentation support

Mark Stavar's enhancements to SDF's embedded documentation support
have now been integrated, but are not yet documented. These
enhancements make it possible to put documentation into
buffers which are formatted independently of the main one.
Amongst other things, this makes it possible to have
subtopics for each procedure/method/function in a library,
each with its own set of {{Interface}}, {{Description}}, {{Examples}}, etc.

When time permits, I'll put together a tutorial explaining the
different ways SDF can be used for embedded documentation.
Until then, if you need further information on the multiple
buffer approach, send me some email.


H3: SDF expressions within inline blocks

SDF expressions are now supported within text processed by
the {{FILT:inline}} filter thanks to a patch from Tim MacKenzie.
For example,

!block example; lang='sdf'
!define VERB "is"
...
!block inline; expand

      
This HTML [[VERB]] expanded.
!endblock
!endblock


H2: Fixes

Most of the links within the Perl documentation should now work correctly.

S phrases (i.e. phrases with non-breaking spaces) now work correctly
for HTML and MIF formats. The {{nbsp}} variable has also been introduced
as another way to insert non-breaking spaces.

HTML escapes (E phrases and CHAR phrases) are now supported by the
mif and plain text drivers.

The default language used for pretty printing .h files is now C++,
rather than C.

Non-last multi-line cells are now working correctly for delimited
format (but aren't yet supported for fixed-width format).

Included some patches from Tim MacKenzie for:

* handling filenames with non-alphanumeric characters like -
* removing the need to have {{CMD:mif2rtf}} and {{CMD:sdfbatch}} on your path
* improving compatibility with FrameMaker 4
* better packaging of Pod:Sdf.pm.

To fix the formatting of MIMS specifications, the +ms option has
been introduced.

When a FrameMaker book is generated:

* the list of figures, list of tables and index, if any, should now
  appear in the table of contents
* the last chapter now has a terminating line for infomap documents.

Missing libraries and modules now create a warning rather than an error.

The default footer for manuals has been changed to:

* include the project name, if any
* exclude the status if it's {{Final}}.


H2: Incompatibilities

None.
sdf-2.001/doc/release/2000b5.sdf010064400042570001753000000056640635011350400156210ustar00iancmtr00000400000236H1: 2.000beta5

!subsections "Enhancements,General Fixes,HTML Fixes,HLP Fixes,Incompatibilities"

H2: Enhancements

H3: Performance

Performance is now 2-3 times faster for most documents.
There is still some work to do here, but the performance
is now "respectable" (rather than "disappointing").

H3: Perl 5

This release has been tested with Perl 5.002 and is
configured to use it, by default. However:

* the odd "eval" buglet still (randomly?) appears when using Perl 5

* the {{CMD:mif2rtf}} script has {{2:not}} been tested.

If you wish to use Perl 4 instead, you will need
to change the top line of the scripts in the
{{FILE:bin}} directory after installing SDF.

H3: Newsletters

There is now a new style called {{newsletter}}.

The {{FILT:title}} filter now supports a {{toc}}
parameter for specifying a table of contents.
For example:

!block example; pure
!block title; toc=$var{'OPT_TARGET'} eq 'html' ? 2 : 0
Name    Value
Title   My Newsletter
Editor  Me
!endblock
!endblock

This produces a title block for a newsletter and only gives it
a table of contents when the target is [[HTML]].

H3: Pre-Filtering

{{CMD:sdfcvt}}'s -p option prefilters the input file for each argument.
The (optional) parameter is the filter to use. For example:

E:	sdfcvt -ptable mytable.tbl

is equivalent to executing {{CMD:sdfcvt}} on a file which only contains:

E:	!include "mytable.pl"; table

File extensions can be mapped to filters in {{FILE:sdfcvt.ini}}.
For example, {{FILE:sdfcvt.ini}} now contains the following:

!block example
[PreFilters]
Name    Aliases     Module
table   tbl
module  sdm,sde     frmodule
!endblock

As {{tbl}} is mapped to {{table}}, creating nicely formatted
tables is now quite easy. For example:

E:	sdfcvt -p -aformat='15,75,10' mytable.tbl

(The -a option can be used to specify prefilter parameters.)

For a given prefilter, a module can be configured in
{{FILE:sdfcvt.ini}} to be loaded before the filter is applied.
As a result, it's possible to do really clever things via
autoloaded filters. Examples include:

* automatically documenting SDF modules
* converting other formats to SDF on the fly.

For example, the following command will build the reference documentation
for a SDF module in [[HTML]] (real soon now):

E: sdfcvt +sdf2html -p abc.sdm

H2: General Fixes

The {{CMD:sdf2txt}} stuff now works.

H2: HTML Fixes

Empty cells now look better. (This was supposed to be fixed
by the previous release but I had missed a few.)

Paragraphs with multiple anchors are now handled better
(although the odd problem probably remains with this stuff).

If a table of contents is requested and SDF doesn't know
the "right" place for it, it is now prepended (rather
than being dumped).

Title blocks for correspondence look much better now.

H2: HLP Fixes

Absolute path names for libraries now correctly go into
HPJ files. / characters are now also mapped to \ characters.

Title blocks for correspondence look much better now.

H2: Incompatibilities

None.
sdf-2.001/doc/release/2001.html010064400042570001753000000356760672242642100156010ustar00iancmtr00000400000236






SDF 2.001: SDF Release Notes: 2.001




      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      1. 2.001
      

      Enhancements | Fixes | Incompatibilities
      

      

      1.1. Enhancements
      

      The enhancements are:
      


      1.1.1. Level 0 headings
      

      H0, A0 and P0 are now supported as paragraph styles. Level 0 headings are implicitly converted to:
      

       !define DOC_NAME "text of heading"
 !build_title

      

      This feature makes it easier to structure large documents as topics each of which begins with H1. To format a particular topic as a document, sdf's -H option can be used to set the initial heading level to zero like this:
      

             sdf -2html -H0 mytopic.sdf

      

      1.1.2. New command line options
      

      The sdf program has some new command line options: -O, -g and -K.
      

      The -O option specifies an explicit output directory. If the -O option is specified without a parameter, the input file's directory is used. For example, to convert mydir1/mydir2/myfile to HTML and put the output in the same directory as the original file, the command is:
      

             sdf -2html -O mydir1/mydir2/myfile

      

      
Note: The -O option doesn't always work. In particular, HTML topics generation doesn't support it yet.

      

      The -g option prefilters the input files by executing sdfget using the default report (default.sdg). To change the report used, specify the report name as the parameter. If the report name doesn't include an extension, sdg is assumed.
      

      The -K option sets the look of headings. Sensible parameter values are H, A and P. For example, to get the embedded documentation out of a script, make the headings plain, generate a document (rather than a topic) and convert it to HTML, the command line is:
      

             sdf -g -KP -H0 -2html myscript

      

      1.1.3. Table enhancements
      

      The predefined table style names (columns, rows, grid, plain and shade) now have edit-case aliases (i.e. Columns, Rows, Grid, Plain and Shade). If the edit-case versions are used, quotes are not needed, e.g.
      

        !block table; style=Plain
  !endblock

      

      The keepindents parameter has been introduced for the table filter. If set, leading whitespace in cells is kept, e.g.
      

      !block table; keepindents
Directory     Description
sdf           top level directory
   bin        scripts
      bat     batch file wrappers around scripts
   perllib
      sdf     sdf libraries
      Pod     pod libraries
!endblock

      

      The output is:
      

      

      

Directory


Description


      

      

sdf


top level directory


      

      

      bin


scripts


      

      

            bat


batch file wrappers around scripts


      

      

      perllib


 


      

      

            sdf


sdf libraries


      

      

            Pod


pod libraries


      

      


      1.1.4. HTMLDOC support
      

      To convert a document to HTML ready for Michael Sweet's HTMLDOC program, the command is:
      

             sdf -2html -DHTMLDOC ...

      

      Alternatively, sdf can call HTMLDOC itself in order to generate PostScript or PDF. The commands to do this are:
      

             sdf -2ps_html ...
       sdf -2pdf_html ...

      

      
Note: To maintain backwards compatibility, FrameMaker is still the default back-end for generating PostScript and PDF. If you wish to make HTMLDOC the default back-end, edit the FormatMappings sections of the sdf.ini file and change ps to mean ps_html and pdf to mean pdf_html. Once this is done, the following commands will use HTMLDOC rather than FrameMaker:
      

             sdf -2ps ...
       sdf -2pdf ...

      

      

      When sdf invokes HTMLDOC, it sets the appropriate HTMLDOC options by using the following SDF variables: DOC_TITLE (build from DOC_NAME and DOC_TYPE), DOC_TOC, DOC_TWO_SIDES, OPT_PAGE_SIZE, OPT_MARGIN_INNER, OPT_MARGIN_OUTER, OPT_MARGIN_TOP and OPT_MARGIN_BOTTOM. In addition, a new variable called HTMLDOC_OPTS can be used to pass additional options through to the HTMLDOC command line, e.g.
      

             sdf -2pdf_html "-DHTMLDOC_OPTS:--gray --jpeg" ...

      

      To do: add support for AUTHOR, COPYRIGHT and DOCNUMBER.
      

      At the moment, SDF headers and footers are not converted to their HTMLDOC equivalents. To access HTMLDOC's header/footer support, it's currently necessary to use the HTMLDOC_OPTS variable.
      

      1.1.5. Improved LaTeX support
      

      Valerio Aimale's (mailto:valerio@publinet.it) LaTeX driver is now part of the standard distribution. Refer to the file doc/notes/latex.notes for usage details.
      

      1.1.6. HTML formatting enhancements
      

      The following phrase attributes are now supported when generating HTML: color, family, size, bold, italic, underline, bgcolor and changed. A changed phrase or paragraph is shown with the background color given by the HTML_CHANGED_COLOR variable. The default value is teal.
      

      The following paragraph attributes are now supported when generating HTML: align, first, left, right.
      

      See the SDF files within the examples/2001/stylesheets directory for examples of using these attributes.
      

      1.1.7. HTML meta information and stylesheet support
      

      The meta filter can now be used to add META tags to the HEAD of a HTML document. This filter expects a table with columns called Name and Content, e.g.
      

      !block meta
Name|Content
description|Tools for building Java systems
keywords|Java,development tools
!endblock

      

      Stylesheets can be linked or embedded using the links and stylesheet filters respectively. Here's a linked stylesheet:
      

             !block links
       Jump
       test.css
       !endblock

      

      Here's how to embed the same stylesheet:
      

             !include "test.css"; stylesheet

      

      Phrases and paragraphs now support the following attributes:
      

        

      • class - give this phrase or paragraph the nominated HTML CLASS attribute

      • style - format this phrase or paragraph using the nominated style information.
      

      Here's an example of applying a custom style:
      

        [style='background-color: blue;; color: red']
  A styled paragraph.

      

      
Note: SDF uses a single semi-colon to separate attributes, so attributes values with embedded semi-colons need to use ';;' to mean ';'. (The general rule is to use N+1 consecutive semi-colons to get N semi-colons).

      

      1.1.8. Stylesheet-friendly HTML generation
      

      Generated HTML documents are now "stylesheet-friendly" in that:
      

        

      • DIVs are placed around interesting parts of the document

      • parts of the title are implicitly given classes

      • tables are implicitly given classes.
      

      Here are the document sections placed in DIVs:
      

      

      

Document part


DIV name


      

      

title section


title


      

      

table of contents


contents


      

      

main body


main


      

      

header section


header


      

      

footer section


footer


      

      

navigate section


navigate


      

      


      The navigate DIV is nested within header and footer. (This makes it easy to format the navigation section regardless of its location.)
      

      Here's the list of classes placed on parts of the title:
      

      

      

Class


Comments


      

      

doc-title


title of document


      

      

doc-id


id of document


      

      

doc-author


author list


      

      

doc-status


document status


      

      

doc-modified


modification date


      

      


      Tables are implicitly given a class named after the SDF table style. Heading and footing rows within tables are given classes of heading and footing respectively. Here's a set of Cascading Style Sheet (CSS) rules for a colorful table:
      

        TABLE.columns {background-color: yellow}
  TABLE.columns TR.heading {background-color: aqua}
  TABLE.columns STRONG {font-size: 20pt}
  TABLE.columns TD {color: purple}

      

      See the SDF files within the examples/2001/stylesheets directory for more examples of using these features.
      

      1.1.9. Embedded documentation enhancements
      

      A new filter called get has been added.
      

      Support for embedded documentation in IDL has been improved (the IDL now gets pretty-printed in the "Interface" section).
      

      The getdoc and getcode macros now guess the get-rule using the formatting extension.
      

      The sdfget program has been enhanced in several ways:
      

        

      • if specified without a parameter, the get-rule is now guessed from the file extension (see the sdfget documentation for details on how this is done)

      • the new -v option enables verbose mode (which shows the get-rule guessed)

      • a new option (-f) can be used to specify the the filename to use for formatting (which is useful when the text is coming from standard input)

      • a new get-rule called bat is supported for DOS batch files

      • if a report filename doesn't have an extension, sdg is assumed.
      

      The default.sdg report has been enhanced to support new sections called Notes, See_also and Authors.
      

      A new SDG report called all.sdg has been added. This report formats all embedded documentation sections (unlike default.sdg which only extracts selected sections).
      

      The default.sdg and all.sdg reports have been enhanced to support the SDG_BEGIN and SDG_END macros. These macros are empty by default so authors can override these to customise the display of extracted documentation.
      

      1.1.10. Miscellaneous stuff
      

      A new module called homepage has been added to make it easier to build SDF-like home pages. For an example of usage, see the source for SDF's home page (doc/home.sdf).
      

      A Russian locale (ru_ru) has been added thanks to Alexey L. Popov (alpopov@elkamail.ru).
      

      New macros called div and enddiv can be used to put divisions in documents.
      

      If sdf's -p option is specified without a parameter, table prefiltering is assumed.
      

      

      1.2. Fixes
      

      Indented tables now work as expected, i.e. leading whitespace at the beginning of the heading row is now accepted and remaining rows have that amount of whitespace trimmed.
      

      When generating txt output, leading cell whitespace now works as expected. Previously, multiple spaces were converted to a single space.
      

      Attribute values containing ;; no longer have the whitespace around the character sequence trimmed.
      

      Internally, unhandled internal directives no longer produce a warning. (As a result, it's now easier to extend things without "breaking" existing drivers.)
      

      When generating HTML, the HTML_PRE_SECTION is no longer prepended unless a table of contents is generated.
      

      

      1.3. Incompatibilities
      

      When HTML is generated, the default footer no longer contains a line. To get the old behaviour, set the HTML_OLD_FOOTERS variable, e.g.
      

             sdf -2html -DHTML_OLD_FOOTERS ...

      

      The HTML driver no longer uses special embedded comments to work out where to put the table of contents.
      

      The getcli macro no longer searches the include path: it just executes the command.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



braries

    		• 

    

    


    1.1.4.sdf-2.001/doc/user/004075500042570001753000000000000672243775200136625ustar00iancmtr00000400000236sdf-2.001/doc/user/in_parag.sdf010064400042570001753000000007120630655661600161340ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Paragraphs

!block topics
Topic
in_hdg
in_examp
in_lists
in_notes
!endblock
sdf-2.001/doc/user/in_fg.sdf010064400042570001753000000007100633425642000154230ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Figures

!block topics
Topic
in_fgov
in_fggen
in_fgtit
in_fgpos
!endblock
sdf-2.001/doc/user/in_start.sdf010064400042570001753000000007420645310010600161600ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Getting Started

!block topics
Topic
in_intro
in_insta
in_gsex
in_gsgen
in_style
in_title
!endblock
sdf-2.001/doc/user/in_fgpos.html010064400042570001753000000113520672242752500163500ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Positioning a Figure





    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    4.4. Positioning a Figure
    

    

    4.4.1. Horizontal Alignment
    

    The alignment of a figure can be specified using the align attribute of the import macro. The supported values are:
    

    

    

Align


Description


    

    

Center


centered within the region (the default)


    

    

Left


left side of region


    

    

Right


right side of region


    

    

Inner


inner side of region for double sided documents (otherwise Left)


    

    

Outer


outer side of region for double sided documents (otherwise Right)


    

    


    For example:
    

      !import "my_graph"; align=Left

    

    

    4.4.2. Wide Figures
    

    By default, figures are aligned within the main text area. To align a figure within the full text area (i.e. including the side-head), use the wide attribute. For example:
    

      !import "my_graph"; align=Left; wide

    

    

    4.4.3. Figures Within a List
    

    To align a figure with a given list indent, use the listitem attribute. For example:
    

      * The graphs are impressive:
    - savings per year
    !import "my_graph"; listitem=2

    

    

    4.4.4. Vertical Positioning
    

    The vertical position of a figure can be specified via the position attribute. The supported values are:
    

    

    

Position


Description


    

    

Below


below the current paragraph (the default)


    

    

Top


top of the current column/page


    

    

Bottom


bottom of the current column/page


    

    


    For example:
    

       !import "my_logo"; position=Bottom; align=Right

    

    

    4.4.5. Wrapping Text Around a Figure
    

    To wrap text around a figure, set the wrap_text attribute. For example:
    

        !import "my_graph"; wrap_text

    

    
Note: When generating HTML, text can be wrapped around a figure but unfortunately, the rules are quite different:
    

      

    1. The wrap_text attribute has no affect.

    2. Text is implicitly wrapped if the align attribute is set to Left or Right.

    3. The wrapping must be explicitly disabled using the clear macro.
    

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/user/in_sdadv.html010064400042570001753000000106740672242763000163360ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Looks





    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6. SDF Advanced Features
    

    

    6.1. Introduction
    

    This chapter presents information on some advanced SDF features. SDF beginners should skip this chapter and return to it if and when they wish to learn more.
    

    The topics covered are outlined below.
    

    

    

Section


Description


    

    

Modules and Libraries


how to load modules and libraries


    

    

Object Management


how to define and use objects (e.g. references)


    

    

Conditional Text


how to conditionally include or exclude SDF


    

    

Event Processing


how to change the layout and automate tasks using rules


    

    

Custom Formatting


how to change fonts, paper sizes, etc.


    

    

Hypertext


how to build hypertext


    

    

Escaping Symbols


how to include special symbols (e.g. {{)


    

    

Multiple Looks


packaged document-wide presentation styles


    

    


    Modules and Libraries
    

    Object Management
    

    Conditional Text
    

    Event Processing
    

    Custom Formatting
    

    Hypertext
    

    Escaping Symbols
    

    Looks
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/user/in_tbsiz.sdf010064400042570001753000000111140635011350400161530ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Sizing Columns

H2: Dynamic Sizing

SDF supports dynamic column widths for paper documentation, i.e.
if a width is not specified for a column, then the column is
sized based on the text within it and the space available.
As a result, it is rarely necessary to explicitly size columns.

H2: The format Attribute

The {{format}} attribute of the {{FILT:table}} filter is used
to specify column widths for paper documentation. Its value
is either:

* a single number, in which case each digit represents 10% of the
  width available to the table, or

* a comma-separated list of column width specifications.

For example, to specify 3 columns with widths of 20%, 10% and
30% respectively:

E:!block table; format=213
E:Name   Age Address
E:Bill   42  123 Main Road
E:Joe    21  456 Queen Street
E:!endblock

The result is:

!block table; format=213
Name    Age Address
Bill    42  123 Main Road
Joe     21  456 Queen Street
!endblock

Note: The {{format}} parameter has no impact on HTML
generation - all columns in HTML are currently dynamically sized.

H2: Column Width Specifications

Examples of the column width specifications supported are given below.

!block table
Value       Meaning
30pt        an exact size (other supported units are cm, mm, " and in)
30%         a percentage of the size available
30          a percentage of the size available (% is implicit)
10-20       dynamic size between 10% and 20% of the total width
-20         dynamic size between 0% and 20% of the total width
10-         dynamic size between 10% and 100% of the total width
-           dynamic size between 0% and 100% of the total width
3*          3 units of the remaining space
*           same as 1*
!endblock

For example, in the table below, the second column will be
twice the size of the last column.

!block example
!block  table; format="20,2*,10,*"
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock
!endblock

The output is:

!block  table; format="20,2*,10,*"
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock

H2: Default Sizing Rules and Narrow Tables

If a column is not given a size, the following rules are used:

^ The last unspecified column size is implicitly '*' (i.e. the rest),
  unless the {{narrow}} attribute is set, in which case the size
  is implicitly '-' (i.e. as much as needed).

+ The other unknown sizes are implicitly '-'.

For example, the first and third columns in the table below
will be dynamically sized. The first column will take as
much space as required and the last column will expand so
that the table takes the full width of the text area.

!block example
!block  table; format=",30,,10"
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock
!endblock

The output is:

!block  table; format=",30,,10"
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock

However, in the example below, each column will only take
as much space is required, making the table narrower
than it would be otherwise.

!block example
!block  table; narrow
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock
!endblock

The output is:

!block  table; narrow
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock

H2: Equalised Column Widths

If an = character is used in place of a - character for a column
width, then those columns will be equalised in size.
For example, the second and forth columns in the table
below will be made equal in size.

!block example
!block  table; format="20,5=30,10,="
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock
!endblock

The output is:

!block  table; format="20,5=30,10,="
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock
sdf-2.001/doc/user/in_event.html010064400042570001753000000147210672242761300163540ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Event Processing





    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.5. Event Processing
    

    

    6.5.1. The on Macro
    

    The on macro allows you to execute an arbitrary piece of Perl code during document conversion. The syntax of the on macro is:
    

     !on type pattern; [id]; action

    

    where:
    

      

    • type specifies the event type

    • pattern is a Perl regular expression string, anchored at both ends, which specifies which styles (or names) the action is to be executed for

    • id is optionally used to name an event for later disabling via the off macro

    • action is the block of Perl code to execute.
    

    For example, the following statement makes every heading a hypertext target named itself:
    

      !on paragraph 'H\d';; $attr{'id'} = $text

    

    

    6.5.2. Event Types
    

    The types supported and the symbols available in the respective actions include:
    

    

    

Type


Symbols


    

    

paragraph


$style, $text, %attr


    

    

phrase


$style, $text, %attr


    

    

macro


$name, $args


    

    

filter


$name, $params


    

    

table


$style, %param


    

    


    

    6.5.3. Event Patterns
    

    Some example event patterns are given below.
    

    

    

Pattern


Comments


    

    

'XYZ'


matches a thing called XYZ


    

    

'AB|CD|E'


matches things named AB, CD or E


    

    

'H1'


for paragraphs, matches a level 1 normal heading


    

    

'H[1-4]'


for paragraphs, matches normal headings at levels 1 to 4


    

    

'[HAP]\d'


for paragraphs, matches all headings


    

    


    If the pattern is an empty string, the action is executed for all entities of that type.
    

    If multiple actions are registered for a given type, actions are executed in "last in, first out" order.
    

    

    6.5.4. The off Macro
    

    The off macro is used to cancel an event. The syntax is:
    

     !off type id

    

    For example:
    

      !on paragraph 'H\d'; XYZ; $attr{'id'} = $text
  # lots of SDF
  !off paragraph XYZ

    

    If two events are given the same name, the most-recently-named event will be cancelled. i.e. nested event cancelling works as expected.
    

    

    6.5.5. Examples
    

    6.5.5.1. Generating Hypertext Targets
    

    To make all level 1 and 2 headings hypertext targets:
    

      !on paragraph '[HAP][12]';; $attr{"id"} = $text

    

    6.5.5.2. Generating Index Entries
    

    To make index entries for all commands (CMD character tags):
    

      !on phrase 'CMD';; $attr{"index"} = $text

    

    6.5.5.3. Adjusting Heading Levels
    

    To move normal headings down one level:
    

      !on paragraph 'H\d';; $style =~ tr/1234/2345/

    

    6.5.5.4. Changing Spelling
    

    To convert selected words to North American spelling:
    

      !on paragraph '';; $text =~ s/colour/color/ig; \
                     $text =~ s/ise\b/ize/g

    

    This approach uses Perl's substitute operator on the text in each paragraph:
    

      

    • the 'i' switch means case insensitive

    • the 'g' switch means global. i.e. all occurances in each paragraph

    • the '\b' symbol matches a word boundary.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



und-color: teal}
.changed {background-color: tesdf-2.001/doc/user/in_fgtit.sdf010064400042570001753000000025100635011350400161350ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Adding Figure Titles

H2: Adding a Title to a Figure

To add a title, use the {{title}}
attribute of the {{MAC:import}} macro.
For example:

E:  !import "growth"; title="Predicted Growth"

H2: Adding a Title to a Psuedo Figure

Occasionally, it is useful to label a source
code example or ASCII graphic with a title.
To do this, use the FT (Figure Title) paragraph style.
For example:

E:   FT: Source code for main.c
E:   !include "main.c"; example; lang='C'

H2: Generating a List of Figures

A list of figures can be generated from the figure titles.
To do this, set the {{VAR:DOC_LOF}} variable. For example:

E:# Build the title
E:!define DOC_NAME "World Peace in 60 Days"
E:!define DOC_LOF
E:!build_title

This will generate a list of figures after the table of contents.

H2: Changing the List of Figures Title

The default title for the list of figures is "List of Figures".
To change this, set the DOC_LOF_TITLE.
For example:

E:!define DOC_LOF_TITLE "Figures"
sdf-2.001/doc/user/in_hyper.html010064400042570001753000000076660672242762200163740ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Hypertext





    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.7. Hypertext
    

    

    6.7.1. Attributes
    

    Hypertext can be specified using the id and jump phrase attributes. The value of id is a text string which can include letters, digits, underscores and spaces. The value of jump is a World Wide Web (WWW) Uniform Resource Locator (URL).
    

    Commonly used jump formats are summarised below.
    

    

    

Format


Description


    

    

#xyz


jump to xyz within this document


    

    

abc


jump to document abc


    

    

abc#xyz


jump to xyz within document abc


    

    


    For example:
    

    This is the only software you will ever need.
See {{CMD[jump="#smartcmd"]smartcmd}} for details.

H2[id="smartcmd"] smartcmd - Do What I Want Utility

{{CMD:smartcmd}} is the best program ever written.
It detects what you want to do next by ...

    

    If you want to specify a phrase as a hypertext target within "normal" paragraph text, use the N (for Normal) phrase style. For example:
    

       The {{N[id='_option_o']-o option}} specifies ...

    

    
Note: Hypertext jumps are ignored when paper documents are being generated.

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/user/in_libr.html010064400042570001753000000106110672242760100161520ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Modules and Libraries





    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    6.2. Modules and Libraries
    

    

    6.2.1. Modules
    

    SDF can be extended by using modules. A module is a normal SDF file which typically contains reusable entities like macros, filters and styles. Modules are loaded by the use macro. For example:
    

       !use "delphi"

    

    By convention, modules are given the sdm extension. The use macro adds this extension if none is provided. Modules can also be loaded by using sdf's -u option.
    

    

    6.2.2. Libraries
    

    A collection of related modules can be placed into a library which is simply a subdirectory under the sdf/home directory on Perl's library path. Libraries can be loaded by the inherit macro which essentially does the following:
    

      

    1. appends the matching directory onto the include path

    2. loads the matching main module.
    

    For example:
    

       !inherit "images"

    

      

    1. appends sdf/home/images onto the include path

    2. loads the sdf/home/images/images.sdm module.
    

    

    6.2.3. The Configuration Library
    

    After loading the standard library (stdlib), SDF loads the configuration library, if any. This is typically specified via the OPT_CONFIG variable being initialised on the top line of the file via the init macro. It can also be set via sdf's -c option.
    

    While sdf only supports a single configuration library, additonal libraries can be loaded via the inherit macro. Furthermore, a library can inherit things from other libraries, making it easy to create new ones.
    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/user/in_event.sdf010064400042570001753000000061110661461342600161550ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Event Processing

H2: The on Macro

The {{MAC:on}} macro allows you to execute an arbitrary piece of
[[Perl]] code during document conversion.
The syntax of the {{MAC:on}} macro is:

E: !on {{type}} {{pattern}}; [{{id}}]; {{action}}

:where:

* {{type}} specifies the event type
* {{pattern}} is a [[Perl]] regular expression string, anchored at both ends,
  which specifies which styles (or names) the action is to be executed for
* {{id}} is optionally used to name an event for later disabling via
  the {{MAC:off}} macro
* {{action}} is the block of [[Perl]] code to execute.

For example, the following statement makes every heading a hypertext
target named itself:

E:  !on paragraph 'H\d';; $attr{'id'} = $text

H2: Event Types

The types supported and the symbols available in the respective actions
include:

!block table
Type        Symbols
paragraph   $style, $text, %attr
phrase      $style, $text, %attr
macro       $name, $args
filter      $name, $params
table       $style, %param
!endblock

H2: Event Patterns

Some example event patterns are given below.

!block table
Pattern     Comments
'XYZ'       matches a thing called XYZ
'AB|CD|E'   matches things named AB, CD or E
'H1'        for paragraphs, matches a level 1 normal heading
'H[1-4]'    for paragraphs, matches normal headings at levels 1 to 4
'[HAP]\d'   for paragraphs, matches all headings
!endblock

If the pattern is an empty string, the action is executed for all
entities of that type.

If multiple actions are registered for a given type, actions are
executed in "last in, first out" order.

H2: The off Macro

The {{off}} macro is used to cancel an event.
The syntax is:

E: !off {{type}} {{id}}

For example:

E:  !on paragraph 'H\d'; XYZ; $attr{'id'} = $text
E:  # lots of SDF
E:  !off paragraph XYZ

If two events are given the same name, the most-recently-named event
will be cancelled. i.e. nested event cancelling works as expected.

H2: Examples

H3: Generating Hypertext Targets

To make all level 1 and 2 headings hypertext targets:

E:  !on paragraph '[HAP][12]';; $attr{"id"} = $text

H3: Generating Index Entries

To make index entries for all commands (CMD character tags):

E:  !on phrase 'CMD';; $attr{"index"} = $text

H3: Adjusting Heading Levels

To move normal headings down one level:

E:  !on paragraph 'H\d';; $style =~ tr/1234/2345/

H3: Changing Spelling

To convert selected words to North American spelling:

E:  !on paragraph '';; $text =~ s/colour/color/ig; \
E:                     $text =~ s/ise\b/ize/g

This approach uses Perl's substitute operator on the text
in each paragraph:

* the 'i' switch means case insensitive
* the 'g' switch means global. i.e. all occurances in each paragraph
* the '\b' symbol matches a word boundary.

!end_topic
sdf-2.001/doc/user/in_notes.sdf010064400042570001753000000031320635011350400161510ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Notes

H2: Short Notes

The paragraph tag for adding a single paragraph note is {{Note}}.
For example:

E:  Note: Life is too short to waste time being unhappy.

The result is:

Note: Life is too short to waste time being unhappy.

H2: Changing the Label

You can change the label for a note by using the {{PATTR:label}}
paragraph attribute. For example:

E:  Note[label='Important: '] Life is too short to drink bad wine.

The result is:

Note[label='Important: '] Life is too short to drink bad wine.

H2: Long Notes

If the note requires more than one paragraph, use the {{FILT:note}}
filter. For example:

E:  !block note
E:  Life is too short to:
E:
E:  * waste time being unhappy
E:  * worry about yesterday.
E:  !endblock

The result is:

!block note
Life is too short to:

* waste time being unhappy
* worry about yesterday.
!endblock

H2: The NB/NE Tags

Before the {{FILT:note}} filter existed, long notes were created
by using the NB (Note Begin) and NE (Note End) tags. For example:

E:  NB: Life is too short to:
E:
E:  * waste time being unhappy
E:  * worry about yesterday.
E:
E:  NE:

These paragraph styles are still supported, although the {{FILT:note}}
filter is now the recommended way of specifying long notes.

!end_topic
sdf-2.001/doc/user/in_examp.sdf010064400042570001753000000067050661461222200161500ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Example Paragraphs

H2: Simple Examples

Example paragraphs are displayed in a fixed-width font (e.g. Courier).
Unlike most other paragraphs, spaces and tabs immediately
after the paragraph tag are not ignored in example paragraphs.
The tags used are:

* E - fixed-width text
* V - verbatim, fixed-width text (embedded symbols are ignored).

For example:

>E:# {{Greeting}} outputs a friendly greeting.
>E:sub Greeting {
>E:    print "Hello world\n";
>E:}

The result is:

E:# {{Greeting}} outputs a friendly greeting.
E:sub Greeting {
E:    print "Hello world\n";
E:}

H2: Shorthand Notation

As verbatim, fixed-width text is very common in software documentation,
">" is provided as a shorthand for "V:". For example:

>># {{Greeting}} outputs a friendly greeting.
>>sub Greeting {
>>    print "Hello world\n";
>>}

The result is:

># {{Greeting}} outputs a friendly greeting.
>sub Greeting {
>    print "Hello world\n";
>}

H2: Large Examples

Large examples are usually defined using the {{example}} or {{verbatim}}
filters like this:

!block verbatim
!block example
# {{Greeting}} outputs a friendly greeting.
sub Greeting {
    print "Hello world\n";
}
!endblock
!endblock

H2: Wide Examples

If an example block has unwanted line breaks, the {{wide}}
parameter should be specified. Wide examples use a wider text area
(and a smaller font, if necessary) so that 80 characters can
fit onto each line. For example:

!block verbatim; wide
!block example; wide
sub SaveTheWorld {                  # This routine provides world peace
    local($param1, param2) = @_;    # Input parameters

    # Do the work
    # ...
}
!endblock
!endblock

The result is:

!block example; wide
sub SaveTheWorld {                  # This routine provides world peace
    local($param1, param2) = @_;    # Input parameters

    # Do the work
    # ...
}
!endblock

H2: Formatting Source Code

Blocks of source code can be nicely formatted via the {{lang}}
parameter to the {{FILT:example}} filter. For example:

!block verbatim
!block example; lang='Perl'
sub hello {
    local($planet) = @_;

    # Output a nice message
    print "hello $planet!\n";
}
!endblock
!endblock

The result is:

!block example; lang='Perl'
sub hello {
    local($planet) = @_;

    # Output a nice message
    print "hello $planet!\n";
}
!endblock

For convenience, if a programming language is used as a filter
(and a filter of that name doesn't exist), SDF implicitly calls
the example filter for you with the relevant lang parameter.

There is built-in support for numerous languages including
[[Perl]], C, C++, [[Java]], [[Delphi]], CORBA IDL and shell.
New language definitions can be easily added
({{CMD:vgrind}} definitions are used).

H2: File Pretty Printing

Pretty printing of source code files is directly supported by
{{CMD:sdf}}'s -P option.
For example:

E:  sdf -2ps -Psh myscript
E:  sdf -2ps -P myapp.c
E:  sdf -2ps -P -n5 mylib.pl

The language to use can be specified as a parameter.
The default language is derived from the extension of the file.
The -n option adds line numbers at the frequency given.
The default frequency is 1. i.e. every line.

!end_topic
sdf-2.001/doc/user/in_tbss.sdf010064400042570001753000000066700635673245200160250ustar00iancmtr00000400000236H1: Spreadsheet calculations

H2: Overview

Spreadsheet style calculations have been introduced into SDF using the
standard {{E<2[> E<2]>}} syntax with a prefix of {{+}} (or {{=}}) indicating
that the expression is to be evaluated by the calculation routines.

This extension has been loosely modelled on [[Microsoft]] {{Excel}}[[r]]
in terms of the initial functions supported and the syntax used.

The spreadsheet expression evaluator and the documentation below
was written by Tim Hudson ({{EMAIL:tjh@cryptsoft.com}}).

H2: Cells and Cellids

Each {{cell}} in a table has an {{cellid}} which is made up of a
single uppercase letter indicating the column index and a number
indicating the row index (counting from 1 and excluding the
heading rows). The upper left {{cell}} is hence {{A1}}.

An example grid indicating {{cellid}}s:

!block table; narrow
Title1:Title2:Title3:Title4:Title5
A1:B1:C1:D1:E1
A2:B2:C2:D2:E2
A3:B3:C3:D3:E3
...:...:...:...:...
A100:B100:C100:D100:E100
!endblock

A range of {{cellid}}s is specified using the syntax {{:cellid1:cellid2}}.
For example: {{:A1:C1}} is exactly the same as {{A1,B1,C1}}

H2: Spreadsheet Expressions

An expression consists of a combination of standard Perl operators
and spreadsheet functions and {{cellid}}s or {{cellid}} ranges.

Standard Perl operators include:

* + - * /

H2: Spreadsheet Functions

Spreadsheet functions use the syntax {{FUNCTION(ARG1,ARG2,...ARGN)}}.

The following functions are supported:

* {{AVERAGE}} - the average - SUM(ARGS)/COUNT(ARGS)
* {{SUM}} - the sum of the args - same as ARG1+ARG2+...+ARGN
* {{MIN}} - the minumum argument value 
* {{MAX}} - the maximum argument value
* {{COUNT}} - the number of arguments
* {{PRODUCT}} - the product of the args - same as ARG1*ARGN*...*ARGN
* {{ROWSUM}} - the {{SUM}} of all the cells in the row to the left of 
               the current cell
* {{ROWPROD}} - the {{PRODUCT}} of all the cells in the row to the 
                left of the current cell
* {{COLSUM}} - the {{SUM}} of all the cells in the column above the 
               current cell
* {{COLPROD}} - the {{PRODUCT}} of all the cells in the column above the 
                current cell

H2: An Example

A simple example is shown below:

!block verbatim
!block table; style="grid"
Count         Price        Total
10            5            [[=A1*B1]]
15            5.23         [[=ROWPROD]]
[[=COLSUM]]   [[=B1+B2]]   [[=COLSUM]]
!endblock
!endblock

This generates the result below. (Ok, summing two prices is
meaningless, but it illustrates the syntax.)

!block table; style="grid"
Count         Price        Total
10            5            [[=A1*B1]]
15            5.23         [[=ROWPROD]]
[[=COLSUM]]   [[=B1+B2]]   [[=COLSUM]]
!endblock

H2: Accessing Spreadsheet Values in Paragraph Text

Values are available until the next table is processed so
you can refer to data inside {{normal}} paragraphs after 
the table like this E<2[>=A1E<2]> (which evaluates to [[=A1]]).

H2: Recursive Expression Evaluation

A spreadsheet expression will recursively evaluate any expressions
contained in {{cells}} that are used in an expression. In the example
above, the expression in {{cell}} {{C3}} depends on the results of the
expression in {{cell}} {{C1}} and {{C2}}.

H2: Disabling Calculations

Calculation support for a table can be disabled by adding in 
an attribute of {{nocalcs}}. (Without this, the pointers required to table
data that are needed when doing spreadsheet calculations occur for each
table cell.)
sdf-2.001/doc/user/in_hdg.html010064400042570001753000000114520672242750000157660ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Headings





    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    3.1. Headings
    

    

    3.1.1. Chapter Headings
    

    Headings are specified using the tags H1 .. H6:
    

      

    • H1 is a chapter heading

    • H2 .. H6 are sub headings
    

    The actual presentation of H-style headings (e.g. numbered or unnumbered) is decided by the target format and document style.
    

    

    3.1.2. Other Headings
    

    The following heading tags are also supported:
    

      

    • A1 .. A6 - headings in Appendices

    • P1 .. P6 - headings in plain sections (e.g. Glossary)
    

    P-style headings are always unnumbered so are commonly used in memos.
    

    In normal documents, it is often unnecessary to use A-style or P-style tags. The preferred approach is to:
    

      

    • store each section in a file using H-style headings

    • convert the heading style using the appendix or plain filter as the file is being imported.
    

    For example:
    

      !include "budget.sdf"; appendix

    

    Using this approach, sections can easily be reused in different ways in different documents.
    

    

    3.1.3. Generating a Table of Contents
    

    A table of contents can be generated from the heading paragraphs. All types of heading tags (i.e. H, A and P) are included. The depth of the table of contents is specified by the DOC_TOC variable. For example, to generate a table of contents including headings up to and including level 4:
    

       doccvt -o -DDOC_TOC=4 mydoc.sdf

    

    
Note: For normal documents, the build_title macro defaults this variable to 3.

    

    Individual headings can be excluded from the table of contents by specifying the notoc attribute. For example:
    

       H3[notoc] Yet Another Heading

    

    See Attributes for further details on attribute syntax.
    

    

    3.1.4. Controlling Page Breaks
    

    Generally speaking, page breaks are controlled by rules associated with heading tags. For example:
    

      

    • for documents, memos and faxes, each level 1 heading starts a new page

    • for manuals, each level 1 heading starts a new chapter and each level 2 heading typically starts a new page.
    

    The top paragraph attribute can be used to position a paragraph at the top of the next page. For example:
    

      H3[top] Abc Module

    

    Page breaks can also be explicitly specified using the PB tag. For example:
    

      text on one page.
  PB:
  H3: Another Section

    

    
Note: SDF is designed to be a logical markup language. While it is sometimes necessary to explicitly specify page breaks in order to get the layout you want, doing so can reduce the portability of your document to different styles, page sizes and target formats.

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



 as the file is being imported.

    For example:
    

      !include "budget.sdf"; appendix

    

    Using this approach, sections can easily be reused in different ways in different documents.
    
sdf-2.001/doc/user/in_gsgen.sdf010064400042570001753000000051000645310006400161220ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Generating outputs

H2: Overview

The {{CMD:sdf}} command is used to convert SDF to other formats.
The general syntax is:

E:   sdf [options] file ...

If an extension is not given (and a file is not found with that name),
an extension of {{sdf}} is assumed.

H2: Generating HTML

To convert {{FILE:mydoc.sdf}} to HTML, the command is:

E:   sdf -2html mydoc

This creates a file called {{FILE:mydoc.html}}.

H2: Generating a set of HTML topics

To convert {{FILE:mydoc.sdf}} to a set of HTML topics, the command is:

E:   sdf -2topics mydoc

This creates the following files:

* {{mydoc.html}} - the table of contents
* {{mydoc_1.html}} - the first topic
* {{mydoc_2.html}} - the second topic.

H2: Generating PostScript on Unix

To convert {{FILE:mydoc.sdf}} to PostScript on Unix, the command is:

E:   sdf -2ps mydoc

This creates a file called {{FILE:mydoc.ps}} by:

^ Generating a MIF (Maker Interchange Format) file called {{mydoc.out}}.
+ Using the {{fmbatch}} program to convert this file to {{mydoc.out.ps}}.
+ Renaming {{mydoc.out.ps}} to {{mydoc.ps}}.
+ Deleting {{mydoc.out}}.

H2: Generating PostScript on Windows

To convert {{FILE:mydoc.sdf}} to PostScript on Windows, the command is:

E:   sdf -2mif mydoc

This creates a file called {{FILE:mydoc.mif}} which can be
opened in FrameMaker and printed to a PostScript file.

H2: Generating PDF

To generate a PDF file, the steps are:

^ Generate a PostScript document (see above)
+ Open the PostScript document using {{Adobe Distiller}}.
+ Generate the PDF file.

Note: The PostScript document generated by SDF includes the
information needed by the PDF distiller to generate a table
of contents.

H2: Generating plain text

To convert {{FILE:mydoc.sdf}} to plain text, the command is:

E:   sdf -2txt mydoc

This creates a file called {{FILE:mydoc.txt}}.

H2: Generating Windows help

To convert {{FILE:mydoc.sdf}} to Windows help, the command is:

E:   sdf -2hlp mydoc

This creates the following files:

* {{mydoc.hpj}} - a help project file
* {{mydoc.rtf}} - an RTF document with embedded help codes

These need to be compiled using a help compiler (e.g. hcp.exe).
For example:

E:   hcp mydoc

This creates a file called {{mydoc.hlp}} (provided no errors are
encountered).
sdf-2.001/doc/user/in_symb.sdf010064400042570001753000000072040645310205600160030ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Escaping Symbols

H2: Special Characters at the Start of a Line

To escape a special character at the start of a line,
precede it with a backslash character (\).

H2: Tag Delimiters

Like special characters, any special pattern at the start of a line
can be escaped by preceding it with a backslash character (\).

Consider the following example:

E:   Important:

This paragraph has a tag called {{Important}} and has no text.
{{CMD:sdf}} will warn you if it finds an unknown tag so most
unintentional errors like this are detected. You can escape the
pattern like this:

E:   \Important:

Other workarounds are:

E:   :Important:
E:   N:Important:

!if $var{'OPT_TARGET'} ne 'hlp'

H2: Special Symbols

[[SDF]] uses a number of special symbols inside paragraphs:

* A-ZE and > - delimit {{concise}} phrases
* E<2{> and E<2}> - delimit {{verbose}} phrases
* E<2[> and E<2]> - delimit expressions (e.g. variables).

If you need to include one of these symbols in a paragraph,
use the appropriate escape as shown below.

!block verbatim
    Symbol      Escape
    <           E
    >           E
    {{          E<2{>
    }}          E<2}>
    [[          E<2[>
    ]]          E<2]>
!endblock

Note the following rules:

^ It isn't necessary to escape any symbols within:
  - paragraphs tagged with the V style or > tag
  - paragraphs given the verbatim attribute
  - paragraphs within a verbatim block

+ It is only necessary to escape a < when it appears after
  a capital letter.

+ It is only necessary to escape a > inside a concise phrase.
  In particular, > is implicitly escaped within a verbose phrase.

!endif

H2: Phrase Parsing Rules

For paragraphs which do not have the {{verbatim}} attribute set,
the parsing rules for the paragraph text are:

^ Expressions embedded in E<2[> and E<2]> are recursively expanded
+ Verbose phrases embedded in E<2{> and E<2}> are recursively expanded
  to concise phrases with a V tag.
+ Concise phrases are parsed.

#Note: These rules may be changed before the production release
#so that only a single left to right parse of the paragraph text is done.
#However, if this happens, I'll keep the semantics as close to the above as
#possible.

H2: Multi-line Macros

\!-style macros can be continued onto the next line by ending the
line with a backslash character (\). To escape this backslash,
use another one. If N backslash characters are found
at the end of a line where N is greater than 2, then that
line is terminated by N-1 backslash characters and the macro
is continued onto the next line.

H2: Embedded Expressions

As expressions embedded within text are terminated by the ]\] symbol,
expressions cannot contain this character sequence. If you need this sequence
within an expression, there is usually a simple workaround you can
use. For example:

^ use a space character (i.e. $a[$b[1]] becomes $a[$b[1] ])
+ use string concatentation (i.e. "]]" becomes "]"."]").

H2: Semi-Colons Within Attributes

If you need to include a real semi-colon within an attribute or parameter,
use two semi-colons. In general, if you need to include a sequence of
N semi-colons in an attribute expression, use N+1 semi-colons.
For example:

V:To install {{P[index="myApp;;install:myApp"]myApp}}, ...

In this case, the value of {{index}} is {{E:myApp;install:myApp}}.


!end_topic
 in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Escaping Symbols

H2: Special Characters at the Start of a Line

To escape a special character at the start of a line,
precede it sdf-2.001/doc/user/in_fgpos.sdf010064400042570001753000000042650635011350400161470ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Positioning a Figure

H2: Horizontal Alignment

The alignment of a figure can be specified using the {{align}}
attribute of the {{MAC:import}} macro.
The supported values are:

!block table
Align   Description
Center  centered within the region (the default)
Left    left side of region
Right   right side of region
Inner   inner side of region for double sided documents (otherwise Left)
Outer   outer side of region for double sided documents (otherwise Right)
!endblock

For example:

E:  !import "my_graph"; align=Left

H2: Wide Figures

By default, figures are aligned within the main text area.
To align a figure within the full text area (i.e. including the side-head),
use the {{wide}} attribute.
For example:

E:  !import "my_graph"; align=Left; wide

H2: Figures Within a List

To align a figure with a given list indent, use the {{listitem}} attribute.
For example:

E:  * The graphs are impressive:
E:    - savings per year
E:    !import "my_graph"; listitem=2

H2: Vertical Positioning

The vertical position of a figure can be specified via the {{position}}
attribute. The supported values are:

!block table
Position    Description
Below       below the current paragraph (the default)
Top         top of the current column/page
Bottom      bottom of the current column/page
!endblock

For example:

E:   !import "my_logo"; position=Bottom; align=Right

H2: Wrapping Text Around a Figure

To wrap text around a figure, set the {{wrap_text}} attribute.
For example:

E:    !import "my_graph"; wrap_text

!block note
When generating HTML, text can be wrapped around a figure but unfortunately,
the rules are quite different:

^ The wrap_text attribute has no affect.
+ Text is implicitly wrapped if the {{align}} attribute is set
  to Left or Right.
+ The wrapping must be explicitly disabled using the {{MAC:clear}} macro.
!endblock
sdf-2.001/doc/user/in_cond.sdf010064400042570001753000000022220647527327600157700ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Conditional Text

Blocks of text can be conditionally included or excluded using
the following macros:

E:   !if condition
E:   !elsif condition
E:   !else
E:   !endif

These macros allow you to tune the output for different audiences.
For example, you may wish to only include email directions
if [[HTML]] is being generated:

!block example; pure
!if OPT_PP_HTML
Click {{[jump="mailto:joe"] here}} to send me email.
!endif
!endblock

NB:
^ {{elseif}} can be used instead of {{MAC:elsif}} if you prefer.

+ {{condition}} is an {{SDF expression}} where
  unknown variables do not give errors

+ Conditional text blocks must be fully defined within a given file.
  This prevents an {{MAC:if}} macro within an included file excluding
  text in the file doing the including.
NE:

!end_topic
sdf-2.001/doc/user/in_ovatt.html010064400042570001753000000065140672242747100163730ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Attributes





    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    2.7. Attributes
    

    

    2.7.1. Introduction
    

    Attributes can be used to specify custom formatting, hypertext targets and jumps, indexing information, etc. For example:
    

      Note[label='Important: ';size="16pt"]
  Life is too short to drink bad wine.

    

    The result is:
    

    
Important: Life is too short to drink bad wine.

    

    

    2.7.2. Syntax
    

    Paragraphs and phrases can be given attributes via the syntax below:
    

      style"["attributes"]" text

    

    where the syntax of attributes is:
    

      name1["="expression1]";" name2["="expression2] ...

    

    If an attribute name is given without a value, the default value is 1. Like style names, attribute names are:
    

      

    • sequences of letters, digits and "_"

    • case-sensitive.
    

    

    2.7.3. Commonly used attributes
    

    Some commonly used attributes are given below.
    

    

    

Name


Purpose


    

    

Paragraphs:


 


    

    

label


prefix label (e.g. Note:)


    

    

notoc


take this heading out of the table of contents


    

    

Phrases:


 


    

    

id


hypertext target tag


    

    

jump


URL (Uniform Resource Locator) to jump to


    

    


    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/user/in_ovexp.html010064400042570001753000000067520672242747400164060ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Expressions





    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    2.8. Expressions
    

    

    2.8.1. Introduction
    

    Expressions are used in several places within SDF including:
    

      

    • attribute values

    • macro argument values

    • filter parameter values

    • evaluation within paragraph text.
    

    The value of an expression can be placed into a paragraph by delimiting it with the special symbols [[ and ]]. For example:
    

       The current file is [[DOC_FILE]].

    

    

    2.8.2. Types of expressions
    

    An expression is either:
    

      

    • an SDF variable name (e.g. DOC_AUTHOR)

    • a Perl expression.
    

    If an expression is a single word, it is the value of a variable. Otherwise, it is evaluated as a Perl expression. A Perl expression is typically one of the following:
    

      

    • a numeric literal (e.g. 213)

    • a string literal (e.g. "User Guide")

    • a subroutine call (e.g. length("User Guide")).
    

    

    2.8.3. Accessing variables within Perl expressions
    

    Within a Perl expression, SDF variables are available via the var associative array. The syntax used by Perl for accessing a value within an associative array is:
    

      "$" array_name "{" string_index "}"

    

    Some examples are:
    

      

    1. get the length of the DOC_AUTHOR variable:
    

          length($var{'DOC_AUTHOR'})

    

      

    1. concatenate the document name and type:
    

          "$var{'DOC_NAME'} $var{'DOC_TYPE'}"

    

    

    

    

    Contents | Parent Topic | Previous Topic | Next Topic 
    Home | Catalog
    

    

    



sdf-2.001/doc/user/in_intro.sdf010064400042570001753000000063110647021524400161650ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Introducing SDF

H2: What is SDF?

SDF (Simple Document Format) is a freely available document development
system which generates high quality outputs in a variety of formats
from a single source. The output formats supported include
[[PostScript]][[tm]], [[HTML]], POD, plain text, man pages, LaTeX,
SGML, [[Windows]][[tm]] help, MIF and RTF.
If the idea of specifying documents in a logical manner via a
simple markup language sounds appealing, SDF may be useful to you.

SDF documents are simple to create and maintain, minimising the time
spent on documentation. In particular, SDF directly supports the
creation and maintenance of large, on-line documentation systems
(including intranets) via centralised hypertext management and
rule-based hypertext generation.

H2: What is SDF useful for?

As well as normal documents, SDF is useful for:

* user manuals (paper-based and online)
* online document catalogs
* Perl module documentation
* Delphi[[tm]] component documentation
* source code listings (pretty printing most languages).

SDF is also good for literate programming, i.e. documentation can
be embedded in the comments of most programming languages and can be
selectively extracted. The embedded documentation can be in any
markup language you like, although there are advantages to using
SDF's markup language.

H2: Requirements

SDF has been completely developed in [[Perl]], a popular and highly
portable scripting language. Perl 5.004 or later is recommended,
although SDF may run on earlier versions of Perl 5.

To generate PostScript, SDF requires one of the following:

* the freely available {{pod2ps}} program
* the freely available {{PRD:SGML-Tools}} and {{LaTeX}} packages
* FrameMaker 5.x or later
* another word processor which can import RTF.

Earlier versions of FrameMaker will generally work, but I don't
explicitly support them.

To generate Windows help, a help compiler (e.g. hcp.exe) is required.

H2: SDF on the World Wide Web

The [[SDF]] home page URL is {{URL:[[SDF_WWW]]}}.
From the home page, you can:

* download the latest software
* browse the {{[jump=$var{'SDF_WWW'}."/faq.html"] FAQ}}
* report defects
* suggest enhancements.

H2: Fetching SDF

SDF is available using anonymous ftp. The URL of the base directory is
{{URL:ftp://ftp.mincom.com/pub/mtr/sdf}}. The latest release is available
in a variety of formats.

H2: Mailing lists

The following mailing lists are available:

* {{EMAIL:sdf-users@mincom.com}} - for general questions
* {{EMAIL:sdf-bugs@mincom.com}} - for reporting bugs and fixes.

To subscribe to these lists, send email to
{{EMAIL:sdf-users-request@mincom.com}} and/or
{{EMAIL:sdf-bugs-request@mincom.com}} for instructions on
using {{factotum}}, the majordomo variant that manages these lists.
In short, send email to {{EMAIL:factotum@mincom.com}} with a
message body of {{subscribe sdf-users}} or {{subscribe sdf-bugs}}.
sdf-2.001/doc/user/ug_sdf.html010064400042570001753000000073130672242763200160140ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide





    

    

    Previous Topic | Next Topic 
    Home | Catalog
    

    

    

    

    

    SDF User Guide
    

    MTR-SDF-0002.001 (Final)
    

    Ian Clatworthy
    

    25 May 1999
    

    

    

    

    

    Table of Contents
    


    

    

    

    Previous Topic | Next Topic 
    Home | Catalog
    

    

    



ml">2.5. Variables

    
2.6. Filters

    
2.7. Attributes

    
2.8. Expressions

    
3. Paragraphs
      
3.1. Headings

      
3.2. Example Parsdf-2.001/doc/user/ug_sdf.sdf010064400042570001753000000024310645310270400156070ustar00iancmtr00000400000236!init OPT_LOOK='infomap'; OPT_STYLE='manual'
# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

# TO DO:
# * add "Special Symbols" to "Language overview"
# * add verbatim stuff to "Example Paragraphs"
# * add enum lists to "Lists"
# * add "Automatic Figure Conversion" to "Figures"
# * add "target via drivers" stuff to "Generating Outputs"?

# Load the configuration
!define SDF_ROOT "../"
!inherit "sdf"

# Define variables
!define DOC_NAME    "SDF"
!define DOC_TYPE    "User Guide"
!define DOC_AUTHOR  "Ian Clatworthy"
!define DOC_TOC     2
!define DOC_IX

# Build the title page
!build_title

# When we're creating help, make the level 2 headings the topics
!if $var{'OPT_TARGET'} eq 'hlp'
!on paragraph '[HAP]2';; $attr{'top'} = 1
!endif

# Include the document components
!include "ugasdf.sdf"; about
!include "in_start.sdf"
!include "in_overv.sdf"
!include "in_parag.sdf"
!include "in_fg.sdf"
!include "in_tb.sdf"
!include "in_sdadv.sdf"
!include "credits.sdf"; appendix
sdf-2.001/doc/user/in_custf.sdf010064400042570001753000000065360635672676200162060ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Custom Formatting

H2: Overview

One of the nice things about [[SDF]] is that system administrators
can control the formatting of documents via templates.
This has two major advantages:

^ document authors can focus on content
+ by default, documents have a consistent format.

However, there are occasions when authors need to override the
default formatting conventions. Custom formatting is supported
for documents, paragraphs and phrases.

H2: Custom Document Formatting

Document formatting can be controlled by setting variables.
The commonly used ones are given below.

!block table
Name                Type        Purpose
DOC_TOC             integer     table of contents level
DOC_LOF             boolean     build a list of figures
DOC_LOT             boolean     build a list of tables
DOC_IX              boolean     build an index
DOC_TWO_SIDES       boolean     build a two-sided document
!endblock

For example, to create a two-sided document,
add this line to your document:

E:  !define DOC_TWO_SIDES

H2: Custom Paragraph Formatting

Paragraph formatting can be controlled by setting attributes.
The commonly used ones are given below.

!block table
Name            Purpose
label           prefix label (e.g. Note:)
top             either Page (the default), Column, LPage or RPage
left            left margin indent (in points)
first           first line indent (in points)
right           right margin indent (in points)
justify         either Full, Left, Right or Center
!endblock

For example, to start a paragraph at the top of a page:

E: H3[top] Other Issues

To indent a paragraph 1 inch from both margins:

E: [left='1in'; right='1in'] This paragraph will be indented from
E: both margins by 1 inch.

The result is:

[left='1in'; right='1in'] This paragraph will be indented from
both margins by 1 inch.

H2: Custom Phrase Formatting

Phrase formatting can be controlled by setting attributes.
The commonly used ones are given below.

!block table
Name            Purpose
family          font family
size            font size
color           text colour
bold            enable bold
italics         enable italics
underline       enable underline
changed         enable change bars
!endblock

For example, to change the size of a phrase to 11.5 points:

V:  I love {{N[size=11.5]custom formatting}}.

The result is:

I love {{N[size=11.5]custom formatting}}.


H2: Applying Phrase Attributes to Paragraphs

Phrase attributes can also be used for paragraphs.
For example, to add a change bar to a paragraph:

E:  [changed] This paragraph has a change bar.

The result is:

[changed] This paragraph has a change bar.


H2: sdf Blocks

Attributes can be applied to a block of text by using the {{FILT:sdf}}
filter. For example:

!block example; pure
!block sdf; size='8pt'; bold; align='Center'
This paragraph has custom formatting:

* and so does this.
!endblock
!endblock

The result is:

!block sdf; size='8pt'; bold; align='Center'
This paragraph has custom formatting:

* and so does this.
!endblock

!end_topic
sdf-2.001/doc/user/in_style.html010064400042570001753000000071660672242743500164020ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Document styles





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      1.5. Document styles
      

      

      1.5.1. Changing the style
      

      The general style (or type) of a document can be changed by initialising the OPT_STYLE variable on the top line of a document. For example:
      

         !init OPT_STYLE="manual"

      

      Alternatively, sdf's -s option can be used. For example:
      

         sdf -2ps -smanual mydoc

      

      
Note: The -s option overrides the init macro setting.

      

      

      1.5.2. Available styles
      

      The available document styles, grouped by style category, are:
      

      

      

Style


Purpose


      

      

General:


 


      

      

document


a normal document


      

      

manual


a manual


      

      

paper


a technical paper


      

      

Administration:


 


      

      

admin


generic administration document


      

      

fax


a fascimile


      

      

memo


a memorandum


      

      

newslttr


a newsletter


      

      

minutes


minutes of a meeting


      

      

Miscellaneous:


 


      

      

listing


a source code listing


      

      


      

      1.5.3. Building a title
      

      Each style category has a different way of building a title section:
      

        

      • general styles use the build_title macro

      • administration styles use the title filter

      • miscellaneous styles do not have a title.
      

      

      1.5.4. Creating new styles
      

      It is relatively simple to create new styles by inheriting details from an existing one.
      

      Refer to the SDF Guru Guide for details.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_cond.html010064400042570001753000000065640672242760700161670ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Conditional Text





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      6.4. Conditional Text
      

      Blocks of text can be conditionally included or excluded using the following macros:
      

         !if condition
   !elsif condition
   !else
   !endif

      

      These macros allow you to tune the output for different audiences. For example, you may wish to only include email directions if HTML is being generated:
      

      !if OPT_PP_HTML
Click {{[jump="mailto:joe"] here}} to send me email.
!endif

      

      
Note: 
      

        

      1. elseif can be used instead of elsif if you prefer.

      2. condition is an SDF expression where unknown variables do not give errors

      3. Conditional text blocks must be fully defined within a given file. This prevents an if macro within an included file excluding text in the file doing the including.
      

      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_phrs.sdf010064400042570001753000000006670630655663400160270ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Phrases

!block topics
Topic
in_phfmt
in_phlog
!endblock
sdf-2.001/doc/user/in_fgov.html010064400042570001753000000125430672242751600161760ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Overview





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      4.1. Overview
      

      

      4.1.1. Features
      

      SDF supports a range of features related to figures:
      

        

      • figures can be imported in a variety of formats including:
          

        • EPS - Encapsulated PostScript

        • WMF - Windows MetaFile

        • MIF - Maker Interchange Format

        • GIF - Graphics Interchange Format

        • JPEG - JPEG File Interchange Format

        • PNG - Portable Network Graphic Format

        • BMP - Windows Bitmap Format
        

      • logos can be easily added to title pages and online headers

      • figure positioning can be controlled

      • text can be wrapped around figures.
      

      

      4.1.2. Importing Figures Into SDF Documents
      

      The import macro is usually used to import a figure. The syntax is:
      

        !import "filename" [; parameters]

      

      For example:
      

        !import "sdfarch"

      

      

      4.1.3. Importing a Figure Into Paragraph Text
      

      To import a figure into the middle of a paragraph, the IMPORT phrase style is used. The syntax is:
      

          {{IMPORT:filename}}, or
    {{IMPORT[parameters]filename}}

      

      For example:
      

      Please visit our {{IMPORT:new}} web site!

      

      

      4.1.4. Figure Extensions
      

      It is generally best not to specify an extension for the filename containing the figure, as SDF will then use the best format it can find. The search rules are:
      

      

      

When generating


The search order is


      

      

PostScript


epsi, eps, wmf, mif, gif


      

      

HTML


jpeg, jpg, png, gif


      

      

Windows Help


bmp


      

      


      So a GIF file is all that is necessary if you are generating PostScript and HTML. However, if SDF finds an EPS file when it is generating PostScript, it will use that instead.
      

      

      4.1.5. Adding Logos
      

      The default implementations of the build_title macro, title filter and HTML header macros provide an easy way to add a company logo: by defining variables. The variables are:
      

      

      

Variable


Description


      

      

DOC_LOGO


the default logo


      

      

DOC_TITLE_LOGO


used in the title of a PostScript document


      

      

DOC_ADMIN_LOGO


used in the title of a PostScript admin. document


      

      

DOC_HTML_LOGO


used in the title of a HTML document


      

      

DOC_TOPIC_LOGO


used in the header of a HTML topic


      

      

DOC_MANUAL_LOGO


used on the front cover of a PostScript manual


      

      

DOC_COMPONENT_LOGO


used on the cover of each chapter in a PostScript manual


      

      


      In each case, the value of the variable is the filename containing the figure.
      

      If a given logo variable is not set, DOC_LOGO is used if it is set. Therefore, a company logo can be added to most SDF documents by simply defining DOC_LOGO is a configuration module (or library) which is loaded into every SDF document via the use (or inherit) macro.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_tb.html010064400042570001753000000053550672242757400156510ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Spreadsheet calculations





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      5. Tables
      

      Overview
      

      Table Styles
      

      Adding Table Titles
      

      Sizing Columns
      

      Positioning Tables
      

      Creating Heading, Footing and Group Rows
      

      Other Table Goodies
      

      Spreadsheet calculations
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_index.sdf010064400042570001753000000046160635672740600161620ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Indexes

H2: Marking Entries

Index entries are specified by using the {{OATTR:index}} object attribute.
If a value is omitted, the text of the phrase is used.
For example, the following are equivalent:

V:  {{CMD[index="mycmd"]mycmd}} is useful for many things.
V:  {{CMD[index]mycmd}} is useful for many things.

Note: The {{OATTR:index}} attribute is only supported by {{mif}} format.
The value is mapped to index marker text using the notation
defined in chapter 23/24 (for [[FrameMaker]] 5.x/4.x respectively)
of {{Using FrameMaker}}.

Commonly used index formats are outlined below.

!block table
Format      Description
abc         add an entry called {{abc}}
abc:xyz     add an entry called {{xyz}} under {{abc}}
abc;def     add entries called {{abc}} and {{def}}
!endblock

NB: To include an actual semi-colon within an [[SDF]] attribute value,
you need to specify two semi-colons. For example:

V:To install {{PRD[index="myApp;;install:myApp"]myApp}}, ...
NE:

H2: Index Types

Different index types can be specified using the {{index_type}} attribute.
For example:

V:{{[index;index_type="author"]Joe Bloggs}} is famous for ...

The default index type is {{standard}}. Other types supported are:

* comment
* subject
* author.

H2: Setting FrameMaker Markers

A numeric value can also be specified (0..25) for the {{index_type}}
attribute. The value maps directly to a [[FrameMaker]] marker type.
The most commonly used marker numbers are 0 and 1 which
correspond to the {{$marker1}} and {{$marker2}}
building blocks of headers and footers.

The following example indirectly sets the first footer line in QSD books
while defining a level 2 heading:

V:  H2: Policy Standard {{N[index_type=0]QSDS0036}}

H2: Generating an Index

To generate an index, set the {{DOC_IX}} variable.
For example:

E:  sdf -b -DDOC_IX ...

Note: Index generation is only supported when {{CMD:sdf}} is
used in "book mode".

To generate other types of indexes, it is currently necessary
to use [[FrameMaker]].
See Chapter 23/24 of {{Using FrameMaker}} for details.

!end_topic
sdf-2.001/doc/user/in_fggen.sdf010064400042570001753000000063110633426030000161100ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Creating Figures

H2: Types of Figure Formats

Figure formats are typically either:

* {{vector}} based, i.e. a set of drawing instructions
* {{bitmap}} based, i.e. a set of pixels.

For diagrams which look good when printed, a vector format (e.g. EPS)
is required. For window snapshots, a bitmap format (e.g. GIF)
is sufficient.

H2: Generating Bitmap-based Figures

With the current popularity of the World Wide Web, most diagramming
and image processing tools can now export JPEG, PNG and/or GIF formats.
Therefore, if HTML is the only output format you care about for a
given document, getting a figure into it is easy.

Occasionally, GIF format is also sufficient for paper-based documents.
However, a GIF figure which displays fine in a browser may or may not
display correctly in a PostScript document! The reason is that
FrameMaker 5.x has problems importing:

* certain GIFs in 89a format
* GIFs with interlacing
* GIFs with transparent backgrounds.

Therefore, if you want to import a GIF file into a PostScript
document, you will probably need to stick with GIF 87 format
and avoid anything fancy.

H2: Generating Vector-based Figures

For good quality diagrams,
you will need to export your figure from your drawing application
into a vector-based format that FrameMaker can successfully import.

The following information may be useful in selecting a vector-based format:

* 99% of Windows tools have a good WMF export filter, but EPS
  export is rarely supported and often broken (Visio 3.0 and
  Adobe Illustrator are known exceptions)
* FrameMaker 5.x on Solaris 2.x has a good EPS import filter, but
  the WMF import filter seems buggy
* FrameMaker 5.x on Windows 95/NT has a good WMF import filter.

So, if you are using FrameMaker on Windows 95/NT, WMF is the vector format
to use and generating it from a Windows-based tool should be easy.
However, if you are using FrameMaker on Solaris, EPS is the vector format
to use, but generating it from a Windows-based tool might be tricky.

H2: Generating EPS From Windows Applications

The following approach can often be used to generate an EPS file from
a Windows program:

^ Print PostScript to a file, typically via a PostScript printer
  configured to use the FILE: port.
+ Run Ghostscript's ps2epsi program on the file.

Depending on the combination of application and printer driver,
you may need to hand edit the ps file before you run ps2epsi.
See the {{REF[expand]SDF-FAQ}} for examples.

H2: Generating FrameMaker Figures

FrameMaker can be used to produce figures which
SDF can import when it is generating PostScript.
To do this, the steps are:

^ Create an anchored frame.
+ Draw the figure within it using FrameMaker's drawing tools.
+ Save the file into MIF format.

The main disadvantage with this approach is that FrameMaker 5.x
does not provide an easy way to convert the figure to other formats
(e.g. GIF).
sdf-2.001/doc/user/in_custf.html010064400042570001753000000154500672242762000163550ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Custom Formatting





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      6.6. Custom Formatting
      

      

      6.6.1. Overview
      

      One of the nice things about SDF is that system administrators can control the formatting of documents via templates. This has two major advantages:
      

        

      1. document authors can focus on content

      2. by default, documents have a consistent format.
      

      However, there are occasions when authors need to override the default formatting conventions. Custom formatting is supported for documents, paragraphs and phrases.
      

      

      6.6.2. Custom Document Formatting
      

      Document formatting can be controlled by setting variables. The commonly used ones are given below.
      

      

      

Name


Type


Purpose


      

      

DOC_TOC


integer


table of contents level


      

      

DOC_LOF


boolean


build a list of figures


      

      

DOC_LOT


boolean


build a list of tables


      

      

DOC_IX


boolean


build an index


      

      

DOC_TWO_SIDES


boolean


build a two-sided document


      

      


      For example, to create a two-sided document, add this line to your document:
      

        !define DOC_TWO_SIDES

      

      

      6.6.3. Custom Paragraph Formatting
      

      Paragraph formatting can be controlled by setting attributes. The commonly used ones are given below.
      

      

      

Name


Purpose


      

      

label


prefix label (e.g. Note:)


      

      

top


either Page (the default), Column, LPage or RPage


      

      

left


left margin indent (in points)


      

      

first


first line indent (in points)


      

      

right


right margin indent (in points)


      

      

justify


either Full, Left, Right or Center


      

      


      For example, to start a paragraph at the top of a page:
      

       H3[top] Other Issues

      

      To indent a paragraph 1 inch from both margins:
      

       [left='1in'; right='1in'] This paragraph will be indented from
 both margins by 1 inch.

      

      The result is:
      

      This paragraph will be indented from both margins by 1 inch.
      

      

      6.6.4. Custom Phrase Formatting
      

      Phrase formatting can be controlled by setting attributes. The commonly used ones are given below.
      

      

      

Name


Purpose


      

      

family


font family


      

      

size


font size


      

      

color


text colour


      

      

bold


enable bold


      

      

italics


enable italics


      

      

underline


enable underline


      

      

changed


enable change bars


      

      


      For example, to change the size of a phrase to 11.5 points:
      

        I love {{N[size=11.5]custom formatting}}.

      

      The result is:
      

      I love custom formatting.
      

      

      6.6.5. Applying Phrase Attributes to Paragraphs
      

      Phrase attributes can also be used for paragraphs. For example, to add a change bar to a paragraph:
      

        [changed] This paragraph has a change bar.

      

      The result is:
      

      This paragraph has a change bar.
      

      

      6.6.6. sdf Blocks
      

      Attributes can be applied to a block of text by using the sdf filter. For example:
      

      !block sdf; size='8pt'; bold; align='Center'
This paragraph has custom formatting:

* and so does this.
!endblock

      

      The result is:
      

      This paragraph has custom formatting:
      

        

      • and so does this.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



d-color: teal}
.changed {background-color: teal}
.changed {background-color: teal}
.changed {background-color: teal}
.changed {background-color: teal}
.changed {background-color: teal}
.changed {background-color: teasdf-2.001/doc/user/in_parag.html010064400042570001753000000037720672242751200163270ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Notes





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      3. Paragraphs
      

      Headings
      

      Example Paragraphs
      

      Lists
      

      Notes
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_tbsty.html010064400042570001753000000107330672242753500164020ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Table Styles





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      5.2. Table Styles
      

      

      5.2.1. The style Attribute
      

      The look of a table is controlled by the style attribute. For example:
      

      !block table; style="rows"
Name   Phone
Bill   123 4567
Joe    789 1234
Mary   584 3333
!endblock

      

      The result is:
      

      

      

Name


Phone


      

      

Bill


123 4567


      

      

Joe


789 1234


      

      

Mary


584 3333


      

      


      The other styles available are shown below.
      

      

      5.2.2. columns
      

      

      

Name


Phone


      

      

Bill


123 4567


      

      

Joe


789 1234


      

      

Mary


584 3333


      

      


      

      5.2.3. plain
      

      

      

Name


Phone


      

      

Bill


123 4567


      

      

Joe


789 1234


      

      

Mary


584 3333


      

      


      

      5.2.4. grid
      

      

      

Name


Phone


      

      

Bill


123 4567


      

      

Joe


789 1234


      

      

Mary


584 3333


      

      


      

      5.2.5. shade
      

      

      

Name


Phone


      

      

Bill


123 4567


      

      

Joe


789 1234


      

      

Mary


584 3333


      

      


      

      5.2.6. Changing the Default Table Style
      

      The default style is columns. This can be changed via the DEFAULT_TABLE_STYLE variable. For example:
      

        !define DEFAULT_TABLE_STYLE "grid"
  # the default table style is now grid ...

      

      

      5.2.7. Creating New Table Styles
      

      New table styles can be defined. See Extending SDF in the SDF Guru Guide for details.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_notes.html010064400042570001753000000070330672242751100163560ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Notes





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      3.4. Notes
      

      

      3.4.1. Short Notes
      

      The paragraph tag for adding a single paragraph note is Note. For example:
      

        Note: Life is too short to waste time being unhappy.

      

      The result is:
      

      
Note: Life is too short to waste time being unhappy.

      

      

      3.4.2. Changing the Label
      

      You can change the label for a note by using the label paragraph attribute. For example:
      

        Note[label='Important: '] Life is too short to drink bad wine.

      

      The result is:
      

      
Important: Life is too short to drink bad wine.

      

      

      3.4.3. Long Notes
      

      If the note requires more than one paragraph, use the note filter. For example:
      

        !block note
  Life is too short to:

  * waste time being unhappy
  * worry about yesterday.
  !endblock

      

      The result is:
      

      
Note: Life is too short to:
      

        

      • waste time being unhappy

      • worry about yesterday.
      

      

      

      3.4.4. The NB/NE Tags
      

      Before the note filter existed, long notes were created by using the NB (Note Begin) and NE (Note End) tags. For example:
      

        NB: Life is too short to:

  * waste time being unhappy
  * worry about yesterday.

  NE:

      

      These paragraph styles are still supported, although the note filter is now the recommended way of specifying long notes.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_tbsiz.html010064400042570001753000000177520672242754600164020ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Sizing Columns





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      5.4. Sizing Columns
      

      

      5.4.1. Dynamic Sizing
      

      SDF supports dynamic column widths for paper documentation, i.e. if a width is not specified for a column, then the column is sized based on the text within it and the space available. As a result, it is rarely necessary to explicitly size columns.
      

      

      5.4.2. The format Attribute
      

      The format attribute of the table filter is used to specify column widths for paper documentation. Its value is either:
      

        

      • a single number, in which case each digit represents 10% of the width available to the table, or

      • a comma-separated list of column width specifications.
      

      For example, to specify 3 columns with widths of 20%, 10% and 30% respectively:
      

      !block table; format=213
Name   Age Address
Bill   42  123 Main Road
Joe    21  456 Queen Street
!endblock

      

      The result is:
      

      

      

Name


Age


Address


      

      

Bill


42


123 Main Road


      

      

Joe


21


456 Queen Street


      

      


      
Note: The format parameter has no impact on HTML generation - all columns in HTML are currently dynamically sized.

      

      

      5.4.3. Column Width Specifications
      

      Examples of the column width specifications supported are given below.
      

      

      

Value


Meaning


      

      

30pt


an exact size (other supported units are cm, mm, " and in)


      

      

30%


a percentage of the size available


      

      

30


a percentage of the size available (% is implicit)


      

      

10-20


dynamic size between 10% and 20% of the total width


      

      

-20


dynamic size between 0% and 20% of the total width


      

      

10-


dynamic size between 10% and 100% of the total width


      

      

-


dynamic size between 0% and 100% of the total width


      

      

3*


3 units of the remaining space


      

      

*


same as 1*


      

      


      For example, in the table below, the second column will be twice the size of the last column.
      

      !block  table; format="20,2*,10,*"
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock

      

      The output is:
      

      

      

Name


Column2


Column3


Column4


      

      

A


B


C


D


      

      

X


Hello dear world


Y


Z


      

      


      

      5.4.4. Default Sizing Rules and Narrow Tables
      

      If a column is not given a size, the following rules are used:
      

        

      1. The last unspecified column size is implicitly '*' (i.e. the rest), unless the narrow attribute is set, in which case the size is implicitly '-' (i.e. as much as needed).

      2. The other unknown sizes are implicitly '-'.
      

      For example, the first and third columns in the table below will be dynamically sized. The first column will take as much space as required and the last column will expand so that the table takes the full width of the text area.
      

      !block  table; format=",30,,10"
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock

      

      The output is:
      

      

      

Name


Column2


Column3


Column4


      

      

A


B


C


D


      

      

X


Hello dear world


Y


Z


      

      


      However, in the example below, each column will only take as much space is required, making the table narrower than it would be otherwise.
      

      !block  table; narrow
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock

      

      The output is:
      

      

      

Name


Column2


Column3


Column4


      

      

A


B


C


D


      

      

X


Hello dear world


Y


Z


      

      


      

      5.4.5. Equalised Column Widths
      

      If an = character is used in place of a - character for a column width, then those columns will be equalised in size. For example, the second and forth columns in the table below will be made equal in size.
      

      !block  table; format="20,5=30,10,="
Name    Column2             Column3     Column4
A       B                   C           D
X       Hello dear world    Y           Z
!endblock

      

      The output is:
      

      

      

Name


Column2


Column3


Column4


      

      

A


B


C


D


      

      

X


Hello dear world


Y


Z


      

      


      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



he column is sized bassdf-2.001/doc/user/in_fg.html010064400042570001753000000043170672242752600156320ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Positioning a Figure





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      4. Figures
      

      Overview
      

      Creating Figures
      

      Adding Figure Titles
      

      Positioning a Figure
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_ovpar.sdf010064400042570001753000000050430635011350400161530ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Paragraphs

H2: Introduction

Paragraphs have the following format:

E:   line1
E:   ...
E:   lineN

Leading and trailing whitespace on lines is generally ignored.
Paragraphs are separated by blank lines or:

* {{comment lines}} - first non-whitespace character is "#"
* {{macros}} - first non-whitespace character is "!".

For normal paragraphs, simply specify the text on one or more lines.
For example:

E:   I like products which are simple to use and
E:   do what I expect. We should encourage engineers
E:   to design more products with these qualities.


H2: Paragraph styles

A paragraph can be given a style using the following syntax:

E:   style":"line1
E:   ...
E:   lineN

Tagged paragraphs do not need to be separated by blank lines.
{{style}} is a sequence of one or more of the following characters:

* letters
* digits
* underscore character (_).

Whitespace is not permitted before the ":" but is generally
ignored immediately after it. The style is optional and
defaults to N (for Normal). The text is also optional.


H2: Commonly used styles

Commonly used paragraph styles are given below.

!block table
Style           Description
N               normal paragraph (the default)
H1 .. H6        chapter heading at level 1-6
A1 .. A6        appendix heading at level 1-6
P1 .. P6        plain heading at level 1-6
Note            a single paragraph note
E               fixed-width (example) text
!endblock

For example:

E:   Note: Life is too short to drink bad wine.

The result is:

Note: Life is too short to drink bad wine.


H2: Special styles

For certain styles, the following syntax is also supported:

E:   special_style line1
E:   ...
E:   lineN

The special styles available are:

!block table
Style           Description
. .. ......     paragraph or plain list item at level 1-6
* .. ******     unordered list at level 1-6
- .. -----      unordered list at level 2-6
^ .. ^^^^^^     first entry in an ordered list at level 1-6
+ .. ++++++     next entry in an ordered list at level 1-6
!endblock

For example:

E:* fruits:
E:  - peach
E:  - banana
E:* vegetables:
E:  - potato
E:  - carrots.

The result is:

* fruits:
  - peach
  - banana
* vegetables:
  - potato
  - carrots.
sdf-2.001/doc/user/in_fggen.html010064400042570001753000000123050672242752000163120ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Creating Figures





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      4.2. Creating Figures
      

      

      4.2.1. Types of Figure Formats
      

      Figure formats are typically either:
      

        

      • vector based, i.e. a set of drawing instructions

      • bitmap based, i.e. a set of pixels.
      

      For diagrams which look good when printed, a vector format (e.g. EPS) is required. For window snapshots, a bitmap format (e.g. GIF) is sufficient.
      

      

      4.2.2. Generating Bitmap-based Figures
      

      With the current popularity of the World Wide Web, most diagramming and image processing tools can now export JPEG, PNG and/or GIF formats. Therefore, if HTML is the only output format you care about for a given document, getting a figure into it is easy.
      

      Occasionally, GIF format is also sufficient for paper-based documents. However, a GIF figure which displays fine in a browser may or may not display correctly in a PostScript document! The reason is that FrameMaker 5.x has problems importing:
      

        

      • certain GIFs in 89a format

      • GIFs with interlacing

      • GIFs with transparent backgrounds.
      

      Therefore, if you want to import a GIF file into a PostScript document, you will probably need to stick with GIF 87 format and avoid anything fancy.
      

      

      4.2.3. Generating Vector-based Figures
      

      For good quality diagrams, you will need to export your figure from your drawing application into a vector-based format that FrameMaker can successfully import.
      

      The following information may be useful in selecting a vector-based format:
      

        

      • 99% of Windows tools have a good WMF export filter, but EPS export is rarely supported and often broken (Visio 3.0 and Adobe Illustrator are known exceptions)

      • FrameMaker 5.x on Solaris 2.x has a good EPS import filter, but the WMF import filter seems buggy

      • FrameMaker 5.x on Windows 95/NT has a good WMF import filter.
      

      So, if you are using FrameMaker on Windows 95/NT, WMF is the vector format to use and generating it from a Windows-based tool should be easy. However, if you are using FrameMaker on Solaris, EPS is the vector format to use, but generating it from a Windows-based tool might be tricky.
      

      

      4.2.4. Generating EPS From Windows Applications
      

      The following approach can often be used to generate an EPS file from a Windows program:
      

        

      1. Print PostScript to a file, typically via a PostScript printer configured to use the FILE: port.

      2. Run Ghostscript's ps2epsi program on the file.
      

      Depending on the combination of application and printer driver, you may need to hand edit the ps file before you run ps2epsi. See the SDF Frequently Asked Questions for examples.
      

      

      4.2.5. Generating FrameMaker Figures
      

      FrameMaker can be used to produce figures which SDF can import when it is generating PostScript. To do this, the steps are:
      

        

      1. Create an anchored frame.

      2. Draw the figure within it using FrameMaker's drawing tools.

      3. Save the file into MIF format.
      

      The main disadvantage with this approach is that FrameMaker 5.x does not provide an easy way to convert the figure to other formats (e.g. GIF).
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_start.html010064400042570001753000000033230672242744100163630ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Building a title





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      1. Getting Started
      

      Introducing SDF
      

      Installing SDF
      

      A simple example
      

      Generating outputs
      

      Document styles
      

      Building a title
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_insta.html010064400042570001753000000234110672242742300163440ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Installing SDF





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      1.2. Installing SDF
      

      

      1.2.1. Overview
      

      If SDF is not yet installed, you will need to fetch it and install it. The latest version of SDF can be fetched from the SDF download page, http://www.mincom.com/mtr/sdf/download.html.
      

      If Perl is not installed, you will also need to fetch and install it. Various ports of Perl can be obtained from the Perl Home Page (http://www.perl.com/index/).
      

      SDF installation details are provided below for:
      


      Some general Installation Notes are also provided.
      

      

      1.2.2. Unix
      

      Use the tar and gunzip programs to unpack the distribution like this:
      

         gunzip sdf-2.000.tar.gz
   tar xvf sdf-2.000.tar

      

      Build, test and install the software like this:
      

         perl Makefile.PL
   make
   make test
   make install

      

      

      1.2.3. Windows NT
      

      Unpack the distribution using a program which understands long file names (e.g. WinZip).
      

      Within the Control Panel, go to the System properties, select the Environment tab and edit the variables as follows:
      

        

      1. Update the PATH to include the bin\dos directory where SDF is installed.

        
For example, if SDF is installed in c:\sdf, then you need to edit the PATH system variable to include c:\sdf\bin\dos.

      2. Edit (or add) the PERL5LIB variable to include the Perl libraries used by SDF.

        
For example, if SDF is installed in c:\sdf, then you need to edit the PERL5LIB variable to include c:\sdf\perllib.

      3. Set the SDFBIN variable to point to the directory containing SDF's scripts, including the trailing \.

        
For example, if SDF is installed in c:\sdf, then you need to set the SDFBIN variable to c:\sdf\bin\.
      

      Test the software. To do this:
      

        

      1. Start an MS-DOS window.

      2. Change directory to the t directory within the SDF distribution.

      3. Run sdf without any arguments to confirm that SDF was successfully installed.

      4. Run sdftest.
      

      If anything fails, sdftest will leave the failed .out and .log files in the relevant directories.
      

      

      1.2.4. Windows 95
      

      Unpack the distribution using a program which understands long file names (e.g. WinZip).
      

      Update the PATH to include the bin\dos directory where SDF is installed. For example, if SDF is installed in c:\sdf, then the command is:
      

         set PATH=%PATH%;c:\sdf\bin\dos

      

      Edit (or add) the PERL5LIB system variable to include the Perl libraries used by SDF. For example, if SDF is installed in c:\sdf, then the command is:
      

         set PERL5LIB=%PERL5LIB%;c:\sdf\perllib

      

      Set the SDFBIN variable to point to the directory containing SDF's scripts, including the trailing \. For example, if SDF is installed in c:\sdf, then the command is:
      

         set SDFBIN=c:\sdf\bin\

      

      Test the software. To do this:
      

        

      1. Change directory to the t directory within the SDF distribution.

      2. Run sdf without any arguments to confirm that SDF was successfully installed.

      3. Run sdftest.
      

      If anything fails, sdftest will leave the failed .out and .log files in the relevant directories.
      

      
Note: PATH, PERL5LIB and SDFBIN should be set within your autoexec.bat file.

      

      

      1.2.5. MS-DOS/Windows 3.x
      

      Use pkunzip to unpack the distribution. The command is:
      

         pkunzip -d sdf.zip

      

      Update the PATH to include the bin\dos directory where SDF is installed. For example, if SDF is installed in c:\sdf, then the command is:
      

         set PATH=%PATH%;c:\sdf\bin\dos

      

      Edit (or add) the PERL5LIB system variable to include the Perl libraries used by SDF. For example, if SDF is installed in c:\sdf, then the command is:
      

         set PERL5LIB=%PERL5LIB%;c:\sdf\perllib

      

      Set the SDFBIN variable to point to the directory containing SDF's scripts, including the trailing \. For example, if SDF is installed in c:\sdf, then the command is:
      

         set SDFBIN=c:\sdf\bin\

      

      Test the software. To do this:
      

        

      1. Change directory to the t directory within the SDF distribution.

      2. Run sdf without any arguments to confirm that SDF was successfully installed.

      3. Run sdftest.
      

      If anything fails, sdftest will leave the failed .out and .log files in the relevant directories.
      

      
Note: PATH, PERL5LIB and SDFBIN should be set within your autoexec.bat file.

      

      

      1.2.6. Installation Notes
      

      1.2.6.1. Distribution Formats
      

      The tar.gz and zip distributions should both contain the same set of files. Therefore, it shouldn't matter which distribution you obtain provided you have the necessary software to unpack it.
      

      1.2.6.2. The sdf.ini File
      

      The sdf.ini configuration file (in the sdf/home directory on Perl's library path) contains several sets of configuration parameters which you may want to edit after SDF is installed. Refer to the comments in the file for further details.
      

      1.2.6.3. Win32 Support
      

      SDF has been briefly tested with:
      

        

      • Gurusamy Sarathy's 5.004_02 Perl port (August 97), and

      • ActiveState's Perl port build 315 (based on 5.003_07).
      

      Both seem to work ok, although running sdftest with the 5.004_02 port leaves zero length .out and .log files for the tests which work (when they should be deleted).
      

      1.2.6.4. The SDFBIN Environment Variable
      

      This environment variable is only used by the Windows/DOS wrapper batch files within bin/dos to find the real scripts. Therefore, if you wish to wrap the scripts in some other way, then there is no need to set this variable.
      

      1.2.6.5. Macintosh support
      

      Unlike earlier versions, the 2.000 release includes support for Macintosh filename handling. Installation instructions for the Macintosh will be made available soon.
      

      1.2.6.6. Testing Notes
      

      When the sdf command is run without arguments, the output should be something like:
      

      usage  : sdf [+alias] [-h[help]] [-o[out_ext]] [-l[log_ext]] [-2 format] [-D var
iable,..] [-n split_level] [-f flag,..] [-I include_path,..] [-p prefilter] [-a
parameters] [-P[plang]] [-N[line_numbers]] [-r report] [-L locale] [-k look] [-s
 style] [-S page_size] [-c config] [-u uses,..] [-H head_level] [-d driver] [-y
post_filter] [-z post_process,..] [-t target] [-v[verbose]] [-w width] sdf_file
...
purpose: convert an sdf file to another format
version: 2.000    (SDF 2.000)

      

      If this fails, check the following:
      

        

      1. perl 5.003 or later is installed (type perl -v to test)

      2. the sdf script is on your path and under Unix, is executable.
      

      SDF is supplied with a regression testing system. To run the tests, change to the t directory within the SDF distribution and execute sdftest like this:
      

         sdftest

      

      This command can be used at anytime to verify your installation of SDF.
      

      The SDF Sample Showcase contains SDF source code and matching outputs. If you wish to conduct further tests, these samples can be used.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_tbrow.sdf010064400042570001753000000036600633603022000161610ustar00iancmtr00000400000236H1: Creating Heading, Footing and Group Rows

H2: Overview

The {{FILT:table}} filter now supports the following attributes:

* {{headings}} - the number of heading rows at the top of the table
* {{footings}} - the number of footing rows at the end of the table
* {{groups}} - look for group rows in the table.

H2: Heading Rows

If the {{headings}} attribute is not defined, then
the column headings are generated using the column names given on
the {{parsing}} line. For example, the column headings in the table
below will be {{Name}} and {{Age}}:

!block example
!block table
Name    Age
Bill    42
!endblock
!endblock

Alternatively, if the {{headings}} attribute is defined,
then that number of {{data}} rows are used as the column headings,
i.e. the parsing line is not used to build the column headings.
For example, the column headings in the table below will be
{{"Title"}} and {{Age}} (remembering that a filter attribute is
implicitly given the value 1 is no value is supplied).

!block example
!block table; headings
A       B
"Title" Age
Bill    42
Sally   23
!endblock
!endblock

Likewise, the column headings below will be {{Preferred Title}} and
{{Likely Age}} with each heading taking 2 rows.

!block example
!block table; headings=2
A           B
Preferred   Likely
Title       Age
Bill        42
Sally       23
!endblock
!endblock

H2: Footing Rows

These work exactly the same as table headings, except that no footings
are generated by default.

H2: Group Rows

If the {{groups}} parameter is specified, SDF assumes that rows
that end in : are group rows. For example:

!block example
!block table; groups
Fruit      Comments
Tropical:
mango      a fruit-bat favorite
banana     great for smoothies
Other:
Tomato     often matched with basil
!endblock
!endblock

The result is:

!block table; groups
Fruit      Comments
Tropical:
mango      a fruit-bat favorite
banana     great for smoothies
Other:
Tomato     often matched with basil
!endblock
sdf-2.001/doc/user/in_lists.sdf010064400042570001753000000043620635011350400161650ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Lists

H2: Overview

[[SDF]] supports 3 types of lists:

* {{unordered}} - items are bulleted
* {{plain}} - items are not bulleted
* {{ordered}} - items are labelled with numbers or letters.

As lists are so common, they are supported by a special syntax:

E:   special_tag text

where {{special_tag}} is a sequence of 1 to 6 special characters.
Spaces or tabs between the tag and text are ignored.

H2: Unordered Lists

To define an unordered list, use the '*' character. For example:

E:* peach
E:* banana
E:* mango.

The result is:

* peach
* banana
* mango.

H2: Plain Lists

To define a plain list, use the '.' character. For example:

E:. peach
E:. banana
E:. mango.

The result is:

. peach
. banana
. mango.

H2: Ordered Lists

To define an ordered list, use the '^' character for the first
item and the '+' character for remaining items. For example:

E:^ peach
E:+ banana
E:+ mango.

The result is:

^ peach
+ banana
+ mango.

H2: List Paragraphs

To nest a normal paragraph inside a list, use the '.' tag.
For example:

E:* peach
E:. This is one of my favorites.

The result is:

* peach
. This is one of my favorites.

H2: Nested Lists

Lists can be nested up to 6 levels. The nesting level is taken
from the number of special characters in the tag. For example:

E:** a bulleted list at level 2
E:^^^ an ordered list at level 3

To nest normal paragraphs inside these lists, use plain list items.
For example:

E:** a bulleted list at level 2
E:.. A normal paragraph at level 2.

H2: The '-' Special Tag

As a convenience, the '-' character can be used to specify
a bulleted list at level 2. For example:

E:* inputs:
E:  - programmers
E:  - pizza
E:* outputs:
E:  - software
E:  - empty pizza boxes.

The result is:

* inputs:
  - programmers
  - pizza
* outputs:
  - software
  - empty pizza boxes.

Likewise, the tags '--' to '-----' are equivalent to the tags
'***' to '******'.

!end_topic
sdf-2.001/doc/user/in_intro.html010064400042570001753000000117520672242741600163700ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Introducing SDF





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      1.1. Introducing SDF
      

      

      1.1.1. What is SDF?
      

      SDF (Simple Document Format) is a freely available document development system which generates high quality outputs in a variety of formats from a single source. The output formats supported include PostScript™ , HTML, POD, plain text, man pages, LaTeX, SGML, Windows™  help, MIF and RTF. If the idea of specifying documents in a logical manner via a simple markup language sounds appealing, SDF may be useful to you.
      

      SDF documents are simple to create and maintain, minimising the time spent on documentation. In particular, SDF directly supports the creation and maintenance of large, on-line documentation systems (including intranets) via centralised hypertext management and rule-based hypertext generation.
      

      

      1.1.2. What is SDF useful for?
      

      As well as normal documents, SDF is useful for:
      

        

      • user manuals (paper-based and online)

      • online document catalogs

      • Perl module documentation

      • Delphi™  component documentation

      • source code listings (pretty printing most languages).
      

      SDF is also good for literate programming, i.e. documentation can be embedded in the comments of most programming languages and can be selectively extracted. The embedded documentation can be in any markup language you like, although there are advantages to using SDF's markup language.
      

      

      1.1.3. Requirements
      

      SDF has been completely developed in Perl, a popular and highly portable scripting language. Perl 5.004 or later is recommended, although SDF may run on earlier versions of Perl 5.
      

      To generate PostScript, SDF requires one of the following:
      

        

      • the freely available pod2ps program

      • the freely available SGML-Tools and LaTeX packages

      • FrameMaker 5.x or later

      • another word processor which can import RTF.
      

      Earlier versions of FrameMaker will generally work, but I don't explicitly support them.
      

      To generate Windows help, a help compiler (e.g. hcp.exe) is required.
      

      

      1.1.4. SDF on the World Wide Web
      

      The SDF home page URL is http://www.mincom.com/mtr/sdf. From the home page, you can:
      

        

      • download the latest software

      • browse the FAQ

      • report defects

      • suggest enhancements.
      

      

      1.1.5. Fetching SDF
      

      SDF is available using anonymous ftp. The URL of the base directory is ftp://ftp.mincom.com/pub/mtr/sdf. The latest release is available in a variety of formats.
      

      

      1.1.6. Mailing lists
      

      The following mailing lists are available:
      


      To subscribe to these lists, send email to sdf-users-request@mincom.com and/or sdf-bugs-request@mincom.com for instructions on using factotum, the majordomo variant that manages these lists. In short, send email to factotum@mincom.com with a message body of subscribe sdf-users or subscribe sdf-bugs.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_table.sdf010064400042570001753000000007750633426375400161410ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Tables

!block topics
Topic
in_tbov
in_tbfmt
in_tbsty
in_tbtit
in_tbsiz
in_tbpos
in_tbrow
in_tbcol
in_tbcel
in_tboth
!endblock
sdf-2.001/doc/user/in_ovflt.sdf010064400042570001753000000036270635011350400161640ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Filters

H2: Introduction

A {{filter}} controls how a block of text is interpreted.
The text is usually delimited by {{MAC:block}} and {{MAC:endblock}}
macros.

For example, tables are usually defined via the {{FILT:table}} filter:

E:!block table
E:Option  Description
E:-h      display help
E:-o      specify the output extension
E:!endblock

The result is:

!block table
Option  Description
-h      display help
-o      specify the output extension
!endblock


H2: Commonly used filters

Some of the commonly used filters are:

!block table; coltags='FILT'
Filter      Description
table       the lines are a table in SDF's {{FMT:TBL}} format
example     the lines are example paragraphs
title       used to build a title block for memos, faxes, etc.
topics      include files as sub-topics
appendix    replace H1 styles with A1, etc.
plain       replace H1 styles with P1, etc.
!endblock

A complete list of the supported filters and their parameters
is given in the {{DOC: SDF Reference}} manual.


H2: Other macros supporting filters

Other macros also support filters. These include:

* {{MAC:include}} - include text from another file
* {{MAC:execute}} - include the output of a system command.

For example, the following line includes another [[SDF]] file
and formats it as an appendix:

E:   !include "tips.sdf"; appendix

Note: The {{FILT:appendix}} and {{FILT:plain}} filters enable
authors to construct topics without needing to worry about how
those topics will be used, e.g. a topic may be a chapter in
one document and an appendix in another!
sdf-2.001/doc/user/in_ovphr.sdf010064400042570001753000000056020661460503400161720ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Phrases

H2: Introduction

A {{phrase}} is a section of text within a paragraph
enclosed in the symbols E<2{> and E<2}>. Like paragraphs,
phrases are optionally tagged with a style.
Some examples are given below.

!block table
SDF                         Typical_result
E<2{>Hello worldE<2}>       {{Hello world}}
E<2{>1:Hello worldE<2}>     {{1:Hello world}}
E<2{>2:Hello worldE<2}>     {{2:Hello world}}
E<2{>B:Hello worldE<2}>     {{B:Hello world}}
E<2{>I:Hello worldE<2}>     {{I:Hello world}}
E<2{>SECT:TablesE<2}>       {{SECT:Tables}}
E<2{>FILE:autoexec.batE<2}> {{FILE:autoexec.bat}}
!endblock


H2: Commonly used styles

Some commonly used phrase styles are given below.

!block table; groups
Tag         Description                     Sample_Output
Emphasis:
1           1st level emphasis (default)    {{1:emphasis 1}}
2           2nd level emphasis              {{2:emphasis 2}}
3           3rd level emphasis              {{3:emphasis 3}}
ST          strong emphasis                 {{ST:strong emphasis}}
Formatting:
N           normal                          {{N:some normal text}}
I           italic                          {{I:some italic text}}
B           bold                            {{B:some bold text}}
U           underline                       {{U:some underline text}}
EX          example                         {{EX:some example text}}
Types:
EMAIL       email address                   {{EMAIL:ianc@mincom.com}}
FILE        Filename                        {{FILE:myfile.sdf}}
SECT        Section                         {{SECT:Paragraphs}}
URL         Uniform Resource Locator        {{URL:http://www.mincom.com}}
Classes:
DOC         document title                  {{DOC:SDF User Guide}}
REF         reference (document code)       {{REF:MTR-SDF-0002}}
ORG         organisation                    {{ORG:Mincom}}
PRD         product                         {{PRD:MIMS}}
!endblock

Note: When emphasising text, it is generally better to
use an emphasis style rather than a formatting style as the best way of
doing so depends on the output format.


H2: Type vs class styles

A {{type}} (e.g. EMAIL) simply marks a phrase as a logical entity.
Rules may be defined for processing (e.g. generating hypertext) for
these types.

A {{class}} (e.g. DOC) is a special kind of type where the entity
must be a member of a predefined set. Rules can also be defined
for processing classes, although hypertext jumps are often defined
for each entity in the tables which define the known entities.
Refer to {{SECT:Object Management}}, later.
sdf-2.001/doc/user/in_overv.sdf010064400042570001753000000021700630670417200161730ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Language overview

H2: Basic concepts

The basic concepts within SDF documents are:

!block table
Concept     Description
paragraph   one or more lines of text
phrase      a section of text within a paragraph
style       the type of a document, paragraph, phrase or table (e.g. H1)
macro       a command embedded in a document (e.g. !define)
variable    a named value (e.g. DOC_NAME)
filter      a rule to use when processing certain sections of text (e.g. table)
attribute   a named parameter of a paragraph, phrase or filter (e.g. jump)
expression  a literal or expression to evaluate (e.g. "Ian Clatworthy").
!endblock

Further details about these are given below.

!block topics
Topic
in_ovpar
in_ovphr
in_ovmac
in_ovvar
in_ovflt
in_ovatt
in_ovexp
!endblock
sdf-2.001/doc/user/in_tbtit.sdf010064400042570001753000000027430635011350400161560ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Adding Table Titles

H2: Adding a Title to a Table

To add a title, use the {{title}} attribute.
For example:

E:!block table; title="Phone numbers of good friends"
E:Name   Phone
E:Bill   123 4567
E:Joe    789 1234
E:Mary   584 3333
E:!endblock

The output is:

!block table; title="Phone numbers of good friends"
Name   Phone
Bill   123 4567
Joe    789 1234
Mary   584 3333
!endblock

H2: Adding a Title to a Psuedo Table

Occasionally, it is useful to title a table by hand.
To do this, use the TT (Table Title) paragraph style.
For example:

E:   TT: My Boring Looking Table
E:   !include "my_table.txt"; example; wide

H2: Generating a List of Tables

A list of tables can be generated from the table titles.
To do this, set the {{VAR:DOC_LOT}} variable. For example:

E:# Build the title
E:!define DOC_NAME "World Peace in 60 Days"
E:!define DOC_LOT
E:!build_title

This will generate a list of tables after the table of contents.

H2: Changing the List of Tables Title

The default title for the list of tables is "List of Tables".
To change this, set the DOC_LOT_TITLE.
For example:

E:!define DOC_LOT_TITLE "Tables"
sdf-2.001/doc/user/in_ovvar.sdf010064400042570001753000000065670635673226200162130ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Variables

H2: Introduction

A {{variable}} is a named value. Document-wide settings are
controlled in SDF using variables. Likewise, authors can
define and access their own variables. In either case,
the value of a variable can be referenced in a paragraph
by delimiting it with the special symbols E<2[> and E<2]>.

For example:

V:  !define MY_EMAIL 'abc@xyz.com'
V:  My electronic mail address is [[MY_EMAIL]].

The result is:

!define MY_EMAIL 'abc@xyz.com'
My electronic mail address is [[MY_EMAIL]].


H2: Commonly used system variables

Some commonly used system variables are:

!block table; groups; coltags='VAR'
Variable            Description
Options:
OPT_LOOK            the overall look (e.g. simple, fancy)
OPT_STYLE           the general type (e.g. memo, manual)
Titles:
DOC_NAME            the title, excluding the type (e.g. SDF)
DOC_TYPE            the title type (e.g. User Guide)
DOC_AUTHOR          the author
DOC_TOC             the number of heading levels in the table of contents
!endblock


H2: Setting variables

Variables can be set via:

* the {{MAC:define}} macro
* the {{MAC:default}} macro
* the {{MAC:init}} macro
* {{CMD:sdf}}'s command line.

To undefine a variable, use the {{MAC:undef}} macro.


H2: The Define macro

Variables are usually set in [[SDF]] by using the {{MAC:define}} macro.
The format is:

E:   !define symbol [expression]

Examples are:

E:   !define LONG
E:   !define VERSION "1.002"

{{symbol}} is a sequence of letters, digits and underscore.
If {{expression}} is omitted, the default value is 1.


H2: The Default macro

It is often a good idea to only define a variable if it does not
already have a value. To do this, use the {{MAC:default}} macro.
The format is:

E:   !default symbol [expression]

For example:

E:   !default VERSION "1.002"

{{symbol}} is a sequence of letters, digits and underscore.
If {{expression}} is omitted, the default value is 1.


H2: The Init macro

Generally speaking, the first thing {{CMD:sdf}} does is to
load the standard library ({{stdlib.sdm}}).
However, if the first line of an SDF document is the {{MAC:init}}
macro, the nominated variables are initialised {{before}}
the standard library is loaded. This allows an SDF
document to initialise variables used within the standard library.
The format of the init macro is:

E:   !init name1["="expression1]";" name2["="expression2] ...

For example:

E:   !init OPT_STYLE="memo"

Note: Certain variables cannot be set after the standard library
is loaded. These variables can {{only}} be set via {{CMD:sdf}}'s
command line or via the {{MAC:init}} macro.


H2: Using the command line

It is occasionally useful to set variables via {{CMD:sdf}}'s -D option.
Multiple definitions can be separated by commas.
For example:

E:   sdf -DLONG,VERSION="1.002" ...

Alternatively, the option can be repeated. For example:

E:   sdf -DLONG -DVERSION="1.002" ...

In either case, if a value is not specified for a variable, 1 is assumed.

Note: Variables set on the command line override the values
set by the {{MAC:init}} macro.
sdf-2.001/doc/user/credits.html010064400042570001753000000076620672242763200162110ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Credits





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      A. Credits
      

      SDF has taken several years to put together and would not exist in its current form without the contributions below.
      

      Firstly, thanks to my former Leeds and Northrup Australia colleagues, particularly Tom Beale, Craig Gibbings and Greg Birnie, for inspiring my initial interest in literate programming.
      

      Secondly, thanks to Tim Hudson (tjh@cryptsoft.com) for being SDF's biggest fan. Tim has assisted in design, fixed bugs, added features, "sold" SDF to many of its current user base and generally hassled me to package SDF into its current form. Thanks also to Chris Moran (chris.moran@mincom.com) for maintaining the SDF Home Page, assisting in design, etc. Many other Mincom colleagues have assisted with SDF, particularly Craig Willis and David Cox. Thanks to everyone involved.
      

      SDF is built on Perl, a freely available scripting language created by Larry Wall (larry@wall.org). Without Perl, SDF would not exist. Thanks Larry.
      

      Finally, thanks to my wife, Geraldine, for being my best friend and inspiring me to develop SDF.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_insta.sdf010064400042570001753000000162570647625171600161740ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Installing SDF

H2: Overview

If SDF is not yet installed, you will need to fetch it and install it.
The latest version of SDF can be fetched from the SDF download page,
{{URL:[[SDF_DOWNLOAD]]}}.

If Perl is not installed, you will also need to fetch and install it.
Various ports of Perl can be obtained from the Perl Home Page
({{http://www.perl.com/index/}}).

SDF installation details are provided below for:

!block sections
* Unix
* Windows NT
* Windows 95
* MS-DOS/Windows 3.x.
!endblock

Some general {{SECT:Installation Notes}} are also provided.

H2: Unix

Use the {{CMD:tar}} and {{CMD:gunzip}} programs to unpack the distribution
like this:

>   gunzip sdf-2.000.tar.gz
>   tar xvf sdf-2.000.tar

Build, test and install the software like this:

>   perl Makefile.PL
>   make
>   make test
>   make install

H2: Windows NT

Unpack the distribution using a program which understands long file
names (e.g. WinZip).

Within the {{Control Panel}}, go to the {{System}} properties,
select the {{Environment}} tab and edit the variables as follows:

^ Update the PATH to include the {{FILE:bin\dos}} directory
  where SDF is installed.
. For example, if SDF is installed in {{FILE:c:\sdf}}, then you
  need to edit the PATH system variable to include {{FILE:c:\sdf\bin\dos}}.

+ Edit (or add) the PERL5LIB variable to include the Perl
  libraries used by SDF.
. For example, if SDF is installed in {{FILE:c:\sdf}}, then you
  need to edit the PERL5LIB variable to include {{FILE:c:\sdf\perllib}}.

+ Set the SDFBIN variable to point to the directory
  containing SDF's scripts, including the trailing \.
. For example, if SDF is installed in {{FILE:c:\sdf}}, then you
  need to set the SDFBIN variable to {{FILE:c:\sdf\bin\}}.

Test the software. To do this:

^ Start an MS-DOS window.
+ Change directory to the {{FILE:t}} directory within the SDF distribution.
+ Run {{CMD:sdf}} without any arguments to confirm that SDF was
  successfully installed.
+ Run {{CMD:sdftest}}.

If anything fails, {{CMD:sdftest}} will leave the failed {{FILE:.out}}
and {{.log}} files in the relevant directories.


H2: Windows 95

Unpack the distribution using a program which understands long file
names (e.g. WinZip).

Update the PATH to include the {{FILE:bin\dos}} directory
where SDF is installed.
For example, if SDF is installed in {{FILE:c:\sdf}}, then the command is:

>   set PATH=%PATH%;c:\sdf\bin\dos

Edit (or add) the PERL5LIB system variable to include the Perl
libraries used by SDF.
For example, if SDF is installed in {{FILE:c:\sdf}}, then the command is:

>   set PERL5LIB=%PERL5LIB%;c:\sdf\perllib

Set the SDFBIN variable to point to the directory
containing SDF's scripts, including the trailing \.
For example, if SDF is installed in {{FILE:c:\sdf}}, then the command is:

>   set SDFBIN=c:\sdf\bin\

Test the software. To do this:

^ Change directory to the {{FILE:t}} directory within the SDF distribution.
+ Run {{CMD:sdf}} without any arguments to confirm that SDF was
  successfully installed.
+ Run {{CMD:sdftest}}.

If anything fails, {{CMD:sdftest}} will leave the failed {{FILE:.out}}
and {{.log}} files in the relevant directories.

Note: PATH, PERL5LIB and SDFBIN should be set within your
{{FILE:autoexec.bat}} file.


H2: MS-DOS/Windows 3.x

Use {{CMD:pkunzip}} to unpack the distribution. The command is:

>   pkunzip -d sdf.zip

Update the PATH to include the {{FILE:bin\dos}} directory
where SDF is installed.
For example, if SDF is installed in {{FILE:c:\sdf}}, then the command is:

>   set PATH=%PATH%;c:\sdf\bin\dos

Edit (or add) the PERL5LIB system variable to include the Perl
libraries used by SDF.
For example, if SDF is installed in {{FILE:c:\sdf}}, then the command is:

>   set PERL5LIB=%PERL5LIB%;c:\sdf\perllib

Set the SDFBIN variable to point to the directory
containing SDF's scripts, including the trailing \.
For example, if SDF is installed in {{FILE:c:\sdf}}, then the command is:

>   set SDFBIN=c:\sdf\bin\

Test the software. To do this:

^ Change directory to the {{FILE:t}} directory within the SDF distribution.
+ Run {{CMD:sdf}} without any arguments to confirm that SDF was
  successfully installed.
+ Run {{CMD:sdftest}}.

If anything fails, {{CMD:sdftest}} will leave the failed {{FILE:.out}}
and {{.log}} files in the relevant directories.

Note: PATH, PERL5LIB and SDFBIN should be set within your
{{FILE:autoexec.bat}} file.


H2: Installation Notes

H3: Distribution Formats

The {{FILE:tar.gz}} and {{FILE:zip}} distributions should both
contain the same set of files. Therefore, it shouldn't matter
which distribution you obtain provided you have the necessary
software to unpack it.

H3: The sdf.ini File

The {{FILE:sdf.ini}} configuration file
(in the {{FILE:sdf/home}} directory on Perl's library path)
contains several sets of configuration parameters which you may
want to edit after SDF is installed.
Refer to the comments in the file for further details.

H3: Win32 Support

SDF has been briefly tested with:

* Gurusamy Sarathy's 5.004_02 Perl port (August 97), and
* ActiveState's Perl port build 315 (based on 5.003_07).

Both seem to work ok, although running {{CMD:sdftest}} with the
5.004_02 port leaves zero length {{FILE:.out}} and {{FILE:.log}} files
for the tests which work (when they should be deleted).

H3: The SDFBIN Environment Variable

This environment variable is only used by the Windows/DOS wrapper batch files
within {{FILE:bin/dos}} to find the real scripts. Therefore, if you wish to
wrap the scripts in some other way, then there is no need to set this variable.

H3: Macintosh support

Unlike earlier versions, the 2.000 release includes support for
Macintosh filename handling. Installation instructions for the
Macintosh will be made available soon.

H3: Testing Notes

When the {{CMD:sdf}} command is run without arguments,
the output should be something like:

!block verbatim
usage  : sdf [+alias] [-h[help]] [-o[out_ext]] [-l[log_ext]] [-2 format] [-D var
iable,..] [-n split_level] [-f flag,..] [-I include_path,..] [-p prefilter] [-a 
parameters] [-P[plang]] [-N[line_numbers]] [-r report] [-L locale] [-k look] [-s
 style] [-S page_size] [-c config] [-u uses,..] [-H head_level] [-d driver] [-y 
post_filter] [-z post_process,..] [-t target] [-v[verbose]] [-w width] sdf_file 
...
purpose: convert an sdf file to another format
version: 2.000    (SDF 2.000)
!endblock

If this fails, check the following:

^ {{CMD:perl}} 5.003 or later is installed (type {{E:perl -v}} to test)

+ the {{CMD:sdf}} script is on your path and under Unix, is executable.

SDF is supplied with a regression testing system.
To run the tests, change to the {{FILE:t}} directory within
the SDF distribution and execute {{CMD:sdftest}} like this:

>   sdftest

This command can be used at anytime to verify
your installation of SDF.

The {{DOC: SDF Sample Showcase}} contains SDF source code and matching
outputs. If you wish to conduct further tests, these samples can be used.
sdf-2.001/doc/user/in_ovmac.html010064400042570001753000000065630672242745700163530ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Macros





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      2.4. Macros
      

      

      2.4.1. Introduction
      

      A macro is a command which can be embedded within SDF. Macros begin with an exclamation mark (!) as the first non-whitespace character on a line. Some examples are:
      

        !use "delphi"
  !define DOC_AUTHOR "Joe Bloggs"
  !build_title

      

      

      2.4.2. Commonly used macros
      

      Some commonly used macros are given below.
      

      

      

Macro


Description


      

      

init variables


initialise variables


      

      

define variable [expression]


set a variable's value


      

      

build_title


build a title page


      

      

block filter


begin a block of text


      

      

endblock


end a block of text


      

      

include file[; filter]


include another file


      

      

import file[; parameters]


import a figure


      

      


      A complete list of the supported macros and their parameters is given in the SDF Reference manual.
      

      

      2.4.3. Creating new macros
      

      The easiest way to create a new macro is to use the macro and endmacro macros. For example:
      

      !macro MY_MACRO
This text will appear whenever the author calls !MY_MACRO.
!endmacro

      

      Macros can also be implemented by a Perl subroutine which generates the SDF text to be inserted when the macro is called. See the SDF Guru Guide for further details.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_gsex.html010064400042570001753000000112220672242742700161750ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: A simple example





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      1.3. A simple example
      

      

      1.3.1. A sample SDF document
      

      A sample SDF document is shown below:
      

      # Build the title
!define DOC_NAME           "GalaxyBuilder"
!define DOC_TYPE           "Discussion Paper"
!define DOC_AUTHOR         "Joe Bloggs"
!build_title

H1: Introduction

After extensive market research, I believe there is
an excellent opportunity for us to develop software
for the I<galaxy construction industry>. Potential
customers include:

* NASA
* European Community
* China
* Japan.

Note: The proposed name of the software package to be
developed is [[DOC_NAME]]. If you want to suggest a
better name, send email to {{EMAIL:joe@bloggs.com}}.

H2: Software Requirements

The key requirements are:

^ support for the design and simulation of galaxies
  containing up to:
  - 1000 large planets, or
  - 5000 small planets
+ the package needs to be easy to use
+ the package needs to be well documented.

H2: Project Team

Exploding galaxies will be B<very> bad for business,
so we need the best team possible for this project:

!block table
Person          Role
Mary Jones      Project Manager
Hans Blass      Architect
Bill Smith      Software Engineer
!endblock

      

      
Note: This document (called mydoc.sdf) is provided in the doc/paper directory of the SDF distribution.

      

      

      1.3.2. A brief explanation
      

      Comments begin with a # character as the first non-whitespace character on a line.
      

      Macros are embedded commands which begin with a ! as the first non-whitespace character on a line. The define macro is used to set variables. The value of a variable can be embedded in paragraph text  by using the [[...]] syntax.
      

      The DOC_NAME and DOC_TYPE variables are used by the build_title macro which creates:
      

        

      • a cover page (or two) for paper-based outputs

      • a title header for online outputs.
      

      Paragraphs can be tagged in different ways. For the vast majority of SDF documents, the only tags used are:
      

      

      

Tag


Meaning


      

      

H1:


level 1 heading


      

      

H2:


level 2 heading


      

      

*


item in level 1 bulleted list


      

      

-


item in level 2 bulleted list


      

      

^


first item in level 1 ordered list


      

      

+


next item in level 1 ordered list


      

      

>


fixed-width, verbatim text


      

      

Note:


note


      

      


      Phrases can also be tagged in several ways. Any phrase can be tagged using the syntax:
      

        {{XYZ:...}}

      

      where XYZ is the tag. For single, uppercase character tags like I (Italics) and B (Bold), POD-style syntax is also supported:
      

        X<...>

      

      where X is the tag.
      

      Tables can be specified using the table filter, typically in combination with the block and endblock macros. The first row is the headings. Remaining rows are data.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_ovpar.html010064400042570001753000000110230672242744600163560ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Paragraphs





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      2.2. Paragraphs
      

      

      2.2.1. Introduction
      

      Paragraphs have the following format:
      

         line1
   ...
   lineN

      

      Leading and trailing whitespace on lines is generally ignored. Paragraphs are separated by blank lines or:
      

        

      • comment lines - first non-whitespace character is "#"

      • macros - first non-whitespace character is "!".
      

      For normal paragraphs, simply specify the text on one or more lines. For example:
      

         I like products which are simple to use and
   do what I expect. We should encourage engineers
   to design more products with these qualities.

      

      

      2.2.2. Paragraph styles
      

      A paragraph can be given a style using the following syntax:
      

         style":"line1
   ...
   lineN

      

      Tagged paragraphs do not need to be separated by blank lines. style is a sequence of one or more of the following characters:
      

        

      • letters

      • digits

      • underscore character (_).
      

      Whitespace is not permitted before the ":" but is generally ignored immediately after it. The style is optional and defaults to N (for Normal). The text is also optional.
      

      

      2.2.3. Commonly used styles
      

      Commonly used paragraph styles are given below.
      

      

      

Style


Description


      

      

N


normal paragraph (the default)


      

      

H1 .. H6


chapter heading at level 1-6


      

      

A1 .. A6


appendix heading at level 1-6


      

      

P1 .. P6


plain heading at level 1-6


      

      

Note


a single paragraph note


      

      

E


fixed-width (example) text


      

      


      For example:
      

         Note: Life is too short to drink bad wine.

      

      The result is:
      

      
Note: Life is too short to drink bad wine.

      

      

      2.2.4. Special styles
      

      For certain styles, the following syntax is also supported:
      

         special_style line1
   ...
   lineN

      

      The special styles available are:
      

      

      

Style


Description


      

      

. .. ......


paragraph or plain list item at level 1-6


      

      

* .. ******


unordered list at level 1-6


      

      

- .. -----


unordered list at level 2-6


      

      

^ .. ^^^^^^


first entry in an ordered list at level 1-6


      

      

+ .. ++++++


next entry in an ordered list at level 1-6


      

      


      For example:
      

      * fruits:
  - peach
  - banana
* vegetables:
  - potato
  - carrots.

      

      The result is:
      

        

      • fruits:
          

        • peach

        • banana
        

      • vegetables:
          

        • potato

        • carrots.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



d-color: teal}
.changed {background-color: teal}
.changed {background-color: teal}
.changed {background-color: teal}
-->





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | )
Multiple Looks          packaged document-wide presentation styles
#Book Mode
#Indexes                 how to build indexes
#Headers and Footers     how to override the default headers and footers
#Cross References        how to build cross references
#Footnotes & Endnotes    how to build footnotes and endnotes
!endblock

!block topics
Topic
in_libr
in_omgmt
in_cond
in_event
in_custf
in_hyper
in_symb
in_looks
#in_book
#in_index
#in_hdrfr
#in_xref
#in_fnote
!endblock
sdf-2.001/doc/user/in_looks.sdf010064400042570001753000000026170645310126600161650ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Looks

H2: Changing the look

The overall appearance of a paper-based output format can be controlled
by initialising the OPT_LOOK variable on the top line of a document.
For example:

E:   !init OPT_LOOK="infomap"

Alternatively, {{CMD:sdf}}'s -k option can be used. For example:

E:   sdf -2ps -kinfomap mydoc

The -k option overrides the {{MAC:init}} macro setting.

Note: At this time (January 98), multiple looks are currently only
supported for paper documentation generated via FrameMaker.
Multiple look support will hopefully be added to other SDF output
drivers during 1998.

H2: Available looks

The available looks include:

* {{simple}} - the default look, useful for general documentation

* {{fancy}} - a look suitable for user documentation

* {{infomap}} - a look based on Information Mapping[[tm]]

* {{overhead}} - a look suitable for overhead transparencies.

H2: Creating new looks

It is relatively simple to create new looks
by inheriting details from an existing one.

Refer to the {{DOC:SDF Guru Guide}} for details.
sdf-2.001/doc/user/in_hdg.sdf010064400042570001753000000054600635011350400155710ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Headings

H2: Chapter Headings

Headings are specified using the tags H1 .. H6:

* H1 is a chapter heading
* H2 .. H6 are sub headings

The actual presentation of H-style headings (e.g. numbered or unnumbered)
is decided by the target format and document style.

H2: Other Headings

The following heading tags are also supported:

* A1 .. A6 - headings in {{Appendices}}
* P1 .. P6 - headings in {{plain}} sections (e.g. Glossary)

P-style headings are always unnumbered so are commonly used in memos.

In normal documents, it is often unnecessary to use A-style or
P-style tags. The preferred approach is to:

* store each section in a file using H-style headings
* convert the heading style using the {{FILT:appendix}} or {{FILT:plain}}
  filter as the file is being imported.

For example:

E:  !include "budget.sdf"; appendix

Using this approach, sections can easily be reused in different ways
in different documents.

H2: Generating a Table of Contents

A table of contents can be generated from the heading paragraphs.
All types of heading tags (i.e. H, A and P) are included.
The depth of the table of contents is specified by the {{VAR:DOC_TOC}} variable.
For example, to generate a table of contents including headings
up to and including level 4:

E:   doccvt -o -DDOC_TOC=4 mydoc.sdf

Note: For normal documents, the {{MAC:build_title}}
macro defaults this variable to 3.

Individual headings can be excluded from the table of contents
by specifying the {{PATTR:notoc}} attribute. For example:

E:   H3[notoc] Yet Another Heading

See {{SECT:Attributes}} for further details on attribute syntax.

H2: Controlling Page Breaks

Generally speaking, page breaks are controlled by rules associated
with heading tags. For example:

* for documents, memos and faxes, each level 1 heading starts a new page
* for manuals, each level 1 heading starts a new chapter and
  each level 2 heading typically starts a new page.

The {{PATTR:top}} paragraph attribute can be used to position
a paragraph at the top of the next page. For example:

E:  H3[top] Abc Module

Page breaks can also be explicitly specified using the PB tag.
For example:

E:  text on one page.
E:  PB:
E:  H3: Another Section

Note:
[[SDF]] is designed to be a {{logical markup language}}.
While it is sometimes necessary to explicitly specify page breaks
in order to get the layout you want, doing so can reduce the portability
of your document to different styles, page sizes and target formats.

!end_topic
style headings are always unnumbered so are commonly used in memos.

In normal documents, it is often unnecessary to use A-style or
P-style tags. The preferred approach is to:

* store each section in a file sdf-2.001/doc/user/in_tb.sdf010064400042570001753000000007520633602717000154420ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Tables

!block topics
Topic
in_tbov
in_tbsty
in_tbtit
in_tbsiz
in_tbpos
in_tbrow
in_tboth
in_tbss
!endblock
sdf-2.001/doc/user/in_title.html010064400042570001753000000076250672242744000163570ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Building a title





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      1.6. Building a title
      

      Each document style category has a different way of building a title section:
      

        

      • administration styles use the title filter

      • general styles use the build_title macro

      • miscellaneous styles do not have a title.
      

      Refer to Document styles for a summary of the styles available and the category of each style.
      

      

      1.6.1. The title filter
      

      The title filter generates a title block for administration-style documents like memos and faxes. For example:
      

      !block title
Name        Value
Date:       [[DATE:DOC_MODIFIED]]
To:         Joe Bloggs, Sue Brown, Maree Jones
Copy:       David Smith
From:       Neil Armstrong
Subject:    Solar System Information
Ref. No:    XY.002/GUI/96
!endblock

      

      Refer to the documentation on the title filter within the SDF Reference for further details.
      

      

      1.6.2. The build_title macro
      

      The build_title macro tunes the layout and content of the title section for each target format. Typically:
      

        

      • paper-based documents have all the title information formatted on a page (or two)

      • online documents only have the essential title information formatted in a few lines.
      

      By convention, parameters are passed to build_title via predefined variable names. For example:
      

        !define DOC_NAME           "GalaxyBuilder"
  !define DOC_TYPE           "User Guide"
  !define DOC_AUTHOR         "Joe Bloggs"
  !build_title

      

      

      1.6.3. Variables used by build_title
      

      The following variables are commonly defined before build_title is called:
      

      

      

Variable


Description


      

      

DOC_NAME


the title, excluding the type (e.g. SDF)


      

      

DOC_TYPE


the title type (e.g. User Guide)


      

      

DOC_AUTHOR


the author


      

      


      Refer to the documentation on the build_title macro within the SDF Reference for further details.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_title.sdf010064400042570001753000000043700647531506000161600ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Building a title

Each document style category has a different way of building a title section:

* {{administration}} styles use the {{FILT:title}} filter
* {{general}} styles use the {{MAC:build_title}} macro
* {{miscellaneous}} styles do not have a title.

Refer to {{SECT:Document styles}} for a summary of the styles available
and the category of each style.

H2: The title filter

The {{FILT:title}} filter generates a title block for administration-style
documents like memos and faxes. For example:

!block example; pure
!block title
Name        Value
Date:       [[DATE:DOC_MODIFIED]]
To:         Joe Bloggs, Sue Brown, Maree Jones
Copy:       David Smith
From:       Neil Armstrong
Subject:    Solar System Information
Ref. No:    XY.002/GUI/96
!endblock
!endblock

Refer to the documentation on the {{FILT:title}} filter within the
{{DOC:SDF Reference}} for further details.

H2: The build_title macro

The {{MAC:build_title}} macro tunes the layout and content of the
title section for each target format. Typically:

* paper-based documents have all the title information formatted on
  a page (or two)
* online documents only have the essential title information formatted
  in a few lines.

By convention, parameters are passed to {{MAC:build_title}} via
predefined variable names. For example:

!block example
  !define DOC_NAME           "GalaxyBuilder"
  !define DOC_TYPE           "User Guide"
  !define DOC_AUTHOR         "Joe Bloggs"
  !build_title
!endblock

H2: Variables used by build_title

The following variables are commonly defined before {{MAC:build_title}}
is called:

!block table
Variable            Description
DOC_NAME            the title, excluding the type (e.g. SDF)
DOC_TYPE            the title type (e.g. User Guide)
DOC_AUTHOR          the author
!endblock

Refer to the documentation on the {{MAC:build_title}} macro within the
{{DOC:SDF Reference}} for further details.
sdf-2.001/doc/user/ugasdf.sdf010064400042570001753000000014030630476360000156120ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: About This Manual

H2: Purpose

This manual provides an introduction to [[SDF]] - a documentation
system for software developers.

H2: Scope

This manual contains a tutorial-style introduction to the
commonly used features in [[SDF]].

The following documents may also be of interest:

* [[SDF_DOC_WP]]
* [[SDF_DOC_QR]]
* [[SDF_DOC_REF]]
* [[SDF_DOC_GG]].

H2: Amendments

!SDF_AMENDMENTS
sdf-2.001/doc/user/ugasdf.html010064400042570001753000000047060672242741200160150ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: About This Manual





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      About This Manual
      

      Purpose
      

      This manual provides an introduction to SDF - a documentation system for software developers.
      

      Scope
      

      This manual contains a tutorial-style introduction to the commonly used features in SDF.
      

      The following documents may also be of interest:
      


      Amendments
      

      Suggested enhancements and corrections to SDF and its documentation can be forwarded to sdf-bugs@mincom.com.
      

      
Note: This manual documents version 2.001 of SDF.

      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_tbov.html010064400042570001753000000101530672242753100161770ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Overview





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      5.1. Overview
      

      

      5.1.1. Features
      

      SDF supports a range of features related to tables including:
      

        

      • tables are defined in a simple format which is:
          

        • easy to write and read

        • upwardly-compatible with the CSV (comma-separated value) format exported by most databases and spreadsheets

        • upwardly-compatible with the fixed-width format generated by most reporting tools.
        

      • column widths can be dynamically sized or explicitly set

      • heading, footing and group rows can be specified

      • table alignment and positioning can be controlled

      • cells support custom alignment, shading, ruling and colours.
      

      In fact, SDF can do lots of very clever things with tables including spreadsheet-like calculations on cells and ranges of cells!
      

      

      5.1.2. Creating a Table
      

      Tables are usually defined via the table filter. For example:
      

        !block table
  Fruit      Comments
  Tropical:
  mango      a fruit-bat favorite
  banana     great for smoothies
  Other:
  Tomato     often matched with basil
  !endblock

      

      or:
      

        !include "fruits.tbl"; table

      

      

      5.1.3. TBL Format
      

      The table filter expects a table definition in a simple text format (called TBL) where:
      

        

      1. the first (non-comment) line is the header record

      2. remaining lines are data records.
      

      The header record specifies the field names and the layout. Fields can be placed in fixed-width columns or delimited by a special character. Fixed-width format (as shown above) is usually used.
      

      
Note: The width of columns in the "input" has no bearing on the width of columns in the output. To change the output width, refer to Sizing Columns.

      

      See the SDF Reference for further details on TBL format.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_tbtit.html010064400042570001753000000073710672242754000163630ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Adding Table Titles





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      5.3. Adding Table Titles
      

      

      5.3.1. Adding a Title to a Table
      

      To add a title, use the title attribute. For example:
      

      !block table; title="Phone numbers of good friends"
Name   Phone
Bill   123 4567
Joe    789 1234
Mary   584 3333
!endblock

      

      The output is:
      

      
Phone numbers of good friends

      

Name


Phone


      

      

Bill


123 4567


      

      

Joe


789 1234


      

      

Mary


584 3333


      

      


      

      5.3.2. Adding a Title to a Psuedo Table
      

      Occasionally, it is useful to title a table by hand. To do this, use the TT (Table Title) paragraph style. For example:
      

         TT: My Boring Looking Table
   !include "my_table.txt"; example; wide

      

      

      5.3.3. Generating a List of Tables
      

      A list of tables can be generated from the table titles. To do this, set the DOC_LOT variable. For example:
      

      # Build the title
!define DOC_NAME "World Peace in 60 Days"
!define DOC_LOT
!build_title

      

      This will generate a list of tables after the table of contents.
      

      

      5.3.4. Changing the List of Tables Title
      

      The default title for the list of tables is "List of Tables". To change this, set the DOC_LOT_TITLE. For example:
      

      !define DOC_LOT_TITLE "Tables"

      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_ovexp.sdf010064400042570001753000000031600635673221600162000ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Expressions


H2: Introduction

Expressions are used in several places within [[SDF]] including:

* attribute values
* macro argument values
* filter parameter values
* evaluation within paragraph text.

The value of an expression can be placed into a paragraph
by delimiting it with the special symbols E<2[> and E<2]>.
For example:

V:   The current file is [[DOC_FILE]].


H2: Types of expressions

An expression is either:

* an [[SDF]] variable name (e.g. DOC_AUTHOR)
* a [[Perl]] expression.

If an expression is a single word, it is the value of
a variable. Otherwise, it is evaluated as a Perl expression.
A Perl expression is typically one of the following:

* a numeric literal (e.g. {{E:213}})
* a string literal (e.g. {{E:"User Guide"}})
* a subroutine call (e.g. {{E:length("User Guide")}}).


H2: Accessing variables within Perl expressions

Within a [[Perl]] expression, [[SDF]] variables are available
via the {{var}} associative array. The syntax used by [[Perl]]
for accessing a value within an associative array is:

E:  "$" array_name "{" string_index "}"

Some examples are:

^ get the length of the DOC_AUTHOR variable:

E:      length($var{'DOC_AUTHOR'})

+ concatenate the document name and type:

E:      "$var{'DOC_NAME'} $var{'DOC_TYPE'}"
sdf-2.001/doc/user/in_tbsty.sdf010064400042570001753000000031010635011350400161620ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Table Styles

H2: The style Attribute

The look of a table is controlled by the {{style}} attribute.
For example:

E:!block table; style="rows"
E:Name   Phone
E:Bill   123 4567
E:Joe    789 1234
E:Mary   584 3333
E:!endblock

The result is:

!block table; style="rows"
Name    Phone
Bill    123 4567
Joe     789 1234
Mary    584 3333
!endblock

The other styles available are shown below.

H2: columns

!block table; style="columns"
Name    Phone
Bill    123 4567
Joe     789 1234
Mary    584 3333
!endblock

H2: plain

!block table; style="plain"
Name    Phone
Bill    123 4567
Joe     789 1234
Mary    584 3333
!endblock

H2: grid

!block table; style="grid"
Name    Phone
Bill    123 4567
Joe     789 1234
Mary    584 3333
!endblock

H2: shade

!block table; style="shade"
Name    Phone
Bill    123 4567
Joe     789 1234
Mary    584 3333
!endblock

H2: Changing the Default Table Style

The default style is {{columns}}. This can be changed via the
{{VAR:DEFAULT_TABLE_STYLE}} variable. For example:

E:  !define DEFAULT_TABLE_STYLE "grid"
E:  # the default table style is now grid ...

H2: Creating New Table Styles

New table styles can be defined.
See {{Extending SDF}} in the {{DOC:SDF Guru Guide}} for details.
sdf-2.001/doc/user/in_gsgen.html010064400042570001753000000104720672242743200163340ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Generating outputs





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      1.4. Generating outputs
      

      

      1.4.1. Overview
      

      The sdf command is used to convert SDF to other formats. The general syntax is:
      

         sdf [options] file ...

      

      If an extension is not given (and a file is not found with that name), an extension of sdf is assumed.
      

      

      1.4.2. Generating HTML
      

      To convert mydoc.sdf to HTML, the command is:
      

         sdf -2html mydoc

      

      This creates a file called mydoc.html.
      

      

      1.4.3. Generating a set of HTML topics
      

      To convert mydoc.sdf to a set of HTML topics, the command is:
      

         sdf -2topics mydoc

      

      This creates the following files:
      

        

      • mydoc.html - the table of contents

      • mydoc_1.html - the first topic

      • mydoc_2.html - the second topic.
      

      

      1.4.4. Generating PostScript on Unix
      

      To convert mydoc.sdf to PostScript on Unix, the command is:
      

         sdf -2ps mydoc

      

      This creates a file called mydoc.ps by:
      

        

      1. Generating a MIF (Maker Interchange Format) file called mydoc.out.

      2. Using the fmbatch program to convert this file to mydoc.out.ps.

      3. Renaming mydoc.out.ps to mydoc.ps.

      4. Deleting mydoc.out.
      

      

      1.4.5. Generating PostScript on Windows
      

      To convert mydoc.sdf to PostScript on Windows, the command is:
      

         sdf -2mif mydoc

      

      This creates a file called mydoc.mif which can be opened in FrameMaker and printed to a PostScript file.
      

      

      1.4.6. Generating PDF
      

      To generate a PDF file, the steps are:
      

        

      1. Generate a PostScript document (see above)

      2. Open the PostScript document using Adobe Distiller.

      3. Generate the PDF file.
      

      
Note: The PostScript document generated by SDF includes the information needed by the PDF distiller to generate a table of contents.

      

      

      1.4.7. Generating plain text
      

      To convert mydoc.sdf to plain text, the command is:
      

         sdf -2txt mydoc

      

      This creates a file called mydoc.txt.
      

      

      1.4.8. Generating Windows help
      

      To convert mydoc.sdf to Windows help, the command is:
      

         sdf -2hlp mydoc

      

      This creates the following files:
      

        

      • mydoc.hpj - a help project file

      • mydoc.rtf - an RTF document with embedded help codes
      

      These need to be compiled using a help compiler (e.g. hcp.exe). For example:
      

         hcp mydoc

      

      This creates a file called mydoc.hlp (provided no errors are encountered).
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_style.sdf010064400042570001753000000031740647531477400162130ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Document styles

H2: Changing the style

The general style (or type) of a document can be changed
by initialising the OPT_STYLE variable on the top line of a document.
For example:

E:   !init OPT_STYLE="manual"

Alternatively, {{CMD:sdf}}'s -s option can be used. For example:

E:   sdf -2ps -smanual mydoc

Note: The -s option overrides the {{MAC:init}} macro setting.

H2: Available styles

The available document styles, grouped by {{style category}}, are:

!block table; groups
Style           Purpose
General:
document        a normal document
manual          a manual
paper           a technical paper
Administration:
admin           generic administration document
fax             a fascimile
memo            a memorandum
newslttr        a newsletter
minutes         minutes of a meeting
Miscellaneous:
listing         a source code listing
!endblock

H2: Building a title

Each style category has a different way of building a title section:

* {{general}} styles use the {{MAC:build_title}} macro
* {{administration}} styles use the {{FILT:title}} filter
* {{miscellaneous}} styles do not have a title.

H2: Creating new styles

It is relatively simple to create new styles
by inheriting details from an existing one.

Refer to the {{DOC:SDF Guru Guide}} for details.
sdf-2.001/doc/user/in_fgov.sdf010064400042570001753000000057320635011350400157720ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Overview

H2: Features

SDF supports a range of features related to figures:

* figures can be imported in a variety of formats including:
  - EPS - Encapsulated PostScript
  - WMF - Windows MetaFile
  - MIF - Maker Interchange Format
  - GIF - Graphics Interchange Format
  - JPEG - JPEG File Interchange Format
  - PNG - Portable Network Graphic Format
  - BMP - Windows Bitmap Format

* logos can be easily added to title pages and online headers
* figure positioning can be controlled
* text can be wrapped around figures.

H2: Importing Figures Into SDF Documents

The {{MAC:import}} macro is usually used to import a figure.
The syntax is:

E:  !import "filename" {{1:[; parameters]}}

For example:

E:  !import "sdfarch"

H2: Importing a Figure Into Paragraph Text

To import a figure into the middle of a paragraph,
the IMPORT phrase style is used.
The syntax is:

!block example; pure
    {{IMPORT:filename}}, or
    {{IMPORT[parameters]filename}}
!endblock

For example:

!block example; pure
Please visit our {{IMPORT:new}} web site!
!endblock

H2: Figure Extensions

It is generally best {{not}} to specify an extension for the filename
containing the figure, as SDF will then use the best format it can find.
The search rules are:

!block table
When_generating     The_search_order_is
PostScript          epsi, eps, wmf, mif, gif
HTML                jpeg, jpg, png, gif
Windows Help        bmp
!endblock

So a GIF file is all that is necessary if you are generating
PostScript and HTML. However, if SDF finds an EPS file when it
is generating PostScript, it will use that instead.

H2: Adding Logos

The default implementations of the {{MAC:build_title}} macro,
{{FILT:title}} filter and HTML header macros provide an easy
way to add a company logo: by defining variables.
The variables are:

!block table
Variable            Description
DOC_LOGO            the default logo
DOC_TITLE_LOGO      used in the title of a PostScript document
DOC_ADMIN_LOGO      used in the title of a PostScript admin. document
DOC_HTML_LOGO       used in the title of a HTML document
DOC_TOPIC_LOGO      used in the header of a HTML topic
DOC_MANUAL_LOGO     used on the front cover of a PostScript manual
DOC_COMPONENT_LOGO  used on the cover of each chapter in a PostScript manual
!endblock

In each case, the value of the variable is the filename
containing the figure.

If a given logo variable is not set, DOC_LOGO is used if it is set.
Therefore, a company logo can be added to most SDF documents by
simply defining DOC_LOGO is a configuration module (or library)
which is loaded into every SDF document via the {{MAC:use}} (or
{{MAC:inherit}}) macro.
sdf-2.001/doc/user/in_tboth.html010064400042570001753000000322300672242756600163550ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Other Table Goodies





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      5.7. Other Table Goodies
      

      

      5.7.1. Column alignment
      

      The colaligns parameter of the table filter can be used to control the alignment of text within columns of a table. For example:
      

      !block  table; colaligns="LCCR"
Name    Column2             Column3     Column4
A       B                   C           1.0
X       Hello dear world    Y           10.2
!endblock

      

      The output is:
      

      

      

Name


Column2


Column3


Column4


      

      

A


B


C


1.0


      

      

X


Hello dear world


Y


10.2


      

      


      The value of colaligns is usually a sequence of the letters L, C and R (which mean what one would expect). If you prefer, a comma-separated list of the values Left, Center and Right can be specified. For example:
      

      !block  table; colaligns="Left,Center,Center,Right"
Name    Column2             Column3     Column4
A       B                   C           1.0
X       Hello dear world    Y           10.2
!endblock

      

      Likewise, the colvaligns parameter can be used to control the vertical alignment of text within columns of a table. The value is either:
      

        

      • a comma-separated list of the values Top, Middle, Bottom and Baseline, or

      • a sequence of the letters T, M, B (Bottom) and L (baseLine).
      

      Baseline alignment means that the base of the first line of the text in each cell is aligned (HTML only).
      

      
Note: For a variety of reasons, the default vertical alignment for cells in a HTML table is Middle, while the default vertical alignment for tables in most other formats is Top. As most tables contain rows which fit on one line, this inconsistency is not usually a problem. However, if you want consistent vertical alignment for a complex table across all formats, you need to use the colvaligns parameter to override the default behaviour.

      

      

      5.7.2. Column tagging
      

      In a similar way, columns can be tagged with a phrase style by using the coltags attribute. For example:
      

      !block table; coltags="B,EMAIL"
Purpose         Email
Information     sdf-users@mincom.com
Bug reporting   sdf-users@mincom.com
!endblock

      

      The result is:
      

      

      

Purpose


Email


      

      

Information


sdf-users@mincom.com


      

      

Bug reporting


sdf-users@mincom.com


      

      


      

      5.7.3. Table filtering and sorting
      

      Tables can be filtered and sorted by using the where and sort attributes of the table filter. These attributes are also supported by the class filters (e.g. terms, references). In either case, filtering is done before sorting.
      

      The where attribute takes an expression which is evaluated for each record. Special symbols available are:
      

      

      

Symbol


Meaning


      

      

$_


the current record


      

      

$o{"xyz"}


the value of column xyz


      

      

$var{"abc"}


the value of variable abc


      

      


      For example:
      

       !define MODULE_CODE "XYZ"
 ...
 !include "../mydata.tbl"; table; \
   where='$o{"Code"} =~ /$var{"MODULE_CODE"}/'

      

      sort takes a comma-separated list of column names to sort on. If no columns are specified, the data is sorted using all columns in the order in which they appear. All sorting is done alphabetically - numeric sorting is not supported.
      

      

      5.7.4. Deleting and selecting columns
      

      The table filter supports the following parameters for changing the columns actually displayed:
      

        

      • delete - a comma-separated list of columns to delete

      • select - the comma-separated list of columns to display.
      

      These parameters are often used in combination with the where parameter. For example:
      

        # Display the open bugs, sorted by priority
  H1: Open Defects
  !include 'mybugs.tbl'; table; \
           where='$o{"Status"} eq "Open"'; \
           sort='Priority'; \
           delete='Status'

      

      If both delete and select are specified, select has precedence.
      

      

      5.7.5. Macros inside tables
      

      Macros can be used inside tables. In particular:
      

        

      • rows can now be conditionally included or excluded

      • rows can be marked as changed.
      

      For example:
      

      !block table
Code    Description
BTW     By the way
!block changed
RTFM    Read the (fine) manual
!endblock
!if ALL_TERMS
SOS     Save our souls
!endif
!endblock

      

      

      5.7.6. Landscape tables
      

      Landscape tables are supported via the landscape parameter of the table filter. The value is the height allocated to the area in which the table is placed. If a unit is not specified, the value is assumed to be a percentage of the text column height. For convenience, a value of 1 implies a full page table. Some examples are given below.
      

      

      

Value


Meaning


      

      

landscape="50pt"


height allocated to table is 50 points


      

      

landscape="50%"


half page table


      

      

landscape=50


half page table (% is the default units)


      

      

landscape=1


full page table (1 implies 100%)


      

      

landscape


full page table (syntactic shorthand for above)


      

      


      
Note: This feature is currently use at your own risk. In particular, long tables and table titles confuse it badly. Furthermore, the align and placement parameters are effectively ignored for landscape tables.

      

      

      5.7.7. Cell attributes
      

      Cells within a table can now be given attributes by preceding the cell value with a semicolon-separated list of name-value pairs enclosed in square brackets. For example:
      

      !block  table; colaligns="LCCR"
Name    Column2             Column3     Column4
A       [align=Left]B       C           [bgcolor=Green]1.0
X       Hello dear world    Y           [bgcolor=Red]10.2
!endblock

      

      The output is:
      

      

      

Name


Column2


Column3


Column4


      

      

A


B


C


1.0


      

      

X


Hello dear world


Y


10.2


      

      


      The cell attributes supported are given below.
      

      

      

Name


Value


      

      

General:


 


      

      

align


horizontal alignment (Left, Center, Right)


      

      

valign


vertical alignment (Top, Middle, Bottom, Baseline)


      

      

cols


the number of columns this cell spans (default is 1)


      

      

rows


the number of rows this cell spans (default is 1)


      

      

bgcolor


background colour of cell (see below)


      

      

PS only:


 


      

      

fill


background colour fill percentage


      

      

truling


ruling setting for top of cell


      

      

bruling


ruling setting for bottom of cell


      

      

lruling


ruling setting for left of cell


      

      

rruling


ruling setting for right of cell


      

      

angle


angle of text (0, 90, 180, 270)


      

      

HTML only:


 


      

      

nowrap


disable word wrap for this cell


      

      

Special:


 


      

      

sdf


treat the cell text as SDF (rather than as phrase text)


      

      

tag


phrase tag to apply to cell text


      

      

paratag


paragraph style to apply to cell text


      

      


      For PS (i.e. MIF) generation, the supported colour values are Black, White, Red, Green, Blue, Yellow, Cyan and Magenta. If a different colour is specified, it is ignored. The supported fill values are 100, 90, 70, 50, 30, 10 and 3. If a fill value is not specified, 100% fill is used.
      

      For HTML generation, any of the HTML colours names (including those supported for PS generation) or the "#rrggbb" form can be used.
      

      The permitted ruling values are Vthin, Thin, Medium, Thick and Double.
      

      The sdf, tag and paratag attributes control the way in which the cell text is converted to SDF:
      

        

      1. If sdf is set, the cell text is already SDF.

      2. Otherwise if tag is set, the SDF paragraph is paratag:{{tag:text}}.

      3. Otherwise, the paragraph is paratag:text.
      

      tag is usually set via the tags or groups parameters of the table filter.
      

      
Note: paratag is not yet implemented.

      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



xample:
      

      !block  table; colaligns="Left,Center,Center,Right"
Name    Column2             Column3     Column4
A       B                   C           1.0
X       Hello dear world    Y           10.2
!endblock

      

      Likewise, the colvaligns parameter can be used to control the vertical alignment of text within columns of a tablesdf-2.001/doc/user/in_tbpos.html010064400042570001753000000076370672242755100163730ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Positioning Tables





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      5.5. Positioning Tables
      

      

      5.5.1. Horizontal Alignment
      

      The horizontal alignment of a table can be controlled by setting the align parameter of the table filter. The permitted values are:
      

      

      

Value


Meaning


      

      

Left


left-align the table


      

      

Center


center the table


      

      

Right


right-align the table


      

      

Inner


align the table with the inner margin


      

      

Outer


align the table with the outer margin


      

      


      
Note: The wide parameter changes the left indent of a table to include the sidehead of a page. Therefore, the wide parameter will impact the horizontal positioning of any table which is not right-aligned.

      

      

      5.5.2. Vertical Positioning
      

      The vertical placement of a table can be controlled by setting the placement parameter of the table filter. The permitted values are:
      

      

      

Value


Meaning


      

      

Float


next column if necessary


      

      

Pagetop


top of the next page


      

      

Columntop


top of the next column


      

      

Lefttop


top of the next left-hand page


      

      

Righttop


top of the next right-hand page


      

      


      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_ovflt.html010064400042570001753000000103760672242746600163750ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Filters





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      2.6. Filters
      

      

      2.6.1. Introduction
      

      A filter controls how a block of text is interpreted. The text is usually delimited by block and endblock macros.
      

      For example, tables are usually defined via the table filter:
      

      !block table
Option  Description
-h      display help
-o      specify the output extension
!endblock

      

      The result is:
      

      

      

Option


Description


      

      

-h


display help


      

      

-o


specify the output extension


      

      


      

      2.6.2. Commonly used filters
      

      Some of the commonly used filters are:
      

      

      

Filter


Description


      

      

table


the lines are a table in SDF's TBL format


      

      

example


the lines are example paragraphs


      

      

title


used to build a title block for memos, faxes, etc.


      

      

topics


include files as sub-topics


      

      

appendix


replace H1 styles with A1, etc.


      

      

plain


replace H1 styles with P1, etc.


      

      


      A complete list of the supported filters and their parameters is given in the SDF Reference manual.
      

      

      2.6.3. Other macros supporting filters
      

      Other macros also support filters. These include:
      

        

      • include - include text from another file

      • execute - include the output of a system command.
      

      For example, the following line includes another SDF file and formats it as an appendix:
      

         !include "tips.sdf"; appendix

      

      
Note: The appendix and plain filters enable authors to construct topics without needing to worry about how those topics will be used, e.g. a topic may be a chapter in one document and an appendix in another!

      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_looks.html010064400042570001753000000077170672242762700163760ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Looks





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      6.9. Looks
      

      

      6.9.1. Changing the look
      

      The overall appearance of a paper-based output format can be controlled by initialising the OPT_LOOK variable on the top line of a document. For example:
      

         !init OPT_LOOK="infomap"

      

      Alternatively, sdf's -k option can be used. For example:
      

         sdf -2ps -kinfomap mydoc

      

      The -k option overrides the init macro setting.
      

      
Note: At this time (January 98), multiple looks are currently only supported for paper documentation generated via FrameMaker. Multiple look support will hopefully be added to other SDF output drivers during 1998.

      

      

      6.9.2. Available looks
      

      The available looks include:
      

        

      • simple - the default look, useful for general documentation

      • fancy - a look suitable for user documentation

      • infomap - a look based on Information Mapping™ 

      • overhead - a look suitable for overhead transparencies.
      

      

      6.9.3. Creating new looks
      

      It is relatively simple to create new looks by inheriting details from an existing one.
      

      Refer to the SDF Guru Guide for details.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_tboth.sdf010064400042570001753000000171240645741124000161550ustar00iancmtr00000400000236H1: Other Table Goodies

H2: Column alignment

The {{colaligns}} parameter of the {{FILT:table}} filter can be used
to control the alignment of text within columns of a table.
For example:

!block example
!block  table; colaligns="LCCR"
Name    Column2             Column3     Column4
A       B                   C           1.0
X       Hello dear world    Y           10.2
!endblock
!endblock

The output is:

!block  table; colaligns="LCCR"
Name    Column2             Column3     Column4
A       B                   C           1.0
X       Hello dear world    Y           10.2
!endblock

The value of {{colaligns}} is usually a sequence of the letters
{{L}}, {{C}} and {{R}} (which mean what one would expect).
If you prefer, a comma-separated list of the values {{Left}}, {{Center}}
and {{Right}} can be specified. For example:

!block example
!block  table; colaligns="Left,Center,Center,Right"
Name    Column2             Column3     Column4
A       B                   C           1.0
X       Hello dear world    Y           10.2
!endblock
!endblock

Likewise, the {{colvaligns}} parameter can be used
to control the vertical alignment of text within columns of a table.
The value is either:

* a comma-separated list of the values {{Top}}, {{Middle}}, {{Bottom}}
  and {{Baseline}}, or
* a sequence of the letters T, M, B (Bottom) and L (baseLine).

Baseline alignment means that the base of the first line of the text
in each cell is aligned (HTML only).

Note: For a variety of reasons, the default vertical alignment for
cells in a HTML table is {{Middle}}, while the default vertical
alignment for tables in most other formats is {{Top}}. As most tables
contain rows which fit on one line, this inconsistency is not usually
a problem. However, if you want consistent vertical alignment for a
complex table across all formats, you need to use the {{colvaligns}}
parameter to override the default behaviour.

H2: Column tagging

In a similar way, columns can be tagged with a phrase style by
using the {{coltags}} attribute. For example:

!block example
!block table; coltags="B,EMAIL"
Purpose         Email
Information     sdf-users@mincom.com
Bug reporting   sdf-users@mincom.com
!endblock
!endblock

The result is:

!block table; coltags="B,EMAIL"
Purpose         Email
Information     sdf-users@mincom.com
Bug reporting   sdf-users@mincom.com
!endblock


H2: Table filtering and sorting

Tables can be filtered and sorted by using the {{where}}
and {{sort}} attributes of the {{FILT:table}} filter.
These attributes are also supported by the class filters (e.g.
terms, references).
In either case, filtering is done before sorting.

The {{where}} attribute takes an expression which is evaluated
for each record. Special symbols available are:

!block table
Symbol      Meaning
$_          the current record
$o{"xyz"}   the value of column xyz
$var{"abc"} the value of variable abc
!endblock

For example:

E: !define MODULE_CODE "XYZ"
E: ...
E: !include "../mydata.tbl"; table; \
E:   where='$o{"Code"} =~ /$var{"MODULE_CODE"}/'

{{sort}} takes a comma-separated list of column names to sort on.
If no columns are specified, the data is sorted using
all columns in the order in which they appear. All sorting
is done alphabetically - numeric sorting is not supported.

H2: Deleting and selecting columns

The {{FILT:table}} filter supports the following parameters for
changing the columns actually displayed:

* {{delete}} - a comma-separated list of columns to delete
* {{select}} - the comma-separated list of columns to display.

These parameters are often used in combination with the {{where}}
parameter. For example:

!block verbatim
  # Display the open bugs, sorted by priority
  H1: Open Defects
  !include 'mybugs.tbl'; table; \
           where='$o{"Status"} eq "Open"'; \
           sort='Priority'; \
           delete='Status'
!endblock

If both {{delete}} and {{select}} are specified, {{select}} has precedence.

H2: Macros inside tables

Macros can be used inside tables. In particular:

* rows can now be conditionally included or excluded
* rows can be marked as changed.

For example:

!block verbatim
!block table
Code    Description
BTW     By the way
!block changed
RTFM    Read the (fine) manual
!endblock
!if ALL_TERMS
SOS     Save our souls
!endif
!endblock
!endblock

H2: Landscape tables

Landscape tables are supported via the {{landscape}} parameter of
the {{FILT:table}} filter. The value is the height allocated to
the area in which the table is placed. If a unit is not specified,
the value is assumed to be a percentage of the text column height.
For convenience, a value of 1 implies a full page table.
Some examples are given below.

!block table
Value               Meaning
landscape="50pt"    height allocated to table is 50 points
landscape="50%"     half page table
landscape=50        half page table (% is the default units)
landscape=1         full page table (1 implies 100%)
landscape           full page table (syntactic shorthand for above)
!endblock

Note: This feature is currently {{B:use at your own risk}}.
In particular, long tables and table titles confuse it badly.
Furthermore, the {{align}} and {{placement}} parameters are
effectively ignored for landscape tables.


H2: Cell attributes

Cells within a table can now be given attributes by preceding the
cell value with a semicolon-separated list of name-value pairs
enclosed in square brackets. For example:

!block example
!block  table; colaligns="LCCR"
Name    Column2             Column3     Column4
A       [align=Left]B       C           [bgcolor=Green]1.0
X       Hello dear world    Y           [bgcolor=Red]10.2
!endblock
!endblock

The output is:

!block  table; colaligns="LCCR"
Name    Column2             Column3     Column4
A       [align=Left]B       C           [bgcolor=Green]1.0
X       Hello dear world    Y           [bgcolor=Red]10.2
!endblock

The cell attributes supported are given below.

!block table; groups
Name        Value
General:
align       horizontal alignment (Left, Center, Right)
valign      vertical alignment (Top, Middle, Bottom, Baseline)
cols        the number of columns this cell spans (default is 1)
rows        the number of rows this cell spans (default is 1)
bgcolor     background colour of cell (see below)
PS only:
fill        background colour fill percentage
truling     ruling setting for top of cell
bruling     ruling setting for bottom of cell
lruling     ruling setting for left of cell
rruling     ruling setting for right of cell
angle       angle of text (0, 90, 180, 270)
HTML only:
nowrap      disable word wrap for this cell
Special:
sdf         treat the cell text as SDF (rather than as phrase text)
tag         phrase tag to apply to cell text
paratag     paragraph style to apply to cell text
!endblock

For PS (i.e. MIF) generation, the supported colour values are
{{Black}}, {{White}}, {{Red}}, {{Green}},
{{Blue}}, {{Yellow}}, {{Cyan}} and {{Magenta}}.
If a different colour is specified, it is ignored.
The supported fill values are 100, 90, 70, 50, 30, 10 and 3.
If a fill value is not specified, 100% fill is used.

For HTML generation, any of the HTML colours names
(including those supported for PS generation) or the "#rrggbb" form
can be used.

The permitted ruling values are {{Vthin}}, {{Thin}}, {{Medium}},
{{Thick}} and {{Double}}.

The {{sdf}}, {{tag}} and {{paratag}} attributes control the way in which the
cell text is converted to SDF:

^ If {{sdf}} is set, the cell text is already SDF.
+ Otherwise if {{tag}} is set, the SDF paragraph is paratag:E<2{>tag:textE<2}>.
+ Otherwise, the paragraph is paratag:text.

{{tag}} is usually set via the {{tags}} or {{groups}} parameters
of the {{FILT:table}} filter.

Note: {{paratag}} is not yet implemented.
sdf-2.001/doc/user/in_ovatt.sdf010064400042570001753000000031360635011350400161620ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Attributes

H2: Introduction

Attributes can be used to specify custom formatting, hypertext
targets and jumps, indexing information, etc.
For example:

E:  Note[label='Important: ';size="16pt"]
E:  Life is too short to drink bad wine.

The result is:

Note[label='Important: ';size="16pt"]
Life is too short to drink bad wine.


H2: Syntax

Paragraphs and phrases can be given attributes via
the syntax below:

E:  style"["attributes"]" text

where the syntax of {{attributes}} is:

E:  name1["="expression1]";" name2["="expression2] ...

If an attribute name is given without a value, the default value is 1.
Like style names, attribute names are:

* sequences of letters, digits and "_"
* case-sensitive.


H2: Commonly used attributes

Some commonly used attributes are given below.

!block table; groups
Name            Purpose
Paragraphs:
label           prefix label (e.g. Note:)
notoc           take this heading out of the table of contents
Phrases:
id              hypertext target tag
jump            URL (Uniform Resource Locator) to jump to
!endblock

#Unlike style names, attribute names can be prefixed by a target name.
#These target-specific attributes (e.g. mif.FontSize above) permit
#tuning of the output for different targets.
sdf-2.001/doc/user/in_tbrow.html010064400042570001753000000114000672242755400163630ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Creating Heading, Footing and Group Rows





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      5.6. Creating Heading, Footing and Group Rows
      

      

      5.6.1. Overview
      

      The table filter now supports the following attributes:
      

        

      • headings - the number of heading rows at the top of the table

      • footings - the number of footing rows at the end of the table

      • groups - look for group rows in the table.
      

      

      5.6.2. Heading Rows
      

      If the headings attribute is not defined, then the column headings are generated using the column names given on the parsing line. For example, the column headings in the table below will be Name and Age:
      

      !block table
Name    Age
Bill    42
!endblock

      

      Alternatively, if the headings attribute is defined, then that number of data rows are used as the column headings, i.e. the parsing line is not used to build the column headings. For example, the column headings in the table below will be "Title" and Age (remembering that a filter attribute is implicitly given the value 1 is no value is supplied).
      

      !block table; headings
A       B
"Title" Age
Bill    42
Sally   23
!endblock

      

      Likewise, the column headings below will be Preferred Title and Likely Age with each heading taking 2 rows.
      

      !block table; headings=2
A           B
Preferred   Likely
Title       Age
Bill        42
Sally       23
!endblock

      

      

      5.6.3. Footing Rows
      

      These work exactly the same as table headings, except that no footings are generated by default.
      

      

      5.6.4. Group Rows
      

      If the groups parameter is specified, SDF assumes that rows that end in : are group rows. For example:
      

      !block table; groups
Fruit      Comments
Tropical:
mango      a fruit-bat favorite
banana     great for smoothies
Other:
Tomato     often matched with basil
!endblock

      

      The result is:
      

      

      

Fruit


Comments


      

      

Tropical:


 


      

      

mango


a fruit-bat favorite


      

      

banana


great for smoothies


      

      

Other:


 


      

      

Tomato


often matched with basil


      

      


      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_hdrfr.sdf010064400042570001753000000041270622022215600161330ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Headers and Footers

Note: The documentation below explains how this feature is
implemented in SDF 2.000. A better solution might be implemented
in SDF 2.001. Therefore, avoid using the stuff below if you can.

The document templates supplied with [[SDF]] have headers and
footers containing [[FrameMaker]] variables. As such, you can control most
of the information displayed in the headers and footers by setting
{{host variables}}. See the configuration files for examples.

The variables used in the {{plain}} templates are summarised below.

!block table; groups
Variable        Description
front page:
FooterA         footer left
FooterB         footer centre
FooterC         footer right
normal pages:
Header1         header left - line 1
Header2         header left - line 2
Header3         header centre - line 1
Header4         header centre - line 2
Running_H_F_1   header right - line 1
Running_H_F_2   header right - line 2
Running_H_F_3   footer left - line 1
Running_H_F_4   footer left - line 2
Footer1         footer centre - line 1
Footer2         footer centre - line 2
Footer3         footer right - line 2
!endblock

!if MINCOM_ONLY
The variables used in the {{qsd*}}
templates are summarised below.

!block table
Variable        Description
#Header1         header inside - line 1
#Header2         header inside - line 2
#Header3         header centre - line 1
#Header4         header centre - line 2
Running_H_F_1   header outside - line 1
Running_H_F_2   header outside - line 2
Running_H_F_3   footer inside - line 1
Running_H_F_4   page number prefix
Footer1         footer inside - line 2
Footer2         footer inside - line 3
Footer3         footer inside - line 4
Footer4         footer centre
!endblock
!endif

!end_topic
sdf-2.001/doc/user/credits.sdf010064400042570001753000000027070633601452200160030ustar00iancmtr00000400000236#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Credits

SDF has taken several years to put together and would not
exist in its current form without the contributions below.

Firstly, thanks to my former {{Leeds and Northrup Australia}}
colleagues, particularly Tom Beale, Craig Gibbings and Greg Birnie,
for inspiring my initial interest in {{literate programming}}.

Secondly, thanks to Tim Hudson ({{EMAIL:tjh@cryptsoft.com}}) for
being SDF's biggest fan. Tim has assisted in design, fixed bugs, added
features, "sold" SDF to many of its current user base and generally
hassled me to package SDF into its current form. Thanks also
to Chris Moran ({{EMAIL:chris.moran@mincom.com}}) for maintaining
the {{[jump=SDF_WWW]SDF Home Page}}, assisting in design, etc.
Many other [[Mincom]] colleagues have assisted with SDF,
particularly Craig Willis and David Cox.
Thanks to everyone involved.

SDF is built on [[Perl]], a freely available scripting language
created by Larry Wall ({{EMAIL:larry@wall.org}}). Without Perl,
SDF would not exist. Thanks Larry.

Finally, thanks to my wife, Geraldine, for being my best friend
and inspiring me to develop SDF.
sdf-2.001/doc/user/in_omgmt.sdf010064400042570001753000000102360661461262200161570ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Object Management

H2: Overview

{{Object management}} is a collection of features which support:

^ the definition of special objects in configuration files
+ the use of these special objects in documents.

For example, a configuration file can contain a lookup table of
{{CLASS:references}}. Within a document:

* a table of references can be inserted by simply specifying
  document codes - the document names are found from the lookup table
* REF/DOC object phrases are validated as legal references/documents
* hypertext is generated for:
  - entries in the table of references
  - REF and DOC object phrases
* REF objects can be converted to DOC objects and visa versa.

[[SDF]] supports 4 predefined {{classes}} of objects - {{CLASS:references}},
{{CLASS:terms}}, {{CLASS:products}} and {{CLASS:organisations}}.
New classes can be added via the {{MAC:class}} macro.

H2: The Predefined Classes

The fields supported by the predefined classes are given below.

!block table
Class           Styles      Identifer_fields    Property_fields
references      REF, DOC    Reference, Document Jump, Version, Status
terms           TERM        Term, Definition    Jump
products        PRD         Name                Jump
organisations   ORG, ORGN   Name, Long          Jump
!endblock

{{Styles}} are the tags used for objects in the class.
The first style is the 'normal' one. The second style
is the 'long' one.

{{Identifier fields}} are the 'normal' and 'long' (if any)
fields within the data tables. {{Property fields}} are
the additional fields, if any.

Note: The {{MAC:build_title}} macro uses the {{CLASS:references}} declarations
to provide default values for DOC_CODE, DOC_VERSION, DOC_STATUS and DOC_URL.

The {{MOD:objects}} module provides some commonly used
objects in these predefined classes (and matching variables).

H2: Declaring Objects

To declare a table of objects, the syntax is:

E:  !block {{class}}; data
E:  {{field names}}
E:  {{object record1}}
E:  ...
E:  {{object recordN}}
E:  !endblock

An example lookup table for organisations is given below.

!block example; wide
!block organisations; data
Name        Long                             Jump
DEC         Digital Equipment Corporation    http://www.dec.com
Frame       Frame International              http://www.frame.com
HP          Hewlett Packard                  http://www.hp.com
IBM         International Business Machines  http://www.ibm.com
Mincom      Mincom Pty Ltd                   http://www.mincom.com
Microsoft   Microsoft Corporation            http://www.microsoft.com
!endblock
!endblock

To insert a table of objects, the syntax is:

E:  !block {{class}}
E:  {{field names}}
E:  {{object key or record1}}
E:  ...
E:  {{object key or recordN}}
E:  !endblock

If only the key is provided, then the 'long' name is found from the
configured data, if any. For example, a configuration file may have
the following declaration of {{CLASS:terms}}:

E:  !block terms; data
E:  Term     Definition
E:  SDF      Simple Document Format
E:  SQL      Structured Query Language
E:  !endblock

These can then be inserted into a document as follows:

E:  !block terms
E:  Term     Definition
E:  SDF
E:  SQL
E:  WWW      World Wide Web
E:  !endblock

Note that the definition for a term already declared will be inserted
if none is provided. Furthermore, new terms (like WWW above) can be
inserted and added to the configured ones.

H2: Hypertext and Name Conversion

If an object has a 'Jump' property defined for it, hypertext is
automatically generated for it. For example:

V: See {{DOC:My Design Document}} for further details

will have a jump created for the DOC object.

Object names can be converted between the normal and long forms
by using the {{OATTR:expand}} and {{OATTR:shrink}} attributes.
For example:

V: {{PRD:Java}} was developed by {{ORG[expand]Sun}}.

!end_topic
sdf-2.001/doc/user/in_lists.html010064400042570001753000000103330672242750600163650ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Lists





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      3.3. Lists
      

      

      3.3.1. Overview
      

      SDF supports 3 types of lists:
      

        

      • unordered - items are bulleted

      • plain - items are not bulleted

      • ordered - items are labelled with numbers or letters.
      

      As lists are so common, they are supported by a special syntax:
      

         special_tag text

      

      where special_tag is a sequence of 1 to 6 special characters. Spaces or tabs between the tag and text are ignored.
      

      

      3.3.2. Unordered Lists
      

      To define an unordered list, use the '*' character. For example:
      

      * peach
* banana
* mango.

      

      The result is:
      

        

      • peach

      • banana

      • mango.
      

      

      3.3.3. Plain Lists
      

      To define a plain list, use the '.' character. For example:
      

      . peach
. banana
. mango.

      

      The result is:
      

        
peach

        
banana

        
mango.
      

      

      3.3.4. Ordered Lists
      

      To define an ordered list, use the '^' character for the first item and the '+' character for remaining items. For example:
      

      ^ peach
+ banana
+ mango.

      

      The result is:
      

        

      1. peach

      2. banana

      3. mango.
      

      

      3.3.5. List Paragraphs
      

      To nest a normal paragraph inside a list, use the '.' tag. For example:
      

      * peach
. This is one of my favorites.

      

      The result is:
      

        

      • peach

        
This is one of my favorites.
      

      

      3.3.6. Nested Lists
      

      Lists can be nested up to 6 levels. The nesting level is taken from the number of special characters in the tag. For example:
      

      ** a bulleted list at level 2
^^^ an ordered list at level 3

      

      To nest normal paragraphs inside these lists, use plain list items. For example:
      

      ** a bulleted list at level 2
.. A normal paragraph at level 2.

      

      

      3.3.7. The '-' Special Tag
      

      As a convenience, the '-' character can be used to specify a bulleted list at level 2. For example:
      

      * inputs:
  - programmers
  - pizza
* outputs:
  - software
  - empty pizza boxes.

      

      The result is:
      

        

      • inputs:
          

        • programmers

        • pizza
        

      • outputs:
          

        • software

        • empty pizza boxes.
      

      Likewise, the tags '--' to '-----' are equivalent to the tags '***' to '******'.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_tbov.sdf010064400042570001753000000040320661461231700160040ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Overview

H2: Features

SDF supports a range of features related to tables including:

* tables are defined in a simple format which is:
  - easy to write and read
  - upwardly-compatible with the CSV (comma-separated value) format
    exported by most databases and spreadsheets
  - upwardly-compatible with the fixed-width format generated by
    most reporting tools.

* column widths can be dynamically sized or explicitly set
* heading, footing and group rows can be specified
* table alignment and positioning can be controlled
* cells support custom alignment, shading, ruling and colours.

In fact, SDF can do lots of very clever things with tables
including spreadsheet-like calculations on cells and ranges
of cells!

H2: Creating a Table

Tables are usually defined via the {{FILT:table}} filter.
For example:

E:  !block table
E:  Fruit      Comments
E:  Tropical:
E:  mango      a fruit-bat favorite
E:  banana     great for smoothies
E:  Other:
E:  Tomato     often matched with basil
E:  !endblock

:or:

E:  !include "fruits.tbl"; table

H2: TBL Format

The {{FILT:table}} filter expects a table definition in a simple text
format (called {{FMT:TBL}}) where:

^ the first (non-comment) line is the header record
+ remaining lines are data records.

The header record specifies the field names and the layout.
Fields can be placed in fixed-width columns or delimited by a
special character. Fixed-width format (as shown above) is usually used.

Note: The width of columns in the "input" has no bearing on the
width of columns in the output. To change the output width, refer to
{{SECT:Sizing Columns}}.

See the {{DOC:SDF Reference}} for further details on {{FMT:TBL}} format.
sdf-2.001/doc/user/in_ovvar.html010064400042570001753000000141020672242746300163640ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Variables





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      2.5. Variables
      

      

      2.5.1. Introduction
      

      A variable is a named value. Document-wide settings are controlled in SDF using variables. Likewise, authors can define and access their own variables. In either case, the value of a variable can be referenced in a paragraph by delimiting it with the special symbols [[ and ]].
      

      For example:
      

        !define MY_EMAIL 'abc@xyz.com'
  My electronic mail address is [[MY_EMAIL]].

      

      The result is:
      

      My electronic mail address is abc@xyz.com.
      

      

      2.5.2. Commonly used system variables
      

      Some commonly used system variables are:
      

      

      

Variable


Description


      

      

Options:


 


      

      

OPT_LOOK


the overall look (e.g. simple, fancy)


      

      

OPT_STYLE


the general type (e.g. memo, manual)


      

      

Titles:


 


      

      

DOC_NAME


the title, excluding the type (e.g. SDF)


      

      

DOC_TYPE


the title type (e.g. User Guide)


      

      

DOC_AUTHOR


the author


      

      

DOC_TOC


the number of heading levels in the table of contents


      

      


      

      2.5.3. Setting variables
      

      Variables can be set via:
      


      To undefine a variable, use the undef macro.
      

      

      2.5.4. The Define macro
      

      Variables are usually set in SDF by using the define macro. The format is:
      

         !define symbol [expression]

      

      Examples are:
      

         !define LONG
   !define VERSION "1.002"

      

      symbol is a sequence of letters, digits and underscore. If expression is omitted, the default value is 1.
      

      

      2.5.5. The Default macro
      

      It is often a good idea to only define a variable if it does not already have a value. To do this, use the default macro. The format is:
      

         !default symbol [expression]

      

      For example:
      

         !default VERSION "1.002"

      

      symbol is a sequence of letters, digits and underscore. If expression is omitted, the default value is 1.
      

      

      2.5.6. The Init macro
      

      Generally speaking, the first thing sdf does is to load the standard library (stdlib.sdm). However, if the first line of an SDF document is the init macro, the nominated variables are initialised before the standard library is loaded. This allows an SDF document to initialise variables used within the standard library. The format of the init macro is:
      

         !init name1["="expression1]";" name2["="expression2] ...

      

      For example:
      

         !init OPT_STYLE="memo"

      

      
Note: Certain variables cannot be set after the standard library is loaded. These variables can only be set via sdf's command line or via the init macro.

      

      

      2.5.7. Using the command line
      

      It is occasionally useful to set variables via sdf's -D option. Multiple definitions can be separated by commas. For example:
      

         sdf -DLONG,VERSION="1.002" ...

      

      Alternatively, the option can be repeated. For example:
      

         sdf -DLONG -DVERSION="1.002" ...

      

      In either case, if a value is not specified for a variable, 1 is assumed.
      

      
Note: Variables set on the command line override the values set by the init macro.

      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_ovphr.html010064400042570001753000000131000672242745400163620ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Phrases





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      2.3. Phrases
      

      

      2.3.1. Introduction
      

      A phrase is a section of text within a paragraph enclosed in the symbols {{ and }}. Like paragraphs, phrases are optionally tagged with a style. Some examples are given below.
      

      

      

SDF


Typical result


      

      

{{Hello world}}


Hello world


      

      

{{1:Hello world}}


Hello world


      

      

{{2:Hello world}}


Hello world


      

      

{{B:Hello world}}


Hello world


      

      

{{I:Hello world}}


Hello world


      

      

{{SECT:Tables}}


Tables


      

      

{{FILE:autoexec.bat}}


autoexec.bat


      

      


      

      2.3.2. Commonly used styles
      

      Some commonly used phrase styles are given below.
      

      

      

Tag


Description


Sample Output


      

      

Emphasis:


 


 


      

      

1


1st level emphasis (default)


emphasis 1


      

      

2


2nd level emphasis


emphasis 2


      

      

3


3rd level emphasis


emphasis 3


      

      

ST


strong emphasis


strong emphasis


      

      

Formatting:


 


 


      

      

N


normal


some normal text


      

      

I


italic


some italic text


      

      

B


bold


some bold text


      

      

U


underline


some underline text


      

      

EX


example


some example text


      

      

Types:


 


 


      

      

EMAIL


email address


ianc@mincom.com


      

      

FILE


Filename


myfile.sdf


      

      

SECT


Section


Paragraphs


      

      

URL


Uniform Resource Locator


http://www.mincom.com


      

      

Classes:


 


 


      

      

DOC


document title


SDF User Guide


      

      

REF


reference (document code)


MTR-SDF-0002


      

      

ORG


organisation


Mincom


      

      

PRD


product


MIMS


      

      


      
Note: When emphasising text, it is generally better to use an emphasis style rather than a formatting style as the best way of doing so depends on the output format.

      

      

      2.3.3. Type vs class styles
      

      A type (e.g. EMAIL) simply marks a phrase as a logical entity. Rules may be defined for processing (e.g. generating hypertext) for these types.
      

      A class (e.g. DOC) is a special kind of type where the entity must be a member of a predefined set. Rules can also be defined for processing classes, although hypertext jumps are often defined for each entity in the tables which define the known entities. Refer to Object Management, later.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_libr.sdf010064400042570001753000000035320647456732000157750ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Modules and Libraries

H2: Modules

[[SDF]] can be extended by using {{modules}}. A module is a normal
[[SDF]] file which typically contains reusable entities like {{macros}},
{{filters}} and {{styles}}. Modules are loaded by the {{MAC:use}}
macro. For example:

E:   !use "delphi"

By convention, modules are given the {{sdm}} extension. The {{MAC:use}}
macro adds this extension if none is provided. Modules can also be
loaded by using {{CMD:sdf}}'s -u option.

H2: Libraries

A collection of related modules can be placed into a {{library}}
which is simply a subdirectory under the {{sdf/home}} directory on
Perl's library path.
Libraries can be loaded by the {{MAC:inherit}} macro which
essentially does the following:

^ appends the matching directory onto the {{include path}}
+ loads the matching {{main module}}.

For example:

E:   !inherit "images"

^ appends sdf/home/images onto the include path
+ loads the sdf/home/images/images.sdm module.

H2: The Configuration Library

After loading the standard library ({{stdlib}}), [[SDF]] loads
the configuration library, if any. This is typically specified
via the {{VAR:OPT_CONFIG}} variable being initialised on the top
line of the file via the {{MAC:init}} macro. It can also be set via
{{CMD:sdf}}'s -c option.

While {{CMD:sdf}} only supports a single configuration library,
additonal libraries can be loaded via the {{MAC:inherit}} macro.
Furthermore, a library can inherit things from other libraries,
making it easy to create new ones.
sdf-2.001/doc/user/in_examp.html010064400042570001753000000127110672242750300163400ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Example Paragraphs





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      3.2. Example Paragraphs
      

      

      3.2.1. Simple Examples
      

      Example paragraphs are displayed in a fixed-width font (e.g. Courier). Unlike most other paragraphs, spaces and tabs immediately after the paragraph tag are not ignored in example paragraphs. The tags used are:
      

        

      • E - fixed-width text

      • V - verbatim, fixed-width text (embedded symbols are ignored).
      

      For example:
      

      E:# {{Greeting}} outputs a friendly greeting.
E:sub Greeting {
E:    print "Hello world\n";
E:}

      

      The result is:
      

      # Greeting outputs a friendly greeting.
sub Greeting {
    print "Hello world\n";
}

      

      

      3.2.2. Shorthand Notation
      

      As verbatim, fixed-width text is very common in software documentation, ">" is provided as a shorthand for "V:". For example:
      

      ># {{Greeting}} outputs a friendly greeting.
>sub Greeting {
>    print "Hello world\n";
>}

      

      The result is:
      

      # {{Greeting}} outputs a friendly greeting.
sub Greeting {
    print "Hello world\n";
}

      

      

      3.2.3. Large Examples
      

      Large examples are usually defined using the example or verbatim filters like this:
      

      !block example
# {{Greeting}} outputs a friendly greeting.
sub Greeting {
    print "Hello world\n";
}
!endblock

      

      

      3.2.4. Wide Examples
      

      If an example block has unwanted line breaks, the wide parameter should be specified. Wide examples use a wider text area (and a smaller font, if necessary) so that 80 characters can fit onto each line. For example:
      

      !block example; wide
sub SaveTheWorld {                  # This routine provides world peace
    local($param1, param2) = @_;    # Input parameters

    # Do the work
    # ...
}
!endblock

      

      The result is:
      

      sub SaveTheWorld {                  # This routine provides world peace
    local($param1, param2) = @_;    # Input parameters

    # Do the work
    # ...
}

      

      

      3.2.5. Formatting Source Code
      

      Blocks of source code can be nicely formatted via the lang parameter to the example filter. For example:
      

      !block example; lang='Perl'
sub hello {
    local($planet) = @_;

    # Output a nice message
    print "hello $planet!\n";
}
!endblock

      

      The result is:
      

      sub hello {
    local($planet) = @_;

    # Output a nice message
    print "hello $planet!\n";
}

      

      For convenience, if a programming language is used as a filter (and a filter of that name doesn't exist), SDF implicitly calls the example filter for you with the relevant lang parameter.
      

      There is built-in support for numerous languages including Perl, C, C++, Java, Delphi, CORBA IDL and shell. New language definitions can be easily added (vgrind definitions are used).
      

      

      3.2.6. File Pretty Printing
      

      Pretty printing of source code files is directly supported by sdf's -P option. For example:
      

        sdf -2ps -Psh myscript
  sdf -2ps -P myapp.c
  sdf -2ps -P -n5 mylib.pl

      

      The language to use can be specified as a parameter. The default language is derived from the extension of the file. The -n option adds line numbers at the frequency given. The default frequency is 1. i.e. every line.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_gsex.sdf010064400042570001753000000037470647457123000160160ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: A simple example

H2: A sample SDF document

A sample SDF document is shown below:

!include "../paper/mydoc.sdf"; verbatim

Note: This document (called {{FILE:mydoc.sdf}}) is provided in
the {{FILE: doc/paper}} directory of the SDF distribution.

H2: A brief explanation

Comments begin with a # character as the first non-whitespace
character on a line.

Macros are embedded commands which begin with a ! as the
first non-whitespace character on a line.
The {{MAC:define}} macro is used to set variables.
The value of a variable can be embedded in paragraph
text  by using the E<2[>...E<2]> syntax.

The DOC_NAME and DOC_TYPE variables are used by
the {{MAC:build_title}} macro which creates:

* a cover page (or two) for paper-based outputs
* a title header for online outputs.

Paragraphs can be tagged in different ways. For the vast majority of
SDF documents, the only tags used are:

!block table
Tag     Meaning
H1:     level 1 heading
H2:     level 2 heading
*       item in level 1 bulleted list
-       item in level 2 bulleted list
^       first item in level 1 ordered list
+       next item in level 1 ordered list
>       fixed-width, verbatim text
Note:   note
!endblock

Phrases can also be tagged in several ways. Any phrase can be tagged
using the syntax:

>  {{XYZ:...}}

where XYZ is the tag. For single, uppercase character tags like
I (Italics) and B (Bold), POD-style syntax is also supported:

>  X<...>

where X is the tag.

Tables can be specified using the {{FILT:table}} filter, typically
in combination with the {{MAC:block}} and {{MAC:endblock}} macros.
The first row is the headings. Remaining rows are data.
sdf-2.001/doc/user/in_omgmt.html010064400042570001753000000162150672242760500163570ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Object Management





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      6.3. Object Management
      

      

      6.3.1. Overview
      

      Object management is a collection of features which support:
      

        

      1. the definition of special objects in configuration files

      2. the use of these special objects in documents.
      

      For example, a configuration file can contain a lookup table of references. Within a document:
      

        

      • a table of references can be inserted by simply specifying document codes - the document names are found from the lookup table

      • REF/DOC object phrases are validated as legal references/documents

      • hypertext is generated for:
          

        • entries in the table of references

        • REF and DOC object phrases
        

      • REF objects can be converted to DOC objects and visa versa.
      

      SDF supports 4 predefined classes of objects - references, terms, products and organisations. New classes can be added via the class macro.
      

      

      6.3.2. The Predefined Classes
      

      The fields supported by the predefined classes are given below.
      

      

      

Class


Styles


Identifer fields


Property fields


      

      

references


REF, DOC


Reference, Document


Jump, Version, Status


      

      

terms


TERM


Term, Definition


Jump


      

      

products


PRD


Name


Jump


      

      

organisations


ORG, ORGN


Name, Long


Jump


      

      


      Styles are the tags used for objects in the class. The first style is the 'normal' one. The second style is the 'long' one.
      

      Identifier fields are the 'normal' and 'long' (if any) fields within the data tables. Property fields are the additional fields, if any.
      

      
Note: The build_title macro uses the references declarations to provide default values for DOC_CODE, DOC_VERSION, DOC_STATUS and DOC_URL.

      

      The objects module provides some commonly used objects in these predefined classes (and matching variables).
      

      

      6.3.3. Declaring Objects
      

      To declare a table of objects, the syntax is:
      

        !block class; data
  field names
  object record1
  ...
  object recordN
  !endblock

      

      An example lookup table for organisations is given below.
      

      !block organisations; data
Name        Long                             Jump
DEC         Digital Equipment Corporation    http://www.dec.com
Frame       Frame International              http://www.frame.com
HP          Hewlett Packard                  http://www.hp.com
IBM         International Business Machines  http://www.ibm.com
Mincom      Mincom Pty Ltd                   http://www.mincom.com
Microsoft   Microsoft Corporation            http://www.microsoft.com
!endblock

      

      To insert a table of objects, the syntax is:
      

        !block class
  field names
  object key or record1
  ...
  object key or recordN
  !endblock

      

      If only the key is provided, then the 'long' name is found from the configured data, if any. For example, a configuration file may have the following declaration of terms:
      

        !block terms; data
  Term     Definition
  SDF      Simple Document Format
  SQL      Structured Query Language
  !endblock

      

      These can then be inserted into a document as follows:
      

        !block terms
  Term     Definition
  SDF
  SQL
  WWW      World Wide Web
  !endblock

      

      Note that the definition for a term already declared will be inserted if none is provided. Furthermore, new terms (like WWW above) can be inserted and added to the configured ones.
      

      

      6.3.4. Hypertext and Name Conversion
      

      If an object has a 'Jump' property defined for it, hypertext is automatically generated for it. For example:
      

       See {{DOC:My Design Document}} for further details

      

      will have a jump created for the DOC object.
      

      Object names can be converted between the normal and long forms by using the expand and shrink attributes. For example:
      

       {{PRD:Java}} was developed by {{ORG[expand]Sun}}.

      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_hyper.sdf010064400042570001753000000027260635672726400162040ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Hypertext

H2: Attributes

Hypertext can be specified using the {{OATTR:id}} and {{OATTR:jump}}
phrase attributes.
The value of {{OATTR:id}} is a text string which can include letters, digits,
underscores and spaces.
The value of {{OATTR:jump}} is 
a World Wide Web (WWW) Uniform Resource Locator (URL).

Commonly used jump formats are summarised below.

!block table
Format      Description
{{#}}xyz    jump to {{xyz}} within this document
abc         jump to document {{abc}}
abc{{#}}xyz jump to {{xyz}} within document {{abc}}
!endblock

For example:

!block example; pure
This is the only software you will ever need.
See {{CMD[jump="#smartcmd"]smartcmd}} for details.

H2[id="smartcmd"] smartcmd - Do What I Want Utility

{{CMD:smartcmd}} is the best program ever written.
It detects what you want to do next by ...
!endblock

If you want to specify a phrase as a hypertext
target within "normal" paragraph text, use the N (for Normal) phrase style.
For example:

V:   The {{N[id='_option_o']-o option}} specifies ...

Note: Hypertext jumps are ignored when paper documents are being generated.

!end_topic
sdf-2.001/doc/user/in_symb.html010064400042570001753000000143220672242762500162050ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Escaping Symbols





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      6.8. Escaping Symbols
      

      

      6.8.1. Special Characters at the Start of a Line
      

      To escape a special character at the start of a line, precede it with a backslash character (\).
      

      

      6.8.2. Tag Delimiters
      

      Like special characters, any special pattern at the start of a line can be escaped by preceding it with a backslash character (\).
      

      Consider the following example:
      

         Important:

      

      This paragraph has a tag called Important and has no text. sdf will warn you if it finds an unknown tag so most unintentional errors like this are detected. You can escape the pattern like this:
      

         \Important:

      

      Other workarounds are:
      

         :Important:
   N:Important:

      

      

      6.8.3. Special Symbols
      

      SDF uses a number of special symbols inside paragraphs:
      

        

      • A-Z< and > - delimit concise phrases

      • {{ and }} - delimit verbose phrases

      • [[ and ]] - delimit expressions (e.g. variables).
      

      If you need to include one of these symbols in a paragraph, use the appropriate escape as shown below.
      

          Symbol      Escape
    <           E<lt>
    >           E<gt>
    {{          E<2{>
    }}          E<2}>
    [[          E<2[>
    ]]          E<2]>

      

      Note the following rules:
      

        

      1. It isn't necessary to escape any symbols within:
          

        • paragraphs tagged with the V style or > tag
          

        • paragraphs given the verbatim attribute
          

        • paragraphs within a verbatim block
        

      2. It is only necessary to escape a < when it appears after a capital letter.

      3. It is only necessary to escape a > inside a concise phrase. In particular, > is implicitly escaped within a verbose phrase.
      

      

      6.8.4. Phrase Parsing Rules
      

      For paragraphs which do not have the verbatim attribute set, the parsing rules for the paragraph text are:
      

        

      1. Expressions embedded in [[ and ]] are recursively expanded

      2. Verbose phrases embedded in {{ and }} are recursively expanded to concise phrases with a V tag.

      3. Concise phrases are parsed.
      

      

      6.8.5. Multi-line Macros
      

      !-style macros can be continued onto the next line by ending the line with a backslash character (\). To escape this backslash, use another one. If N backslash characters are found at the end of a line where N is greater than 2, then that line is terminated by N-1 backslash characters and the macro is continued onto the next line.
      

      

      6.8.6. Embedded Expressions
      

      As expressions embedded within text are terminated by the ]\] symbol, expressions cannot contain this character sequence. If you need this sequence within an expression, there is usually a simple workaround you can use. For example:
      

        

      1. use a space character (i.e. $a[$b[1]] becomes $a[$b[1] ])

      2. use string concatentation (i.e. "]]" becomes "]"."]").
      

      

      6.8.7. Semi-Colons Within Attributes
      

      If you need to include a real semi-colon within an attribute or parameter, use two semi-colons. In general, if you need to include a sequence of N semi-colons in an attribute expression, use N+1 semi-colons. For example:
      

      To install {{P[index="myApp;;install:myApp"]myApp}}, ...

      

      In this case, the value of index is myApp;install:myApp.
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_tbss.html010064400042570001753000000160520672242757300162120ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Spreadsheet calculations





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      5.8. Spreadsheet calculations
      

      

      5.8.1. Overview
      

      Spreadsheet style calculations have been introduced into SDF using the standard [[ ]] syntax with a prefix of + (or =) indicating that the expression is to be evaluated by the calculation routines.
      

      This extension has been loosely modelled on Microsoft Excel®  in terms of the initial functions supported and the syntax used.
      

      The spreadsheet expression evaluator and the documentation below was written by Tim Hudson (tjh@cryptsoft.com).
      

      

      5.8.2. Cells and Cellids
      

      Each cell in a table has an cellid which is made up of a single uppercase letter indicating the column index and a number indicating the row index (counting from 1 and excluding the heading rows). The upper left cell is hence A1.
      

      An example grid indicating cellids:
      

      

      

Title1


Title2


Title3


Title4


Title5


      

      

A1


B1


C1


D1


E1


      

      

A2


B2


C2


D2


E2


      

      

A3


B3


C3


D3


E3


      

      

...


...


...


...


...


      

      

A100


B100


C100


D100


E100


      

      


      A range of cellids is specified using the syntax cellid1:cellid2. For example: A1:C1 is exactly the same as A1,B1,C1
      

      

      5.8.3. Spreadsheet Expressions
      

      An expression consists of a combination of standard Perl operators and spreadsheet functions and cellids or cellid ranges.
      

      Standard Perl operators include:
      

        

      • + - * /
      

      

      5.8.4. Spreadsheet Functions
      

      Spreadsheet functions use the syntax FUNCTION(ARG1,ARG2,...ARGN).
      

      The following functions are supported:
      

        

      • AVERAGE - the average - SUM(ARGS)/COUNT(ARGS)

      • SUM - the sum of the args - same as ARG1+ARG2+...+ARGN

      • MIN - the minumum argument value

      • MAX - the maximum argument value

      • COUNT - the number of arguments

      • PRODUCT - the product of the args - same as ARG1*ARGN*...*ARGN

      • ROWSUM - the SUM of all the cells in the row to the left of the current cell

      • ROWPROD - the PRODUCT of all the cells in the row to the left of the current cell

      • COLSUM - the SUM of all the cells in the column above the current cell

      • COLPROD - the PRODUCT of all the cells in the column above the current cell
      

      

      5.8.5. An Example
      

      A simple example is shown below:
      

      !block table; style="grid"
Count         Price        Total
10            5            [[=A1*B1]]
15            5.23         [[=ROWPROD]]
[[=COLSUM]]   [[=B1+B2]]   [[=COLSUM]]
!endblock

      

      This generates the result below. (Ok, summing two prices is meaningless, but it illustrates the syntax.)
      

      

      

Count


Price


Total


      

      

10


5


50.00


      

      

15


5.23


78.45


      

      

25.00


10.23


128.45


      

      


      

      5.8.6. Accessing Spreadsheet Values in Paragraph Text
      

      Values are available until the next table is processed so you can refer to data inside normal paragraphs after the table like this [[=A1]] (which evaluates to 10.00).
      

      

      5.8.7. Recursive Expression Evaluation
      

      A spreadsheet expression will recursively evaluate any expressions contained in cells that are used in an expression. In the example above, the expression in cell C3 depends on the results of the expression in cell C1 and C2.
      

      

      5.8.8. Disabling Calculations
      

      Calculation support for a table can be disabled by adding in an attribute of nocalcs. (Without this, the pointers required to table data that are needed when doing spreadsheet calculations occur for each table cell.)
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



al}
.changed {background-color: teal}
.changed {background-color: teal}
.changed {background-color: teal}
.changed {background-color: teal}
.changed {background-color: teal}
.changed {background-color: teal}
.changed {background-color: teal}
.changed {background-color: teal}
.changed {background-color: teal}
.changed {background-color: teal}
.changed {background-color: teal}
.changed {background-color: teal}
.changed {background-color: teal}
-->


>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Macros

H2: Introduction

A {{macro}} is a command which can be embedded within [[SDF]].
Macros begin with an exclamation mark (!) as the first non-whitespace
character on a line. Some examples are:

E:  !use "delphi"
E:  !define DOC_AUTHOR "Joe Bloggs"
E:  !build_title


H2: Commonly used macros

Some commonly used macros are given below.

!block table
Macro                                   Description
init {{variables}}                      initialise variables
define {{variable}} [{{expression}}]    set a variable's value
build_title                             build a title page
block {{filter}}                        begin a block of text
endblock                                end a block of text
include {{file}}[; {{filter}}]          include another file
import {{file}}[; {{parameters}}]       import a figure
!endblock

A complete list of the supported macros and their parameters
is given in the {{DOC: SDF Reference}} manual.

H2: Creating new macros

The easiest way to create a new macro is to use the
{{MAC:macro}} and {{MAC:endmacro}} macros. For example:

!block example; pure
!macro MY_MACRO
This text will appear whenever the author calls !MY_MACRO.
!endmacro
!endblock

Macros can also be implemented by a Perl subroutine which
generates the SDF text to be inserted when the macro is called.
See the {{DOC:SDF Guru Guide}} for further details.
sdf-2.001/doc/user/in_fgtit.html010064400042570001753000000064170672242752200163520ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Adding Figure Titles





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      4.3. Adding Figure Titles
      

      

      4.3.1. Adding a Title to a Figure
      

      To add a title, use the title attribute of the import macro. For example:
      

        !import "growth"; title="Predicted Growth"

      

      

      4.3.2. Adding a Title to a Psuedo Figure
      

      Occasionally, it is useful to label a source code example or ASCII graphic with a title. To do this, use the FT (Figure Title) paragraph style. For example:
      

         FT: Source code for main.c
   !include "main.c"; example; lang='C'

      

      

      4.3.3. Generating a List of Figures
      

      A list of figures can be generated from the figure titles. To do this, set the DOC_LOF variable. For example:
      

      # Build the title
!define DOC_NAME "World Peace in 60 Days"
!define DOC_LOF
!build_title

      

      This will generate a list of figures after the table of contents.
      

      

      4.3.4. Changing the List of Figures Title
      

      The default title for the list of figures is "List of Figures". To change this, set the DOC_LOF_TITLE. For example:
      

      !define DOC_LOF_TITLE "Figures"

      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



sdf-2.001/doc/user/in_overv.html010064400042570001753000000057740672242747500164120ustar00iancmtr00000400000236






SDF 2.001: SDF User Guide: Expressions





      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      

      

      

      2. Language overview
      

      

      2.1. Basic concepts
      

      The basic concepts within SDF documents are:
      

      

      

Concept


Description


      

      

paragraph


one or more lines of text


      

      

phrase


a section of text within a paragraph


      

      

style


the type of a document, paragraph, phrase or table (e.g. H1)


      

      

macro


a command embedded in a document (e.g. !define)


      

      

variable


a named value (e.g. DOC_NAME)


      

      

filter


a rule to use when processing certain sections of text (e.g. table)


      

      

attribute


a named parameter of a paragraph, phrase or filter (e.g. jump)


      

      

expression


a literal or expression to evaluate (e.g. "Ian Clatworthy").


      

      


      Further details about these are given below.
      

      Paragraphs
      

      Phrases
      

      Macros
      

      Variables
      

      Filters
      

      Attributes
      

      Expressions
      

      

      

      

      Contents | Parent Topic | Previous Topic | Next Topic 
      Home | Catalog
      

      

      



">
>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Book Mode

By default, {{CMD:sdf}} processes each argument as a single document.
i.e. a single stream of paragraphs is passed to the {{format driver}}
for conversion. This mode is good enough for most documents.

In {{book mode}}, {{CMD:sdf}} processes each argument as a "book".
i.e. a set of {{MAC:include}} macros specifying the chapters.
In this mode, a shell script is generated which treats each chapter
as a "pseudo-document". This mode is required when:

^ you wish to generate a [[FrameMaker]] book

+ you want to generate a list of figures, list of tables or index

+ each chapter has a fancy cover page.

Book mode can be activated via {{CMD:sdf}}'s -b option.

Note: The {{VAR:OPT_BOOK}} variable can be used to check if book mode is
active. However, it cannot be used to enable or disable the mode.

!end_topic
sdf-2.001/doc/postscript.gif010064400042570001753000000015420647547732400156100ustar00iancmtr00000400000236GIF89a÷ÿÿÿÿÿÌÿÿ™ÿÿfÿÿ3ÿÿÿÌÿÿÌÌÿÌ™ÿÌfÿÌ3ÿÌÿ™ÿÿ™Ìÿ™™ÿ™fÿ™3ÿ™ÿfÿÿfÌÿf™ÿffÿf3ÿfÿ3ÿÿ3Ìÿ3™ÿ3fÿ33ÿ3ÿÿÿÌÿ™ÿfÿ3ÿÌÿÿÌÿÌÌÿ™ÌÿfÌÿ3ÌÿÌÌÿÌÌÌÌÌ™ÌÌfÌÌ3ÌÌÌ™ÿÌ™ÌÌ™™Ì™fÌ™3Ì™ÌfÿÌfÌÌf™ÌffÌf3ÌfÌ3ÿÌ3ÌÌ3™Ì3fÌ33Ì3ÌÿÌÌÌ™ÌfÌ3Ì™ÿÿ™ÿÌ™ÿ™™ÿf™ÿ3™ÿ™Ìÿ™Ì̙̙™Ìf™Ì3™Ì™™ÿ™™Ì™™™™™f™™3™™™fÿ™fÌ™f™™ff™f3™f™3ÿ™3Ì™3™™3f™33™3™ÿ™Ì™™™f™3™fÿÿfÿÌfÿ™fÿffÿ3fÿfÌÿfÌÌfÌ™fÌffÌ3fÌf™ÿf™Ìf™™f™ff™3f™ffÿffÌff™fffff3fff3ÿf3Ìf3™f3ff33f3fÿfÌf™fff3f3ÿÿ3ÿÌ3ÿ™3ÿf3ÿ33ÿ3Ìÿ3ÌÌ3Ì™3Ìf3Ì33Ì3™ÿ3™Ì3™™3™f3™33™3fÿ3fÌ3f™3ff3f33f33ÿ33Ì33™33f333333ÿ3Ì3™3f333ÿÿÿÌÿ™ÿfÿ3ÿÌÿÌÌÌ™ÌfÌ3Ì™ÿ™Ì™™™f™3™fÿfÌf™fff3f3ÿ3Ì3™3f333ÿÌ™f3îÝ»ªˆwUD"îÝ»ªˆwUD"îÝ»ªˆwUD"îîîÝÝÝ»»»ªªªˆˆˆwwwUUUDDD"""!ù+,?WH° Áƒ*\È°¡Ã‡ÿIü7PâB‹)RL˜qÅÄ‹7~äÒ£Ç'¢´¨%D—cÊœ9àŠ€;sdf-2.001/doc/index.html010044400042570001753000000136770672243757600147160ustar00iancmtr00000400000236






SDF - The Author-friendly Markup Language






      

      

      

      

      

      

      

 


    


 S i m p l e 
       D o c u m e n t 
       F o r m a t 
             
      		

      

      

 


 


 


      

      

Key pages


 



      

      

 Document Catalog
       Frequently Asked Questions
       Overview Paper
      		

    


 Sample Showcase
       Resource Center
       Latest News
      		

      

      

      		

      

      

 


 


 


      

      

What is it?


 


SDF is a freely available documentation system designed and developed by Ian Clatworthy, with help from many others. Based on a simple, readable markup language, SDF generates high quality output in multiple formats, all derived from a single document source. Supported output formats include HTML, PostScript, PDF, man pages, POD, LaTeX, SGML, MIMS HTX and F6 help, MIF, RTF, Windows help and plain text. If you want to:

        publish documents or reports on the Web or in multiple formats
         maintain a large documentation suite using rule-based formatting and hypertext generation
         embed documentation in source code or pretty print source code
      

      then SDF may be for you.
      
      		

      

      

 


 


 


      

      

What does it need?


 


  Perl 5.005 or later.
         For generating PostScript, the freely available HTMLDOC program or pod2ps program or SGML-Tools and LaTeX packages. Alternatively, you need a word processor which can import MIF or RTF - Adobe's FrameMaker is preferred.
         For generating PDF, Adobe's Acrobat is recommended.
         For generating Windows Help files, a help compiler is required.
      		

      

      

 


 


 


      

      

Where can I get it?


 


The current version is 2.001, released 25-May-99. You can download the latest release from http://www.mincom.com/mtr/sdf/download/ in a variety of formats. SDF templates are also available from http://www.mincom.com/mtr/sdf/templates/.


      

      

 


 


 


      

      

Support?


 


An on-line bug database provides information on known bugs and requested enhancements. Any problems with the software or the documentation can be reported to the mailing list sdf-bugs@mincom.com. For general queries, mail sdf-users@mincom.com. To subscribe to either list, send a message to factotum@mincom.com with subscribe sdf-bugs or subscribe sdf-users as the message body.


      

      


      Questions about these pages? Send some mail to sdf-bugs@mincom.com.
      

      

      

      

      

      





Key pages

>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Jul-96 ianc    2.000beta7 release
# -----------------------------------------------------------------------
#

# Setup the header/footer: as this is the catalog page, remove the
# jump to it.
!define HTML_URL_CATALOG ''

# Define the list of columns to display
!define COLUMNS $var{'LOCAL_DOCS'} ? "PDF,PS" : "PDF&website,PS&website"
!define COLUMNS $var{'COLUMNS'} . ",DOC:Document,CONCISE:Date,Pages"

# Build the title
!define DOC_NAME "SDF Document Catalog"
!define DOC_TOC  0
!build_title

!subsections "Getting started,Manuals,Tutorials,Other documents"; "noprefix"

This page lists the supporting documentation available for SDF version
{{B:[[SDF_VERSION]]}}. For the latest documentation, visit the
{{DOC:SDF Document Catalog}} on the {{DOC:SDF Web Site}}.
Documentation for local extensions, if any, may be found
{{A[jump="local/"]here}}.


P1: Getting started

!block references; \
  columns=COLUMNS
Reference
MTR-SDF-0001
SDF-FAQ
MTR-SDF-0003
!endblock

P1: Manuals

!block references; \
  columns=COLUMNS
Reference
MTR-SDF-0002
MTR-SDF-0004
MTR-SDF-0005
!endblock

P1: Tutorials

!block references; \
  columns=COLUMNS
Reference
MTR-SDF-0011
MTR-SDF-0012
!endblock

P1: Other documents

!block references; \
  columns=COLUMNS
Reference
MTR-SDF-0008
!endblock
sdf-2.001/doc/paper/004075500042570001753000000000000672243774100140115ustar00iancmtr00000400000236sdf-2.001/doc/paper/sdfarch.gif010064400042570001753000000227550645304561400161150ustar00iancmtr00000400000236GIF89a@<÷€€€€€€€€€ÀÀÀÀÜÀ¦Êðÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿ::ÿWWÿuuÿ’’ÿ¯¯ÿÌÌ3J` w(Ž/¤7»>ÒFèMÿUÿl"ÿ‚Dÿ™fÿ°ˆÿƪÿÝÌ3"J1`@wOŽ^¤n»}ÒŒè›ÿªÿµ"ÿÁDÿÌfÿ׈ÿãªÿîÌ33GG\\pp……™™­­ÂÂÖÖëëÿÿÿÿ)ÿÿRÿÿzÿÿ£ÿÿÌ"31J@`Ow^Žn¤}»ŒÒ›èªÿµÿ"ÁÿDÌÿf×ÿˆãÿªîÿÌ3M"f+€3™<³DÌMæUÿhÿ|ÿ:ÿW£ÿu¶ÿ’Êÿ¯ÝÿÌ3PmŠ¨Åâÿÿ3ÿ3MÿMfÿf€ÿ€™ÿ™³ÿ³ÌÿÌ3Mf"€+™3³<ÌDæMÿUÿh:ÿ|Wÿuÿ£’ÿ¶¯ÿÊÌÿÝ3"J1`@wOŽ^¤n»}ÒŒè›ÿª"ÿµDÿÁfÿ̈ÿתÿãÌÿî33MMff€€™™³³ÌÌææÿÿÿÿ:ÿÿWÿÿuÿÿ’ÿÿ¯ÿÿÌÿÿ3(P7mEŠT¨bÅqâ€ÿŒÿ3™ÿM¦ÿf³ÿ€¿ÿ™Ìÿ³ÙÿÌæÿ3Uw™»Ýÿÿ--ÿDDÿ[[ÿqqÿˆˆÿŸŸÿµµÿÌÌÿ3&M3f@€M™Y³fÌsæ€ÿŽÿ:ÿ«WÿºuÿÈ’ÿׯÿæÌÿ33MMff€€™™³³ÌÌææÿÿÿÿÿ:ÿÿWÿÿuÿÿ’ÿÿ¯ÿÿÌÿ3M&f3€@™M³Yÿûð  ¤€€€ÿÿÿÿÿÿÿÿÿÿÿÿ!ù,@<þH° Áƒ*\È°¡Ã‡#JœH±¢Å‹3jÜȱ£Ç CŠI²¤É“(Sª\ɲ¥Ë—0cÊœI³¦Í›8sêÜɳ§O–‚
J´¨Q£?“*]Ê´©Ó§‹Ž”
µªÕ«X³j58ôe×­`ÊKV¤Ð›g˪]˶mد;áºK·®]—i™æ½Ë·¯ß¿ƒb¸°áÃu	kUŒ¸±ãÇN÷‚•¹²åËx¸eŒ¹³çÏ9·
º´éÓ\ýjFͺ5èÕª]˞ݘô]Û´së.ûpïÝÀƒ/†ü[¸ñãIqVŽ¼¹s¯ž‹?ŸN¥t›×fǸ½º÷ï»þËd~¼EñàÓ«oˆþ|^Á„3þ
7¾f¹Û¯ßÏ_~Š°Ùw߀QýfŸ@ú·šyçõçàƒýW}V¨ W^ˆà{JÔ!„ 
÷¡‡jx hî5߈…è"x,–a‚ð—`„’ã‹<š¶£C4f¨ tAnh¤†Sõ¨äq?>DÔ‘òÙ–bG"R“KfYZÖ„¥–`þõ%G]z晬e>©‰æ›l¹É—œpÖ)vái瞃Ѧ'Ÿ€>õç„Bò4h ˆ&‡Ó‡6˜è£s.jc£Bjib-ÉU£‘FYf~—†ºÙJE¦U¤‰”–'êªk¥J%ª]PÎ(+^¬ÖJ–«Cš:+¬¼’jë¯o©„⮧~J&°ÈgݬºÆ꬯ÉF{•«š–å†×
+í¶VáÚ-·àBå­ á–fãš«îEé*ºî»î:Ö.¼ôF4¯N÷þ	4xaB…6tøbD‰)V€E9ÄØdH‘#I–4yeJ•+YJÌØfÄ—1iÖ´ygN;y&üØ3æO C‰5ziRŽB•‚dÚjT©S©VÝøÔjC¬Y¹võúìÍ­adž5{mZµËfm»n\¹s¥¾j—n^½{ùÅ[ã̾ƒ	6L2°`£‰7vü2DÆ='G¶|³åÊ~ÿföü4ÜÄ]Ž}uj¾£Y·vÝZulÙ³+¦}wîÕ¤u÷öýj`àÉojÚxråËk"gþzôŽ°¥W·~]!uìÛ¹GÝ|øþå¶Å—7¯›üyõëQ§gÿ~d÷ñé×ï;ß~~ýkñï÷ÿ¿«þÀã
<A¥¾KÁsÒÎÁ%\	Â	-¼P$ç0ÜC‹4ìĵâMÄ1ÎÄzíCXtÍ +tñÅãd¼ÇuÜqFÀnŒqG urA	°.ïS’,#W<É‹'*™tÒE(¯ÔËJ›ºLêË	ÃÌ0/_±aƒåŠqCÅ ™f´LÐòÄ’˜/R6*y2aœI#õ‹”ñf…ŸC»~
´uÅγ9v¶½ºvJÙzeç^
ü2kŒÄ©ò¾ûòéW°Ì7÷ìXøÜã°«[wy}wõ܃''=!þ÷ÙƳ/6~4úõì·_»}yܺãǯïÕùsϿ勤ž€xu—Þ{( u	
¥ÙQkÉ×yâ=yÊÕÞ‚fù§Þ®§ák!þÔ ‡Ñ!^È"D&ÂÇÞˆ¡ÉøaPшX‰:®¸£Žõ¨ÙnÞgU‹µ}E[d Ú(“N^‡ãaQ
¤€CÉ™„Xf†Ÿh1>©˜bJ‰ÜTS:aUà]Y$…n	Ú—å
8f…Ùäñ…éŠIv©å~~êžœfhg¢táIQŒúô(”^)Š^j„Ü9—_l“bZ¨+¹È\ŽX©¨ªþWjNÀYŠþ¡¡«ê«%YT³î:c_¥1·kª°	K毂ñŠ¬Kµz$±9&«¢m5(´ÖÚ¸ltoAël¯Ášæ Ÿ×Ž‹®Ì;k·’©[¦±înKn¼Bºi½ý±{çµøbÇn¶šÚ©¼Ï;0¢Öî{bÁ
‰pP
Êí§u>¼po‰RÌš¾3\ñ¸·ôq£É†Ü¡“$w\ÖÉNmŒ¬Ê™]ŒòÁ0ËÚ2Ë`º³£3/)3Í7ç<òÎåjìó“8í°Ð™ÍóÄHóz4«E§k³ÑO«lÕTOÍdÔW÷dƒ?†d³ddŒd¯ÍvÛn¿õÛh¯=÷Ù•‰ýuÞzæõÖ{ÿ
8Çó\6UAUg¢UÖ[£³U*Vqíõ²cÓ×aÖD]‰Mv;c]VÙg-t¢%¡­6Ë&‹´6-€þH° Áƒ*\È°¡Ã‡#JœH±¢Å‹
`Üȱ£Ç CŠI²¤É“(Sª©q¥Ë—0cÊœI³¦Í›8!¶Ìɳ§ÏŸ@ƒ
*t'Ñ£H“*]Ê´)M£N£JJµªÕ¢W³jÝʵ«×‡P¿ŠK¶¬Ù›aϪ]˶­[‡ißÊK·nÖ¸vóêÝË'Þ¾€Ìñ/áÈ+6¬¸±ãÇnHžÌ²å˘­R®œ¹³çÏE)ƒMº4ÐɦS«^ý5ëק7ËžM»¶íÛ¸sëÞÍ»·ïßÀƒN¼¸ñãÈ“+_îú+g­Ï¡Ž~•úݱ֫f×>ívîb¿Kþ?¾ûZòåÃ{o‹^ýùÈØ×ËÜžiý¦÷ƒæOºŸ¿yµýùç€ìýwV€H!È“‚XÍ׃úÁ7àái:ç …nÈ¡†ïy¨×…?‘ˆá„f™è“ŠN±˜“‹Æ⌊XŒ0áh“Ž;˜b†^ñøT…ôÙH–*!)“’Kúx#]1™#‘5ÒH ŠOY—”­AÉ—.¦“Gz¹•˜IRÉš)±™&–ejI—›'щ’áI’ž{’)£œãÉv¤ ƒn6"¡Øš¢¢Ð‰v££6—£…J ¤waž¦›Jj¥‰Zz©¨_’éy¦Ê'K©že«|¢ºjLžÊžÌåªXºöj\¾‹hžÂëAÆ«S²Â"[X×54+´ M×µÏR«™³ÛbÛ-CÖJËR´à’+n¶…»Ðsê®ë-xµ›Ñ»TE'oBiÝËí¹ßº‹nžæÎûo¹¤¯A쌯Œ0½SÙk.@þ
XÐàA„	.dØÐ!A‡#N¤XÑbAˆ/näØ1cÇ„AŽ$yPä“%Uz¬˜råË–!aμèR&MœmšÌÙ³áN–>…"ŠqèQ£‹"]™r)S’OH…
ò)Õª±êÌêójמT·‚Uz“,L©cÏjŒ¨v-C·pߢå:·iL»*æ-™–oߺ}<0ᩇãš}¹XqÆÂ(£ü7heË÷fÖZ–sç¶w
~$–¦cÈ#+\M7ôgÍxa[Ü<ÛókÛ·ŠN*±÷iàVSîú5·n¶ÇqV¾|wóäÏ3ÿ=YîLÔU§^¹pëËÒ¡þSF>ž(có<1§§}¤ÈÒÚ»¦¯uxbßøõ#Û9ûßÜ0¿ö$P<§ZÏ#ÅÔ;°>Þì;L»Ñæón»¨P¬p@¿:|5ÞNŠ'ëÎ.¤á.$N?«4dCT±ÃE4nºOšœÂp¿!û«IÆôhÔ=¥Z|Œ ù’GcTq»	$Q/}ÄîGûX|ÑE"3üO³+l-Í«l2JÃÖ¼)ÅÚh»ïÅ8åÃÓÌ34IµC’6m”Ë/W$Š;2É´ÒMBÛ;ÑË÷d;RRIá”ÊuºF)¡´0EC!EóOßHÝÒTóTítÃAþ1Û”:øÚDÐRMÜs?DméÓ5ùÕVò¸„,×C{½D0ÜñÑT¯ôZV¯»ñ¼cg­ôÚ_Ùõ;å³Ú˜²M5K-™d6Ñ%ûŒ4)]K•—ÚeßœÖ(sçíÞ¶€%
Êp§·^ÐFV_AÝM²YŸeÝxkU–܇ŽsSƒµ¥áŠ)ô˜8€ÅÝVáK3ŽÖ4’Çs5ÙVcí3b~ýs¹.˜Ã=y`–%ûø[QEÝuãU§3ùàœn˜áu)®·æWeN¹Ø›á•ã‰sfÍß
¥,³j¨ù´Xcv	.ÖÈ/îÏ`§‰…õiH'õpd¶Ñ³8¿¹ÁÞ÷mOwö\þ³+ïѯ­šÛäì–Wc‰ÕZ™ã´gþ[ÝK¯NNÅ®˜rt
ýÚÛwñžññÏã¦;ÐÄ}5\i\ý5]“=·:vü8£­%Úô²1<á¨FíÃÌqÚÙÔ]oºåÙaŸ]SÉÒ”¸·±'µÑ"®|xÙ“·-vãm'^ô½Ç’rÍ¿>Ì­CÝùüÖ×Ö~6îÝG]y𥞷tk£GýDz^_xÈ…î}°‰Ÿç·½åAï~ê©ÍÜŠÀSJ>Ÿb_̺ZPeDêê;»ÕÍ|Ò˜ª÷3¸y/{¯C`û2x@ø%POÄߢ(ÅBêL}&üßà4¸Aþñ‡ÍÉŽ’·8ì
ÐrB\"t”dDv†<"R·?ª°{Z”ßñ˜ØD"j‰CL"	¥ÈÅ,‚Q9|¡i§DÎH¯FŒó\ÑØFÁ½Ž™©]¹æÇ2Ú±k+ô¢ƒhÈ~FŽ5ê£ ‰G:"2‘qÜ£eÙ®)*òvcqÆIò‹ )yÆ<Ò/”–¬ä_.	ÅLRò“k,åïˆÊSÚ²‚¸¬¥.¹ÅNf¥ˆß‹¥(ÃFL7ªr•®ì%(—É—FšÒ‡¼Œ"5›éL5=I›Ûäf7½ùÍþy
œã$g9É)Ns¦Sê<Í:ÝùÎo¢žó¤§XêyOxÎjQ™úL&?ý¹Ë¦2 þ&zТ!ô—
EhA5ÉPˆ4 (4+ZÈ‹f´š¥¨F×ÒQVzT¤ýdäH'ªQš›M©J™ÒÒ¼ÀÔ¥1DéLõ)Ó¹àÔ¦Æ̨Nw:JŽþT¥>ýhWþ¢@à@‚
D˜PáB†
>„âDŠ-”xQãFŽ=~i0cH’%Ž4™RåJ–Q¶„ùðeLš5m²œyS§Àœ;}þ\Ù(L¡CÕYiJ¥K>u	•¨TªUC6µºkV®I»–ÜúU¬Õ°c–5›öªÚŽÜ¾…Wî\ºuíÞÅ›.Û˜hùFýX¥_Á<S$|ø¬bÄŒk}¼8òÂÄ“[VXsaÍ;³ý¼94èÍ¥ŽN‹z¬êȬW›†]Ðõ×Ù\k+¾m;ön¹Éò6<¢ðàÄ1û®Š\ªrÏÆ™ÿùü©ô¥ÔS;‡ÞznéºÜ·gÇø=þ¶uð-Å‹–kú|ùÞéw“g4.ìõ–ÝÇo¿—7|ü&ç×O½ûûOÀûúSk@ïÞzAóãϧú¤Í-à0BÛ,lPA
WÓp'ü°=á
,q9½PmESsÑÃãbäp2S”ðÀˆtœŽG™^ìñƆ&LÐÇ!l1D…lkD ˜äH¼ŠÊ
kËJ³°ÄÑ&-㲦/ÁŒ.LœÌÒK4³"²Ë,C“¤8Í[Ó¿:‰ºsJ8ó¤I/—ðrS+%eCŽO1•3´ÏAyZô¤¡4Ñ@çÌÑNª(ELR5ËlT$M#U³Ó»ú43QOC­Ô¤ÈSuUùö<þ•¶-C‹•²¶¶óº,j»!Óõ¢ZznXb«¼´×÷Ž´؉4óë%i‡Ó¨2he%$©
j0F•Eh4pû2Ö(¬Î23‹#LÛÞ0âVØŠ:›¶¸‘êuÖ¿nÝ•3J\)Ü
ÝcO“÷Ù‚ß½×à|%«Ûwá}ø$n+T$°ª-ÕϵP"kôXÛAÙÄÆdjØ°„¿•8£ŽoEÙ_ˆ{ÂWæ~
ÆrÄ—¾ùdœ¾U-ã›f´è‡?¶7éàV˜áy[–8b—]6záf#Õfžm^ëYª¥^z¦ÚÚí+b³­Î.¬¯Áf{æ¨!>Ûiu!Kxå£ß7æ…×þ&Ò¦?"{é¨í.î⿻ݚkðÔVún{$¼ñxçn¸n¼Ï[îuÖš©ž¹];t¸õœ²œ=Vyê·WW<í˜ííÈÛ.=\-Wö‰õNypνíºéØuGœ÷«¿Ùh¾oÝõtÛ^ùËiלòƒ_™x´	V\{ŠIßQpñÞø«§'¾æÝã#z Ã;úÞ’™¾úÃ¥ÿýæ¹ß;ÛуàbN'²ŽýG{>³ªÒ‡¾ÿ­=B«Ÿù‚%Á	0‚H‰ÖædÇ@ú9ðaŸÖœò%0:#¬òb縱mŒ/×"õ3
ž…Gù²!¦Qo`‚¡àedøšÞÑ<1âõ¼ò¡qªIbWûäD(~&„ÌUŠ¤(d‘…5[$ÓЄ&Evñ†Z¬¦æ•FŠ
ËŒ™JÖç (GU‡9oÄxÕ(<æ|¤
búhºA†Kr:d“	8¿‰q‘k¤½HGb=Òk…ü&!d.KîH“UÂd$AòÉurV®é$P™Ê3­Ò”†tåPHù£‡þDÀ<ˆ0¡Â…:|(€Ä‰%¬ˆÄf¬xðãÄŽ$Kiñ"J&[ºT¸’%Á˜/ki“$Îœ<{úô‰ñ§Ð–‡åXô¨ÒžA—2MéTÁΨT«2µŠ5dÖ­¹zu(ó+QŠ?AŠ=‹ödZªa×mëö+ܸHÍÖ%K7¯×¹zsòíûò/`§‚ƒ™Ô°b¶‹ynñ1ä«“kJ®ŒÙof¢›K^îlò3è‹£K;6½Q´iÕ¨Á¶Žü:vGÖ¥iƒ¶-[kî…¸wî½8fᾉ÷<¡ñÉË7ýÜyòéj©Ï´~;RíÙ¹#®üþ`ñ«½K5_Ü;ù¾ë›o^®zîð;×Ï{?~Öünù§õÏÜ{úɆXˆ`‚SQ d
¢õà€éIH…E(†¾¦!}’6߇"n7¢PvâV)–˜ÙŠ²x^ˆ0Ψ6¹HŽUéhãx=Þ#Q	ù#~E¤€GÒHdnMžõäQQ.ÉÕGTF–˜…Sµå•Xeé%LM}ØeYa’i×™¼¥©¥’jRÈæ›!á¥%˜NÚ)'vtæ©Ü‚âygœ|Zçç 3Aµá˜É)j¨žeÖö([{N'h£{)ˆi¦
Ž§i§ž¢Ä\¡Å‰ji•¨m)C©J…(¡­–*þ_y(žZÙ«”®z%®Êù(«NŸþ
,‚*K짰zD묽Î&cw«j²ìIˬ‡Õ=-LÔ¹,‰ÚÁ¥k´ÙîÚmŽÛ¦ÖlWÐKnm¼ºëYº1bË.ˆðN[.lÖ^·n½öº§ìœ7Ae‘­Kš¼áòæï¿·½«ÒÀ2|™Á§Å»¯³­-üp¾ý‰QJ÷©TocÌ/½
«{¯^‚QÌjÌ2Ã<°Ì¬Š6ã}¾-rÍ7Û,ñ̶¿nxë|gn÷ç‰{^ùí¬®¹¿àVzXÜŸkÍíì¹÷Þ:NXÏz»s}=å¾ûñT;Ïóéãõú׸S/>º}›Ÿ·ûįɰöÑ­ºêÔ.qXÄïÌ5²ì{Sßîô'>ô‘xó
Ü¡†·õù®}úþˆ	4xaB…6tø"BLX"F#2äxÐbG‘#†$yeB“WÔøÒ"Ì‹1[ÊÜHsfΛ?.¬éӤ͊8uJÔæÖ)™6uúTa͇NzãUŠZ«îÜ	³§Q¨cK’5«ôäÒ’HÙê{õhN®8e†¥xèÚ¢I߶õ×ãYÁƒ	Kܪ÷ïĺV?.F—¨áÂ)ÕN6[¹!fÀX7ëmÜU.cÑEUâªÕkêªKSEm×´eÙ³QJ«Ñ ¯Wºv$푘…3%î“6ì¨Ç]n^¼vfèÓ©KÖ
’mÒµÀUûU¾±ºCþæá3¦M>ÞjyçbÉ«_ß¾l©ØIC¦Ÿz¯wÍñKóNr¼§¾s	5cóï?$k¾Ã¾¢+²¸|ËM»p9ÄxCë§Í‘DÊÜʵ	WÓ/¯³îÃ7$íDG,Dq|oÇ¥»PF‹òÄïLP$"}„ñ¢%ÑrJ&ã;RGþ”|±;»ò¹á”âÒÊ*©\Ì(á+ó¬1Ù±ÌÕZ£i˦®PM4ûC²ÉL3I3ý,ëÏ5c4.=ÜU9¿ÏÎûðOϼÒ²Ñ@‡´P6	}lÅCÑœsQá•ÓÓHåŒ%1Y›¬B
þÖ¥ÄtÇJóõ²Ms°BE}Í,DOwÅWý"
¶Æ<…]vÆ7¥uI\©“6GÊ\Õ/NãnôH­X‡E5CfSí2ÙíŒéÕs÷„¶Gj¡s×@k5¼Í19·•”@Oo#;où}RÐ|;jß#Ýü–GvK„W8†í}×VP-asñ-ÕKr~±3‹Ãå˜N…}tx6’M„¸ÚŒ¥xÙŽ[vq]eËuöe–%ìVäv¡5ùQù"¾w9z…F÷Z‰¹W)+;˜èkµ4Üß’†4ç…w¶šV‰Éã™êLŒëªö3l•-Õºº°‘-™°²Åî3k¬1Eûm»¾ºîAã&þÑmÇÎ{í½ó¾oM‡{ð€ï><ñ)×{î¿ë<òÆýë›O¾×òÅ1o»ó0'|t÷,§üìЧt“õÖ]öØe—ÈÙm¿÷Û%õ@?Wý]à…OxðÞÿü}x¶“_Þîâ«<žùÉ£Ÿ>÷ê­¿>wQ±ßž{اùïÅŸüò7ýôÕ_qöÝ~÷ßþúíooþûõߟYï€ Žþ7@ÓaZØ@2h_”à),DUƒ< í4ØA"ð‚áÅg=ž…ÉëK"˜B¾pn!äVþ`XC2Ša¼áyˆ²’Ñ°$‡A$¡BD!‰*	Ÿ“ØD!2ñ2@tâ÷E°I‘Š
þˆ	4xaB…6tø"D)VD8ÑbF9vôødH‘#I–4y¥IŒ);®dùfL™3iÖ´ygI—9îäùhP¡C‰5*ñhBŸI™6uújT£KR•zkV­[¹´ÚôkW±cÉ–5«“kسkÙ¶u{V-Ó¸oéÖµ{èܤzñöõûpKŠ|~h8pbÅ‹žˆx`\ÇŒ)W¶œx2d’_öü4ÜÎ;”Ž¬cé•]ªÞlihÙ³iƒí¼ù4nÔ©sÃæ­{rmáÉÛŽ:7ÁÕ½“3¿]zté 	«¶®[yòßÈ_û®¨yzxþñÅ«Ü®Ý9÷åÜ#‚ÿþg¾K§_ÿ5öÃñù÷¯—¾îšs­»ÖêÛ­=ÿ\°6÷‚rÁ%,Ÿ*œÃ¯ºð&5üÄ©ºò0ÄM̉ęR<‘ÅYZ&]œ‘ÆdDéÆuÜñ»¬räÈ úq$"…<I«22É&ƒdR#(œrG)Ÿ£Ë,7‚M(.µüÌö¬TjÌ0Í,ÑKšÒ<“Í6/ZG8Ýœ“NO"°Î<õTNÎ(ûÜP:­ƒlÐ@
=Ô¼A]´LDå±ÑG%=2ÒI-­òÒL5ÕoÓN­ÔÓP3UÔR$ÕÔTùCUÕV£cÔÕX©\TÖZ“TÔÖ\)½N×^«ÄÓ×:þR p Á‚"L¨p!ÆBŒ(‘!€Š/b̨q#ÇŽ?‚)r$É’&O¢L9Тʖ._ÂŒ)s&Íš6oVÌ©s'Ïž>
*4çÍ¢F"Mªt)S…šN|
u*ÕªV¯bE*5k­\¿‚
+v,X¯dÍ’M«v-Û¶#ÑŠ…ëv.ݺvÛÊ-{w/ß¾~§æýø/á†wœU1âÆŽ?f|U2äÊ–/»¥\U3æΞ?Så4éÒ¦C³}z5ëÖU7…íz6íÚNSÛέ{·CÙK}ó.ü2ð¤Å‡#ONøøQæÊŸCÏŒ;:õê™ó\©“`vέƒ?þš#K,Ïo-ò»øöî‹bO/µ<ú·ïïã×K^¾@úóÙ¯”Ÿ€Ž·‘ýñg€ýØ ƒFÅ·‚Ú!(abb˜!Lñt ‚öi¢ˆ$qh‡ê½6¢Š+’—\õM(Ò‚,Ò8`‰íÄÝŒ3ÖØã{<ʤCZ'ä†D"I¤‘/-™¤“Á5ÙR”ORYÛ”)]Y¥–«eyR—[‚ùÙ—%¦™••	â™k¶—¦Œlž›!ͧvÕ™â{&—§w|*œŸZhnƒ¶h¨¢³!jࢲ֨F’BZisÓYš)f”bÄ©¦Ÿ¹–§ ’ŠåP§¢šªª–Úª«¯Â«¬c;øÚDÐRMÜs?DméÓ5ùÕsdf-2.001/doc/paper/sdfintro.html010064400042570001753000001477510672242256500165410ustar00iancmtr00000400000236






SDF 2.001: The SDF Document Development System




      

      

      Home | Catalog
      

      

      

      

      

      The SDF Document Development System
      

      Ian Clatworthy (ianc@mincom.com), Research Architect, Mincom Pty Ltd
      

      25 May 1999
      

      

      

      

      

      Table of Contents
      


      

      

      

      Abstract
      

      SDF (Simple Document Format) is a freely available document development system which generates high quality outputs in a variety of formats from a single source. The output formats supported include HTML, PostScript, PDF, man pages, POD, LaTeX, SGML, MIF, RTF, Windows help and plain text.
      

      SDF documents are simple to create and maintain, minimising the time spent on documentation. In particular, SDF directly supports the creation and maintenance of large, on-line documentation systems (including intranets) via centralised hypertext management and rule-based hypertext generation.
      

      SDF has been completely developed in Perl, a popular and highly portable scripting language. Like Perl, SDF is freely available for commercial and non-commercial use.
      

      

      1. Overview
      

      1.1. Introduction
      

      SDF is a document publishing system which aims to solve some common problems that many software organisations encounter with documentation:
      

        

      1. How do we support multiple formats (and produce high quality output for each)?

      2. How do we reduce the time it takes to create documents?

      3. How do we maintain a large on-line documentation system?

      4. How can we generate and easily maintain hypertext links?

      5. How do we keep the documentation up to date with the code?

      6. How can we centrally manage corporate formatting standards?
      

      The basic design principles are:
      

        

      1. Documents should be specified in a logical manner.

      2. Make common things easy.

      3. Give power users full control when they need it.

      4. The architecture should be open and easy to extend.
      

      The key feature of SDF is the division of responsibility:
      

        

      • content is supplied as text files or generated where feasible

      • formatting is generally implied by the semantics of the content or supplied by rules or external templates.
      

      SDF consists of the following key components:
      

        

      • SDF - Simple Document Format, a text format for defining documents

      • sdf - a utility for converting SDF files to other formats.
      

      Unlike SGML, XML, HTML and many other markup languages, the SDF language has been designed to be author-friendly, rather than parser-friendly. As a result, most SDF documents look quite similar to plain text email, making them easy-to-write and easy-to-read.
      

      1.2. A Sample SDF Document
      

      A sample SDF document is shown below:
      

          # Build the title
    !define DOC_NAME           "GalaxyBuilder"
    !define DOC_TYPE           "Discussion Paper"
    !define DOC_AUTHOR         "Joe Bloggs"
    !build_title
    
    H1: Introduction
    
    After extensive market research, I believe there is
    an excellent opportunity for us to develop software
    for the I<galaxy construction industry>. Potential
    customers include:
    
    * NASA
    * European Community
    * China
    * Japan.
    
    Note: The proposed name of the software package to be
    developed is [[DOC_NAME]]. If you want to suggest a
    better name, send email to {{EMAIL:joe@bloggs.com}}.
    
    H2: Software Requirements
    
    The key requirements are:
    
    ^ support for the design and simulation of galaxies
      containing up to:
      - 1000 large planets, or
      - 5000 small planets
    + the package needs to be easy to use
    + the package needs to be well documented.
    
    H2: Project Team
    
    Exploding galaxies will be B<very> bad for business,
    so we need the best team possible for this project:
    
    !block table
    Person          Role
    Mary Jones      Project Manager
    Hans Blass      Architect
    Bill Smith      Software Engineer
    !endblock

      

      1.3. A Brief Explanation
      

      Comments begin with a # character as the first non-whitespace character on a line.
      

      Macros are embedded commands which begin with a ! as the first non-whitespace character on a line. The define macro is used to set variables. The value of a variable can be embedded in paragraph text  by using the [[...]] syntax.
      

      The DOC_NAME and DOC_TYPE variables are used by the build_title macro which creates:
      

        

      • a cover page (or two) for paper-based outputs

      • a title header for online outputs.
      

      Paragraphs can be tagged in different ways. For the vast majority of SDF documents, the only tags used are:
      

      

      

Tag


Meaning


      

      

H1:


level 1 heading


      

      

H2:


level 2 heading


      

      

*


item in level 1 bulleted list


      

      

-


item in level 2 bulleted list


      

      

^


first item in level 1 ordered list


      

      

+


next item in level 1 ordered list


      

      

>


fixed-width, verbatim text


      

      

Note:


note


      

      


      Phrases can also be tagged in several ways. Any phrase can be tagged using the syntax:
      

        {{XYZ:...}}

      

      where XYZ is the tag. For single, uppercase character tags like I (Italics) and B (Bold), POD-style syntax is also supported:
      

        X<...>

      

      where X is the tag.
      

      Tables can be specified using the table filter, typically in combination with the block and endblock macros. The first row is the headings. Remaining rows are data.
      

      1.4. Generating Output Formats
      

      The sdf command is used to convert SDF to other formats. The general syntax is:
      

         sdf [options] file ...

      

      If an extension is not given (and a file is not found with that name), an extension of sdf is assumed.
      

      The most commonly used option is the -2 option. For example, to convert mydoc.sdf to HTML and PostScript, the respective commands are:
      

         sdf -2html mydoc
   sdf -2ps mydoc

      

      These commands create files called mydoc.html and mydoc.ps respectively.
      

      To convert mydoc.sdf to a set of HTML topics, the command is:
      

         sdf -2topics mydoc

      

      This creates the following files:
      

        

      • mydoc.html - the table of contents

      • mydoc_1.html - the first topic

      • mydoc_2.html - the second topic.
      

      By default, topics are created whenever a level 1 heading is encountered or a file is explicitly included. The -n option can be used to specify a different level for splitting into topics, e.g.
      

        sdf -2topics -n2 mydoc

      

      1.5. Requirements
      

      SDF requires the following:
      

        

      • Perl 5.003 or later

      • for generating PostScript, the freely available pod2ps program or SGML-Tools and LaTeX packages. Alternatively, you need a word processor which can import MIF or RTF (Adobe's FrameMaker 5.x is preferred)

      • for generating PDF, Adobe's Acrobat

      • for generating Windows Help files, a help compiler (e.g. hcp.exe).
      

      1.6. Architecture
      

      The architecture of SDF is given in the diagram below.
      

      

      

      2. Alternative Systems
      

      2.1. WYSIWYG Tools
      

      WYSIWYG (What-You-See-Is-What-You-Get) tools are great for creating small to medium-sized:
      

        

      • World Wide Web documents (i.e. HTML), or

      • paper-based documents (i.e. PostScript), or

      • Windows help files.
      

      However, the WYSIWYG approach is inefficient when it comes to creating and maintaining large documentation systems, particularly if you want high quality paper-based and on-line outputs.
      

      The reasons are:
      

        

      1. WYSIWYG is meaningless when it comes to supporting multiple formats. For example:
          

        • paper documents are formatted on fixed-size pages; on-line documents are formatted as topics displayed in user-sized windows
          

        • different browsers may display a given HTML document differently.
        

      2. For good-looking results, the formatting rules need to be tuned for each format. For example, a certain phrase may be:
          

        • a hypertext jump within HTML
          

        • emphasised using italics for paper-based formats
          

        • a pop-up window within Windows help.
        

      3. The content often needs to be tuned for each format. For example, you may wish to describe a given procedure in different ways:
          

        • in detail for a paper-based document
          

        • terse for on-line help.
        

      4. Centralised management of formatting rules and hypertext generation is essential for minimising the cost and maximising the quality of a large documentation system. By making it too easy for individual authors to customise formatting, WYSIWYG tools often make it harder for workgroups to centrally manage formatting!
      

      Nevertheless, WYSIWYG tools are often used in combination with SDF when they save time. For example, diagrams can be created in most packages and imported into SDF documents.
      

      2.2. SGML/XML
      

      The SGML/XML approach of specifying documents semantically is an extremely powerful one and SDF uses the same approach whenever possible. However, as SDF does not use document structure rules and DTDs, it is much simpler than SGML. SDF is also more readable than SGML, so high-cost authoring tools are not needed on every desktop, making SDF much cheaper to implement than SGML.
      

      Like SDF, XML has built on SGML's good ideas but minimised the overall complexity. However, XML has retained SGML's unfriendly appearance.
      

      2.3. POD
      

      In many ways, the system closest to SDF is POD (Plain Old Documentation) which is widely used in the Perl community. Like SDF, POD:
      

        

      • is simple, readable and free

      • supports a large number of output formats

      • supports literate programming (i.e. POD documentation can be directly embedded in Perl scripts and libraries)

      • is built on Perl.
      

      Currently, SDF has several advantages over POD:
      

        

      1. SDF supports more features, e.g.:
          

        • tables
          

        • figures
          

        • formatting within example text
        

      2. SDF is more extensible as sites can add their own:
          

        • paragraph and phrase styles
          

        • paragraph and phrase attributes
          

        • filters, macros, etc.
      

      Furthermore, versions 2.000beta10 and later of SDF are POD friendly:
      

        

      • POD can be converted to SDF and vice versa

      • SDF can be nested inside POD and vice versa

      • SDF is largely upwardly compatible with POD in terms of syntax and functionality.
      

      As a result, POD users can use SDF or migrate to SDF when POD isn't powerful enough. Refer to SDF for POD Users for further details.
      

      

      3. Language Overview
      

      3.1. Basic Concepts
      

      The basic concepts within SDF documents are:
      

      

      

Concept


Description


      

      

paragraph


one or more lines of text


      

      

phrase


a section of text within a paragraph


      

      

style


the type of a document, paragraph, phrase or table (e.g. H1)


      

      

macro


a command embedded in a document (e.g. !define)


      

      

variable


a named value (e.g. DOC_NAME)


      

      

filter


a rule to use when processing certain sections of text (e.g. table)


      

      

attribute


a named parameter of a paragraph, phrase or filter (e.g. jump)


      

      

expression


a literal or expression to evaluate (e.g. "Ian Clatworthy").


      

      


      Further details about these are given below.
      

      3.2. Paragraphs
      

      Paragraphs have the following format:
      

         line1
   ...
   lineN

      

      Leading and trailing whitespace on lines is generally ignored. Paragraphs are separated by:
      

        

      • blank lines

      • comment lines - first non-whitespace character is "#"

      • macros - first non-whitespace character is "!" or "=".
      

      For normal paragraphs, simply specify the text on one or more lines. For example:
      

         I like products which are simple to use and
   do what I expect. We should encourage engineers
   to design more products with these qualities.

      

      A paragraph can be given a style using the following syntax:
      

         style":"line1
   ...
   lineN

      

      Some commonly-used paragraph styles are:
      

      

      

Style


Description


      

      

N


normal paragraph (the default)


      

      

H1 .. H6


chapter heading at level 1-6


      

      

A1 .. A6


appendix heading at level 1-6


      

      

P1 .. P6


plain heading at level 1-6


      

      

Note


a single paragraph note


      

      

E


fixed-width (example) text


      

      


      For example:
      

         Note: Life is too short to drink bad wine.

      

      The result is:
      

      
Note: Life is too short to drink bad wine.

      

      3.3. Special styles
      

      For certain styles, the following syntax is also supported:
      

         special_style line1
   ...
   lineN

      

      The special styles available are:
      

      

      

Style


Description


      

      

>


fixed-width, verbatim paragraph


      

      

. .. ......


paragraph or plain list item at level 1-6


      

      

* .. ******


unordered list at level 1-6


      

      

- .. -----


unordered list at level 2-6


      

      

& .. &&&&&&


enumerated list at level 1-6


      

      

^ .. ^^^^^^


first entry in an ordered list at level 1-6


      

      

+ .. ++++++


next entry in an ordered list at level 1-6


      

      


      For example:
      

      ^ fruits:
  - peach
  - banana
+ vegetables:
  - potato
  - carrots.

      

      The result is:
      

        

      1. fruits:
          

        • peach
          

        • banana
        

      2. vegetables:
          

        • potato
          

        • carrots.
      

      3.4. Phrases
      

      A phrase is a section of text within a paragraph enclosed in the symbols {{ and }}. Like paragraphs, phrases are optionally tagged with a style.
      

      The commonly-used phrase styles are:
      

      

      

Tag


Description


Sample Output


      

      

Emphasis:


 


 


      

      

1


1st level emphasis (default)


emphasis 1


      

      

2


2nd level emphasis


emphasis 2


      

      

3


3rd level emphasis


emphasis 3


      

      

Formatting:


 


 


      

      

N


normal


some normal text


      

      

I


italic


some italic text


      

      

B


bold


some bold text


      

      

U


underline


some underline text


      

      

EX


example


some example text


      

      

Types:


 


 


      

      

EMAIL


email address


ianc@mincom.com


      

      

F (or FILE)


Filename


myfile.sdf


      

      

SECT


Section


Paragraphs


      

      

URL


Uniform Resource Locator


http://www.mincom.com


      

      

Classes:


 


 


      

      

DOC


document title


SDF User Guide


      

      

REF


reference (document code)


MTR-SDF-0002


      

      

ORG


organisation


Mincom


      

      

PRD


product


MIMS


      

      

Specials:


 


 


      

      

E (or CHAR)


escape (i.e. special character)


© 


      

      

S


spaces are non-breaking


section 2.1


      

      

IMPORT


name of a figure to import





      

      


      For single character, uppercase phrase styles, POD's [A-Z]<..> syntax can be used. For example:
      

      E:  I<Please> reply to {{EMAIL:customer@xyz.com}} quickly.

      

      The result is:
      

      Please reply to customer@xyz.com quickly.
      

      This example also illustrates the advantage of specifying documents in a logical manner:
      

        

      • when generating PostScript, the EMAIL style is mapped to italics

      • when generating HTML, the EMAIL style is mapped to a 'mailto' Uniform Resource Locator (URL).
      

      3.5. Types vs Classes
      

      A type (e.g. EMAIL) simply marks a phrase as a logical entity. Rules may be defined for processing (e.g. generating hypertext) for these types. Refer to Rule-based Hypertext Generation, later.
      

      A class (e.g. DOC) is a special kind of type where the entity must be a member of a predefined set. As a result, SDF can validate the entry name, lookup a hypertext jump and do other clever things (like replace the text with a longer name).
      

      Rules can also be defined for processing classes, although hypertext jumps are often defined for each entity in the tables which define the known entities. Refer to Centralised Hypertext Management, later.
      

      3.6. Special Phrases
      

      Special phrases are used for entering things like:
      

        

      • special symbols (like {{)

      • special characters (like ö)

      • images within paragraph text

      • the current page number in the header or footer.
      

      3.7. Macros
      

      A macro is a command which can be embedded within SDF. Macros begin with an exclamation mark (!) or equals sign (=) as the first non-whitespace character on a line. !-style macros terminate at the end of the line, unless explicitly continued using a backslash character at the end of the line. =-style macros terminate at the next blank line (ala POD).
      

      Some examples are:
      

        !define DOC_NAME   "The SDF Document Development System"
  !define DOC_AUTHOR "Ian Clatworthy"
  !build_title

      

      Some commonly-used macros are:
      

      

      

Macro


Description


      

      

init variables


initialise variables


      

      

define variable [expression]


set a variable's value


      

      

build_title


build a title page


      

      

block filter


begin a block of text


      

      

endblock


end a block of text


      

      

include file[; filter]


include another file


      

      

import file[; parameters]


import a figure


      

      


      3.8. Variables
      

      A variable is a named value. Document-wide settings are controlled in SDF using variables. Likewise, authors can define and access their own variables. In either case, the value of a variable can be referenced in a paragraph by delimiting it with the special symbols [[ and ]].
      

      For example:
      

        !define MY_EMAIL 'abc@xyz.com'
  My electronic mail address is [[MY_EMAIL]].

      

      The result is:
      

      My electronic mail address is abc@xyz.com.
      

      Some commonly used system variables are:
      

      

      

Variable


Description


      

      

DOC_NAME


the title, excluding the type (e.g. SDF)


      

      

DOC_TYPE


the title type (e.g. User Guide)


      

      

DOC_AUTHOR


the author


      

      

DOC_TOC


the number of heading levels in the table of contents


      

      

DOC_START


the time processing of the document started


      

      


      The define macro is usually used to set variables. However, variables beginning with OPT_ need to be set before processing of the document begins. The init macro is used on the top line of a document to set these variables. For example:
      

         !init OPT_STYLE="manual"

      

      3.9. Formats
      

      As the value of date-time variables is the number of seconds since January 1, 1970, a format is typically applied to them when they are embedded in text. For example:
      

        The date is [[DATE:DOC_START]].

      

      The predefined formats available include:
      

      

      

Format


Description


      

      

FULL


complete date-time format


      

      

TIME


time only


      

      

DATE


date only


      

      

CONCISE


concise date only


      

      

YEAR


4-digit year


      

      


      New formats can be created and the definitions of existing formats can be changed. Furthermore, a format can be applied to any variable (or embedded Perl expression), although the date-time formats are obviously only useful when applied to date-time values.
      

      3.10. Document styles
      

      The general type of an document can be controlled by either:
      

        

      • initialising the OPT_STYLE variable on the top line of a document

      • using sdf's -s option (which overrides the init macro).
      

      The available document styles include:
      

      

      

Style


Purpose


      

      

General:


 


      

      

document


a normal document


      

      

manual


a manual


      

      

paper


a technical paper


      

      

Administration:


 


      

      

fax


a facsimile


      

      

memo


a memorandum


      

      

minutes


minutes of a meeting


      

      


      It is relatively simple to create new document styles by inheriting details from an existing one.
      

      3.11. Filters
      

      A filter controls how a block of text is interpreted. The text is usually delimited by block and endblock macros.
      

      For example, tables are usually defined via the table filter:
      

      !block table
Option  Description
-h      display help
-o      specify the output extension
!endblock

      

      The result is:
      

      

      

Option


Description


      

      

-h


display help


      

      

-o


specify the output extension


      

      


      Other macros also support filters. These include:
      

        

      • include - include text from another file

      • execute - include the output of a system command.
      

      Some of the commonly-used filters are:
      

      

      

Filter


Description


      

      

table


the lines are a table in SDF's TBL format


      

      

example


the lines are example paragraphs


      

      

title


used to build a title block for memos, faxes, etc.


      

      

topics


include files as sub-topics


      

      

appendix


replace H1 styles with A1, etc.


      

      

plain


replace H1 styles with P1, etc.


      

      


      For example, the following macro includes another SDF file and formats it as an appendix:
      

         !include "tips.sdf"; appendix

      

      
Note: The appendix and plain filters enable authors to construct topics without needing to worry about how those topics will be used, e.g. a topic may be a chapter in one document and an appendix in another!

      

      3.12. Attributes
      

      Paragraphs and phrases can be given attributes via the syntax:
      

        style"["attributes"]" text

      

      where the syntax of attributes is:
      

        name1["="expression1]";" name2["="expression2] ...

      

      Attributes are used for specifying custom formatting, hypertext targets and jumps, indexing information, etc.
      

      Some commonly used attributes are:
      

      

      

Name


Purpose


      

      

Paragraphs:


 


      

      

align


Left, Right, Center, or Full (i.e. justified)


      

      

notoc


take this heading out of the table of contents


      

      

Phrases:


 


      

      

family


font family


      

      

size


font size


      

      

id


hypertext target tag


      

      

jump


URL (Uniform Resource Locator) to jump to


      

      


      For convenience, phrase attributes can be applied to paragraphs.
      

      For example:
      

        N[align=Center;size='12pt']
  Life is too short to drink bad wine.

      

      The result is:
      

      Life is too short to drink bad wine.
      

      

      4. Web Publishing Features
      

      4.1. Centralised Hypertext Management
      

      SDF has a generic object management feature which enables:
      

        

      1. the definition of objects in configuration files

      2. the use of those objects in documents.
      

      For example, a configuration file may have the following declaration of products:
      

        !block products; data
  Name     Jump
  SDF      http://www.mincom.com/mtr/sdf/
  MIMS     http://www.mincom.com/mims/
  !endblock

      

      If an object with a Jump attribute is specified in a document, SDF will automatically include a hypertext jump to the appropriate place. For example, the objects above could be specified in a document like this (PRD is the style used to specify a product object):
      

        The user documentation for {{PRD:MIMS}} is now
  produced using {{PRD:SDF}}.

      

      SDF has built-in support for the following classes of objects:
      

        

      1. references/documents

      2. terms/definitions

      3. organisations

      4. products.
      

      Additional classes of objects can be easily added, so workgroups can centrally manage all sorts of URLs: mail addresses, FTP sites and so on.
      

      4.2. Rule-based Hypertext Generation
      

      SDF provides a generic, rule-based feature called event processing for automating tasks like hypertext generation, index generation and custom formatting.
      

      The on macro allows you to execute an arbitrary piece of Perl code when an event occurs during document conversion. Its syntax is:
      

       !on type pattern; [id]; action

      

      where:
      

        

      • type specifies the event type

      • pattern is a Perl regular expression string, anchored at both ends, which specifies which styles (or names) the action is to be executed for

      • id is optionally used to name an event for later disabling via the off macro

      • action is the block of Perl code to execute.
      

      The types supported and the Perl symbols available in the respective actions include:
      

      

      

Type


Symbols


      

      

paragraph


$style, $text, %attr, &ParaPrepend, &ParaAppend


      

      

phrase


$style, $text, %attr


      

      

macro


$name, $args


      

      

filter


$name, $params


      

      

table


$style, %param


      

      


      Some examples are:
      

        # Make every heading a hypertext target named itself
  !on paragraph 'H\d';; $attr{'id'} = $text

  # If the target is HTML, add a line above level 1 headings
  !if $var{'OPT_TARGET'} eq 'html'
  !on paragraph 'H1';; &PrependText("Line:")
  !endif

      

      4.3. Embedded Perl Scripting
      

      As systems built by embedding scripts within HTML are typically easier to customise than systems build by generating HTML from scripts, embedded scripting is now a well established web-publishing solution.
      

      Likewise, Perl embedded in SDF can be a powerful combination providing this same flexibility with some additional benefits:
      

        

      • SDF is arguably easier to read than HTML

      • the information can be published in several formats.
      

      To embed a block of Perl code, the script filter is used. For example:
      

          !block script
    for $i ('a' .. 'z') {
        print "$i";
    }
    !endblock

      

      To embed an expression within paragraph text, the [[..]] syntax is used. For example:
      

        Hello [["wor" . "ld"]]

      

      
Note: If the expression is a single word, it is assumed to be a variable name, otherwise the expression is treated as a Perl expression.

      

      For single line scripts, the script macro can be used. For example:
      

        !script $next_version = $var{'VERSION'} + 1

      

      As shown above, SDF variables are available within Perl expressions via the var associative array.
      

      4.4. Inline HTML
      

      As HTML is constantly evolving and contains features which SDF doesn't explicitly support (e.g. frames), it is occasionally necessary to directly embed native HTML. To do this, use the inline filter. For example:
      

          !block inline
    <P>
    My name is <B>Bill</B>.
    !endblock

      

      Inlined HTML is ignored when PostScript is being generated. Likewise, if text for another format is inlined (by using the target parameter to the inline filter, say), it is ignored when HTML is generated.
      

      If you want to use embedded expressions (enclosed in [[ and ]]) and macros within the inline text, add the expand parameter like this:
      

          # If the SHOW_DATE variable is true, show the date, otherwise the time
    !block inline; expand
        !if SHOW_DATE
            <P>
            The date is [[DATE:DOC_START]].
        !else
            <P>
            The time is [[TIME:DOC_START]].
        !endif
    !endblock

      

      Likewise, you can use the INLINE phrase style within a paragraph to embed HTML within a paragraph. For example:
      

        My name is {{INLINE:<B>Bill</B>}}.

      

      

      5. Other Special Features
      

      SDF supports a number of special features which collectively make it useful for building large documentation systems like intranets and software manuals.
      

      These features are:
      

      

      

Feature


Description


      

      

Modules and Libraries


an extensible way of packaging and reusing configuration information


      

      

Reusable Topics


topics can be defined without needing to know how they are used


      

      

Conditional Text


inclusion and exclusion of certain text


      

      

Extracting Documentation


extraction of documentation embedded in source code


      

      

Programming Language Support


attractive formatting of source code


      

      

Multiple Looks


packaged document-wide presentation styles


      

      


      Further details about these are given below.
      

      5.1. Modules and Libraries
      

      A module is a normal SDF document which contains reusable information. As SDF has an open architecture, a module can provide:
      

        

      • new paragraph and phrase styles

      • new paragraph and phrase attributes

      • new macros

      • new filters

      • declarations of objects

      • formatting rules.
      

      A library is a directory containing modules with a common theme. Importantly, a library can inherit information from other libraries, making it easy to:
      

        

      1. create new libraries, and

      2. maximise the reuse of configuration information.
      

      5.2. Reusable Topics
      

      Documentation systems can be developed as a set of topics, where each topic uses H-style headings, starting at H1. A topic does not generally need to know how it will be used - each document including a given topic can:
      

        

      • "slide" the headings levels up or down as needed

      • change the heading styles as needed.
      

      For example:
      

       !include "types.sdf"

 H1: Subroutines
 !block topics
 Topic
 create
 delete
 update
 !endblock

 !include "errors.sdf"; appendix

      

      In this example, the results are:
      

        

      1. types.sdf will be included into the document unmodified

      2. the documentation for each subroutine (create.sdf, delete.sdf and delete.sdf) will be included as sub-sections in the Subroutines chapter, and the heading levels will be modified accordingly

      3. errors.sdf will be included as an appendix.
      

      
Note: Providing tabular data to a filter is a common idiom in SDF. In this case, the only column provided is the Topic column.

      

      5.3. Conditional Text
      

      Sections of text can be conditionally included or excluded using the following macros:
      

         !if condition
   !elsif condition
   !else
   !endif

      

      These macros allow you to tune the output for different audiences and different target formats.
      

      5.4. Extracting Documentation
      

      Software documentation can be embedded within comments in source code (and text-based data files) and extracted by the sdfget utility. The name, order and formatting of extracted sections can be controlled via report files.
      

      Consider the following scenarios:
      

        

      • a User Guide may need to extract sections called Purpose, Description and Examples

      • a Technical Reference may need to extract sections called Internal Architecture and Maintenance Tips.
      

      Creating the necessary reports and mapping the extraction commands to SDF macros is relatively easy.
      

      5.5. Programming Language Support
      

      Blocks of source code can be nicely formatted via the lang parameter to the example filter. For example:
      

      !block example; lang='Perl'
sub hello {
    local($planet) = @_;

    # Output a nice message
    print "hello $planet!\n";
}
!endblock

      

      If SDF encounters an unknown filter which is defined as a programming language, the example filter is implicit. Therefore, the above example can be simplified to:
      

      !block Perl
sub hello {
    local($planet) = @_;

    # Output a nice message
    print "hello $planet!\n";
}
!endblock

      

      In either case, the result is:
      

      sub hello {
    local($planet) = @_;

    # Output a nice message
    print "hello $planet!\n";
}

      

      There is built-in support for numerous languages, including Perl, C, C++, Java, Delphi and CORBA IDL. New language definitions can be easily added (vgrind definitions are used).
      

      Pretty printing of source code is directly supported by sdf's -P option. For example:
      

        sdf -2ps -Psh myscript
  sdf -2ps -P myapp.c
  sdf -2ps -P -N5 mylib.pl

      

      The language to use can be specified as a parameter. The default language is derived from the extension of the file. The -N option adds line numbers at the frequency given.
      

      5.6. Multiple Looks
      

      The overall appearance of an document can be controlled by either:
      

        

      • initialising the OPT_LOOK variable on the top line of a document

      • using sdf's -k option (which overrides the init macro).
      

      The available looks include:
      

        

      • simple - the default look, useful for general documentation

      • fancy - a look suitable for user documentation

      • infomap - a look based on Information Mapping™ 

      • overhead - a look suitable for overhead transparencies.
      

      It is relatively simple to create new looks by inheriting details from an existing one.
      

      
Note: At this time (January 98), multiple looks are currently only supported for paper documentation generated via FrameMaker. Multiple look support will hopefully be added to other SDF output drivers during 1998.

      

      

      6. Other Issues
      

      6.1. Why should I use SDF?
      

      The common reasons for using SDF are:
      

        

      1. it provides a single-source solution for high quality PostScript, HTML, Windows help, etc.

      2. it saves time

      3. it is highly portable

      4. it is free.
      

      6.1.1. High quality outputs from a single source
      

      As SDF can be used to specify a logical definition of a document, it is reasonably good at maintaining quality across the different output formats it supports.
      

      6.1.2. Saving time
      

      SDF often saves time in a number of ways:
      

        

      1. developers can focus on document content and leave the formatting to SDF, i.e. minimal effort is required for good formatting

      2. developers can use their favorite text editor, rather than switching between two different tools for source code and documents

      3. documentation can be extracted or generated from source code

      4. hypertext can be automatically generated using event processing or object management.
      

      6.1.3. High portability
      

      SDF documents are plain text files which can be created on any platform. The underlying technology is Perl, a highly portable scripting language available on all commonly used platforms.
      

      6.1.4. SDF is free
      

      SDF is freely available for commercial and non-commercial use. However, like most software packages, there are costs to be considered when using SDF. These include:
      

        

      1. training costs

      2. the cost of coverting existing documents, if you wish to do this.
      

      6.2. Converting Documents to SDF
      

      For POD documents, SDF contains a pod2sdf conversion program.
      

      For other formats, the easiest way to convert existing documents is usually to convert them to plain text and add the necessary markup. For Word users, an RTF-to-SDF converter is available.
      

      In any case, remember that:
      

        

      1. most document formats are physical markup languages, and

      2. the main benefits of SDF come from specifying logical documents.
      

      Therefore, regardless of what conversion tools you use, expect to do some manual changes.
      

      6.3. Further Information
      

      The SDF home page URL is http://www.mincom.com/mtr/sdf. From the home page, you can:
      

        

      • download the latest software, documentation and templates

      • browse the FAQ

      • report defects

      • suggest enhancements

      • visit the SDF Resource Center.
      

      SDF is also available using anonymous ftp. The URL of the base directory is ftp://ftp.mincom.com/pub/mtr/sdf. The latest release is available in a variety of formats.
      

      The following mailing lists are available:
      


      To subscribe to these lists, send email to sdf-users-request@mincom.com and/or sdf-bugs-request@mincom.com for instructions on using factotum, the majordomo variant that manages these lists. In short, send email to factotum@mincom.com with a message body of subscribe sdf-users or subscribe sdf-bugs.
      

      

      7. Summary
      

      By using a logical document approach, where content and formatting are largely separated, SDF delivers high-quality Web-based and paper documentation from a single source. Importantly, the SDF language is easier for (most!) humans to read and write than alternatives like SGML or XML.
      

      In addition, SDF lowers the cost of document production by providing a number of features for managing large documentation systems. These features include:
      

        

      1. rule-based hypertext generation, index generation and formatting

      2. centralised hypertext management

      3. an extensible way of packaging and reusing configuration information

      4. reusable topics

      5. conditional text, and

      6. extraction of documentation embedded in source code.
      

      If all else fails, Perl scripts can be directly embedded in SDF documents to generate the output required!
      

      Finally, as SDF is freely available to everyone, the costs associated with using SDF are relatively low.
      

      

      Credits
      

      Thanks to Tim Hudson (tjh@cryptsoft.com) for being SDF's biggest fan. Tim has assisted in design, fixed bugs, added features, promoted SDF to many of its current user base and generally helped with SDF whenever time permitted. Thanks also to Chris Moran (chris.moran@mincom.com) for maintaining the SDF Home Page, assisting in design, reviewing documents, etc. Many other Mincom colleagues have assisted with SDF, particularly David Cox and Craig Willis. Thanks to everyone involved.
      

      Thanks also to my former Leeds and Northrup Australia colleagues, particularly Tom Beale, Craig Gibbings and Greg Birnie, for inspiring my initial interest in literate programming.
      

      The initial version of the mif2rtf program is Copyright 1992 by Convex Computer Corporation, Richardson, Texas. (The full copyright notice and permission notice is included in the SDF distribution.)
      

      

      Trademarks
      

      FrameMaker, FrameViewer, Acrobat, PDF and PostScript are trademarks of Adobe Systems Incorporated.
      

      Delphi is a trademark of Borland International, Incorporated.
      

      Windows is a trademark of Microsoft Corporation.
      

      

      

      

      Home | Catalog
      

      

      



xtracted sections can bsdf-2.001/doc/paper/sdfarch.eps010064400042570001753000001242600645305327000161260ustar00iancmtr00000400000236%!PS-Adobe-3.0 EPSF-3.0
%%Creator: ImageMark Software Labs
%%For: () ()
%%Title: H:\SDF\WIP\DOC\PAPER\SDFARCH.EPS
%%CreationDate: () ()
%%BoundingBox: 0.0000 0.0000 444.7500 428.2500

%%DocumentProcessColors: Black
%%DocumentFonts: Helvetica
%%+Helvetica-Bold

%%DocumentSuppliedResources: procset Adobe_packedarray 2.0 0
%%+ procset Adobe_cmykcolor 1.1 0
%%+ procset Adobe_cshow 1.1 0
%%+ procset Adobe_customcolor 1.0 0
%%+ procset Adobe_typography_AI3 1.0 0
%%+ procset Adobe_Illustrator_AI3 1.0 0
%AI3_ColorUsage: Black&White
%AI3_TemplateBox: 0.0000 0.0000 444.7500 428.2500

%AI3_TileBox: 0.0000 0.0000 444.7500 428.2500

%AI3_DocumentPreview: None
%%Template:
%%PageOrigin:0.0000 0.0000

%%EndComments
%%BeginProlog
%%BeginResource: procset Adobe_packedarray 2.0 0
%%Title: (Packed Array Operators)
%%Version: 2.0
%%CreationDate: (8/2/90) ()
%%Copyright: ((C) 1987-1990 Adobe Systems Incorporated All Rights Reserved)
userdict /Adobe_packedarray 5 dict dup begin put
/initialize
{
/packedarray where
{
pop
}
{
Adobe_packedarray begin
Adobe_packedarray
{
dup xcheck
{
bind
} if
userdict 3 1 roll put
} forall
end
} ifelse
} def
/terminate
{
} def
/packedarray
{
array astore readonly
} def
/setpacking
{
pop
} def
/currentpacking
{
false
} def
currentdict readonly pop end
%%EndResource

Adobe_packedarray /initialize get exec

%%Title: (CMYK Color Operators)
%%Version: 1.1 
%%CreationDate: (1/23/89) ()
%%Copyright: ((C) 1987-1990 Adobe Systems Incorporated All Rights Reserved)
currentpacking true setpacking
userdict /Adobe_cmykcolor 4 dict dup begin put
/initialize
{
/setcmykcolor where
{
pop
}
{
userdict /Adobe_cmykcolor_vars 2 dict dup begin put
/_setrgbcolor
/setrgbcolor load def
/_currentrgbcolor
/currentrgbcolor load def
Adobe_cmykcolor begin
Adobe_cmykcolor
{
dup xcheck
{
bind
} if
pop pop
} forall
end
end
Adobe_cmykcolor begin
} ifelse
} def
/terminate
{
currentdict Adobe_cmykcolor eq
{
end
} if
} def
/setcmykcolor
{
1 sub 4 1 roll
3
{
3 index add neg dup 0 lt
{
pop 0
} if
3 1 roll
} repeat
Adobe_cmykcolor_vars /_setrgbcolor get exec
pop
} def 
/currentcmykcolor
{
Adobe_cmykcolor_vars /_currentrgbcolor get exec
3
{
1 sub neg 3 1 roll
} repeat
0
} def
currentdict readonly pop end
setpacking

%%EndResource

%%BeginResource: procset Adobe_cshow 1.1 0
%%Title: (cshow Operator)
%%Version: 1.1 
%%CreationDate: (1/23/89) ()
%%Copyright: ((C) 1987-1990 Adobe Systems Incorporated All Rights Reserved)
currentpacking true setpacking
userdict /Adobe_cshow 3 dict dup begin put
/initialize
{
/cshow where
{
pop
}
{
userdict /Adobe_cshow_vars 1 dict dup begin put
/_cshow 
{} def
Adobe_cshow begin
Adobe_cshow
{
dup xcheck
{
bind
} if
userdict 3 1 roll put
} forall
end
end
} ifelse
} def
/terminate
{
} def
/cshow
{
exch
Adobe_cshow_vars
exch /_cshow
exch put
{
0 0 Adobe_cshow_vars /_cshow get exec
} forall
} def
currentdict readonly pop end
setpacking


%%EndResource

%%BeginResource: procset Adobe_customcolor 1.0 0
%%Title: (Custom Color Operators)
%%Version: 1.0 
%%CreationDate: (5/9/88) ()
%%Copyright: ((C) 1987-1990 Adobe Systems Incorporated All Rights Reserved)
currentpacking true setpacking
userdict /Adobe_customcolor 5 dict dup begin put
/initialize
{
/setcustomcolor where
{
pop
}
{
Adobe_customcolor begin
Adobe_customcolor
{
dup xcheck
{
bind
} if
pop pop
} forall
end
Adobe_customcolor begin
} ifelse
} def
/terminate
{
currentdict Adobe_customcolor eq
{
end
} if
} def
/findcmykcustomcolor
{
5 packedarray
}  def
/setcustomcolor
{
exch
aload pop pop
4
{
4 index mul 4 1 roll
} repeat
5 -1 roll pop
setcmykcolor
} def
/setoverprint
{
pop
} def
currentdict readonly pop end
setpacking
%%EndResource 



%%BeginResource: procset Adobe_typography_AI3 1.0 0
%%Title: (Typography Operators)%%Version: 1.0
%%CreationDate:(5/31/90) ()
%%Copyright: ((C) 1987-1990 Adobe Systems Incorporated All Rights Reserved)
currentpacking true setpacking
userdict /Adobe_typography_AI3 46 dict dup begin put
/initialize
{
/TZ
where
{
pop
}
{
Adobe_typography_AI3 begin
Adobe_typography_AI3
{
dup xcheck
{
bind
} if
pop pop
} forall
end
Adobe_typography_AI3 begin
} ifelse
} def
/terminate
{
currentdict Adobe_typography_AI3 eq
{
end
} if
} def
/modifyEncoding
{
/_tempEncode exch ddef
/_pntr 0 ddef
{
counttomark -1 roll
dup type dup /marktype eq   
{
pop pop exit
}
{
/nametype eq
{
_tempEncode /_pntr dup load dup 3 1 roll 1 add ddef 3 -1 roll
put
}
{
/_pntr exch ddef
}
ifelse
}
ifelse
}
loop 
_tempEncode
}
def
/TE 
{
StandardEncoding 256 array copy modifyEncoding 
/_nativeEncoding exch def
} def
/TZ  
{
/_useNativeEncoding exch def
pop pop
findfont dup length 2 add dict
begin
mark exch
{
1 index /FID ne { def } if cleartomark mark
}
forall
pop
/FontName exch def
counttomark 0 eq
{
Encoding StandardEncoding eq 1 _useNativeEncoding eq and
{
/Encoding _nativeEncoding def
}
if
cleartomark
}
{ 
/Encoding load 256 array copy 
modifyEncoding /Encoding exch def
}
ifelse  
FontName currentdict
end
definefont pop
}
def
/tr
{
_ax _ay 3 2 roll
} def
/trj 
{
_cx _cy _sp _ax _ay 6 5 roll
} def


/a0
{
/Tx 
{
dup 
currentpoint 3 2 roll
tr _psf
newpath moveto
tr _ctm _pss
} ddef
/Tj 
{
dup
currentpoint 3 2 roll
trj _pjsf
newpath moveto
trj _ctm _pjss
} ddef
} def
/a1
{
W B
} def
/e0
{
/Tx 
{
tr _psf
} ddef
/Tj 
{
trj _pjsf
} ddef
} def
/e1
{
W F 
} def
/i0
{
/Tx
{
tr sp
} ddef
/Tj
{
trj jsp
} ddef
} def
/o0
{
/Tx
{
tr sw rmoveto
} ddef
/Tj
{
trj swj rmoveto
} ddef
} def
/r0
{
/Tx
{
tr _ctm _pss
} ddef
/Tj
{
trj _ctm _pjss
} ddef
} def
/r1
{
W S
} def
/To
{
pop _ctm currentmatrix pop
} def
/TO
{
Te _ctm setmatrix newpath
} def
/Tp
{
pop _tm astore pop _ctm setmatrix 
2 dict begin /W {} def /h {} def
} def
/TP
{
end
iTm 0 0 moveto
} def
/Tr
{
Te currentpoint newpath moveto
dup 8 eq {pop 0} {dup 9 eq {pop 1} if} ifelse
dup /_render exch ddef
_renderStart exch get load exec
} def
/iTm 
{
_ctm setmatrix _tm concat 0 _rise translate _hs 1 scale
} def
/Te
{
_render -1 eq {} {_renderEnd _render get dup null ne {load exec} {pop} ifelse} ifelse
/_render -1 ddef
} def
/Tf
{
dup 1000 div /_fScl exch ddef
exch findfont exch scalefont setfont
} def
/Tl
{
pop
0 exch _leading astore pop
} def
/Tt 
{
pop
} def
/TW
{
3 npop
} def
/Tw
{
/_cx exch ddef
} def
/Tc
{
/_ax exch ddef
} def
/Ts
{
/_rise exch ddef
currentpoint
iTm
moveto
} def
/Ti
{
3 npop
} def
/Tz
{
100 div /_hs exch ddef
iTm
} def
/Tq 
{
pop
} def
/TX {pop} def
/Tk
{
exch pop _fScl mul neg 0 rmoveto
} def
/T- 
{
_hyphen Tx
} def
/TS
{
0 eq {Tx} {Tj} ifelse
} def
currentdict readonly pop end
setpacking
%%EndResource




%%BeginResource: procset Adobe_Illustrator_AI3 1.0 0
%%Title: (Adobe Illustrator (R) Version 3.0 Full Prolog)
%%Version: 1.0 
%%CreationDate: (7/22/89) ()
%%Copyright: ((C) 1987-1990 Adobe Systems Incorporated All Rights Reserved)
currentpacking true setpacking
userdict /Adobe_Illustrator_AI3 71 dict dup begin put
/initialize
{
userdict /Adobe_Illustrator_AI3_vars 55 dict dup begin put
/_lp /none def
/_pf {} def
/_ps {} def
/_psf {} def
/_pss {} def
/_pjsf {} def
/_pjss {} def
/_pola 0 def
/_doClip 0 def
/cf currentflat def
/_tm matrix def
/_renderStart [/e0 /r0 /a0 /o0 /i0 /i0 /i0 /i0] def 
/_renderEnd [null null null null /e1 /r1 /a1 /clip] def
/_render -1 def
/_rise 0 def
/_ax 0 def
/_ay 0 def
/_cx 0 def
/_cy 0 def
/_leading [0 0] def
/_ctm matrix def
/_mtx matrix def
/_sp 16#020 def
/_hyphen (-) def
/_fScl 0 def
/_cnt 0 def
/_hs 1 def
/_nativeEncoding 0 def
/_useNativeEncoding 0 def
/_tempEncode 0 def
/_pntr 0 def
/Tx {} def
/Tj {} def
/CRender {} def
/_AI3_savepage {} def
/_gf null def
/_cf 4 array def
/_if null def
/_of false def
/_fc {} def
/_gs null def
/_cs 4 array def
/_is null def
/_os false def
/_sc {} def
/_pd 1 dict def
/_ed 15 dict def
/_pm matrix def
/_fm null def
/_fd null def
/_fdd null def
/_sm null def
/_sd null def
/_sdd null def
/_i null def
Adobe_Illustrator_AI3 begin
Adobe_Illustrator_AI3 dup /nc get begin
{
dup xcheck
{
bind
} if
pop pop
} forall
end
end
end
Adobe_Illustrator_AI3 begin
Adobe_Illustrator_AI3_vars begin
newpath
} def
/terminate
{
end
end
} def


/_
null def
/ddef
{
Adobe_Illustrator_AI3_vars 3 1 roll put
} def
/xput
{
dup load dup length exch maxlength eq
{
dup dup load dup
length 2 mul dict copy def
} if
load begin def end
} def
/npop
{
{
pop
} repeat
} def


/sw
{
dup length exch stringwidth
exch 5 -1 roll 3 index 1 sub mul add
4 1 roll 3 1 roll 1 sub mul add
} def
/swj
{
dup 4 1 roll
dup length exch stringwidth 
exch 5 -1 roll 3 index 1 sub mul add
4 1 roll 3 1 roll 1 sub mul add 
6 2 roll /_cnt 0 ddef
{1 index eq {/_cnt _cnt 1 add ddef} if} forall pop
exch _cnt mul exch _cnt mul 2 index add 4 1 roll 2 index add 4 1 roll pop pop
} def
/ss
{
4 1 roll
{
2 npop 
(0) exch 2 copy 0 exch put pop
gsave
false charpath currentpoint
4 index setmatrix
stroke
grestore
moveto
2 copy rmoveto
} exch cshow
3 npop
} def
/jss
{
4 1 roll
{
2 npop 
(0) exch 2 copy 0 exch put 
gsave
_sp eq 
{
exch 6 index 6 index 6 index 5 -1 roll widthshow  
currentpoint
}
{
false charpath currentpoint
4 index setmatrix stroke
}ifelse
grestore
moveto
2 copy rmoveto
} exch cshow
6 npop
} def
/sp
{
{
2 npop (0) exch
2 copy 0 exch put pop
false charpath
2 copy rmoveto
} exch cshow
2 npop
} def
/jsp
{
{
2 npop 
(0) exch 2 copy 0 exch put 
_sp eq 
{
exch 5 index 5 index 5 index 5 -1 roll widthshow  
}
{
false charpath
}ifelse
2 copy rmoveto
} exch cshow
5 npop
} def
/pl
{
transform
0.25 sub round 0.25 add exch
0.25 sub round 0.25 add exch
itransform
} def
/setstrokeadjust where
{pop true setstrokeadjust
/c
{
curveto
} def
/C
/c load def
/v
{
currentpoint 6 2 roll curveto
} def
/V
/v load def
/y
{
2 copy curveto
} def
/Y
/y load def
/l
{
lineto
} def
/L
/l load def
/m
{
moveto
} def
}
{
/c
{
pl curveto
} def
/C
/c load def
/v
{
currentpoint 6 2 roll pl curveto
} def
/V
/v load def
/y
{
pl 2 copy curveto
} def
/Y
/y load def
/l
{
pl lineto
} def
/L
/l load def
/m
{
pl moveto
} def
} ifelse
/d
{
setdash
} def
/cf {} def
/i
{
dup 0 eq
{
pop cf
} if
setflat
} def
/j
{
setlinejoin
} def
/J
{
setlinecap
} def
/M
{
setmiterlimit
} def
/w
{
setlinewidth
} def
/H {} def /h { closepath } def /N { _pola 0 eq {

_doClip 1 eq {clip /_doClip 0 ddef} if newpath } {

/CRender {N} ddef }ifelse } def /n {N} def

/F
{
_pola 0 eq 
{
_doClip 1 eq 
{
gsave _pf grestore clip newpath /_lp /none ddef _fc 
/_doClip 0 ddef
}
{
_pf
}ifelse
} 
{
/CRender {F} ddef
}ifelse
} def
/f
{
closepath
F
} def
/S
{
_pola 0 eq 
{
_doClip 1 eq 
{
gsave _ps grestore clip newpath /_lp /none ddef _sc 
/_doClip 0 ddef
}
{
_ps
}ifelse
} 
{
/CRender {S} ddef
}ifelse
} def
/s
{
closepath
S
} def
/B
{
_pola 0 eq 
{
_doClip 1 eq
gsave F grestore 
{
gsave S grestore clip newpath /_lp /none ddef _sc
/_doClip 0 ddef
} 
{
S
}ifelse
}
{
/CRender {B} ddef
}ifelse
} def
/b
{
closepath
B
} def
/W
{
/_doClip 1 ddef
} def
/*
{
count 0 ne 
{
dup type (stringtype) eq {pop} if
} if 
_pola 0 eq {newpath} if
} def
/u
{} def
/U
{} def
/q
{_pola 0 eq {gsave} if
} def
/Q
{
_pola 0 eq {grestore} if
} def
/*u
{
_pola 1 add /_pola exch ddef
} def
/*U
{
_pola 1 sub /_pola exch ddef 
_pola 0 eq {CRender} if
} def
/D
{pop} def
/*w
{} def
/*W
{} def
/`
{
/_i save ddef
6 1 roll 4 npop
concat
userdict begin
/showpage {} def
false setoverprint
pop
} def
/~ { end _i restore } def
/@
{} def
/&
{} def
/O
{
0 ne
/_of exch ddef
/_lp /none ddef
} def
/R
{
0 ne
/_os exch ddef
/_lp /none ddef
} def
/g
{
/_gf exch ddef
/_fc
{
_lp /fill ne
{
_of setoverprint
_gf setgray
/_lp /fill ddef
} if
} ddef
/_pf
{
_fc
fill
} ddef
/_psf
{
_fc
ashow
} ddef
/_pjsf
{
_fc
awidthshow
} ddef
/_lp /none ddef
} def
/G
{
/_gs exch ddef
/_sc
{
_lp /stroke ne
{
_os setoverprint
_gs setgray
/_lp /stroke ddef
} if
} ddef
/_ps
{
_sc
stroke
} ddef
/_pss
{
_sc
ss
} ddef
/_pjss
{
_sc
jss
} ddef
/_lp /none ddef
} def
/k
{
_cf astore pop
/_fc
{
_lp /fill ne
{
_of setoverprint
_cf aload pop setcmykcolor
/_lp /fill ddef
} if
} ddef
/_pf
{
_fc
fill
} ddef
/_psf
{
_fc
ashow
} ddef
/_pjsf
{
_fc
awidthshow
} ddef
/_lp /none ddef
} def
/K
{
_cs astore pop
/_sc
{
_lp /stroke ne
{
_os setoverprint
_cs aload pop setcmykcolor
/_lp /stroke ddef
} if
} ddef
/_ps
{
_sc
stroke
} ddef
/_pss
{
_sc
ss
} ddef
/_pjss
{
_sc
jss
} ddef
/_lp /none ddef
} def
/x
{
/_gf exch ddef
findcmykcustomcolor
/_if exch ddef
/_fc
{
_lp /fill ne
{
_of setoverprint
_if _gf 1 exch sub setcustomcolor
/_lp /fill ddef
} if
} ddef
/_pf
{
_fc
fill
} ddef
/_psf
{
_fc
ashow
} ddef
/_pjsf
{
_fc
awidthshow
} ddef
/_lp /none ddef
} def
/X
{
/_gs exch ddef
findcmykcustomcolor
/_is exch ddef
/_sc
{
_lp /stroke ne
{
_os setoverprint
_is _gs 1 exch sub setcustomcolor
/_lp /stroke ddef
} if
} ddef
/_ps
{
_sc
stroke
} ddef
/_pss
{
_sc
ss
} ddef
/_pjss
{
_sc
jss
} ddef
/_lp /none ddef
} def
/dp
{
dup null eq
{
pop
_dp 0 ne
{
0 1 _dp 1 sub _dl mod
{
_da exch get 3 get
} for
_dp 1 sub _dl mod 1 add packedarray
_da 0 get aload pop 8 -1 roll 5 -1 roll pop 4 1 roll
definepattern pop
} if
}
{
_dp 0 ne _dp _dl mod 0 eq and
{
null dp
} if
7 packedarray _da exch _dp _dl mod exch put
_dp _dl mod _da 0 get 4 get 2 packedarray
/_dp _dp 1 add def
} ifelse
} def
/E
{
_ed begin
dup 0 get type /arraytype ne
{
0
{
dup 1 add index type /arraytype eq
{
1 add
}
{
exit
} ifelse
} loop
array astore
} if
/_dd exch def
/_ury exch def
/_urx exch def
/_lly exch def
/_llx exch def
/_n exch def
/_y 0 def
/_dl 4 def
/_dp 0 def
/_da _dl array def
0 1 _dd length 1 sub
{
/_d exch _dd exch get def
0 2 _d length 2 sub
{
/_x exch def
/_c _d _x get _ ne def
/_r _d _x 1 add get cvlit def
_r _ ne
{
_urx _llx sub _ury _lly sub [1 0 0 1 0 0] 
[
/save cvx
_llx neg _lly neg /translate cvx
_c
{
nc /begin cvx
} if
_r dup type /stringtype eq
{
cvx
}
{
{exec} /forall cvx
} ifelse
_c
{
/end cvx
} if
/restore cvx
] cvx
/_fn 12 _n length add string def
_y _fn cvs pop
/_y _y 1 add def
_fn 12 _n putinterval
_fn _c false dp
_d exch _x 1 add exch put
} if
} for
} for
null dp
_n _dd /_pd
end xput
} def
/fc
{
_fm dup concatmatrix pop
} def
/p
{
/_fm exch ddef
9 -2 roll _pm translate fc
7 -2 roll _pm scale fc
5 -1 roll _pm rotate fc
4 -2 roll exch 0 ne
{
dup _pm rotate fc
1 -1 _pm scale fc
neg _pm rotate fc
}
{
pop
} ifelse
dup _pm rotate fc
exch dup sin exch cos div 1 0 0 1 0 6 2 roll
_pm astore fc
neg _pm rotate fc
_pd exch get /_fdd exch ddef
/_pf
{
save
0 1 _fdd length 1 sub
{
/_fd exch _fdd exch get ddef
_fd
0 2 _fd length 2 sub
{
gsave
2 copy get dup _ ne
{
cvx exec _fc
}
{
pop
} ifelse
2 copy 1 add get dup _ ne
{
aload pop findfont _fm
patternfill
}
{
pop
fill
} ifelse
grestore
pop
} for
pop
} for
restore
newpath
} ddef
/_psf
{
save
0 1 _fdd length 1 sub
{
/_fd exch _fdd exch get ddef
_fd
0 2 _fd length 2 sub
{
gsave
2 copy get dup _ ne
{
cvx exec _fc
}
{
pop
} ifelse
2 copy 1 add get dup _ ne
{
aload pop findfont _fm
9 copy 6 npop patternashow
}
{
pop
6 copy 3 npop ashow
} ifelse
grestore
pop
} for
pop
} for
restore

sw rmoveto
} ddef
/_pjsf
{
save
0 1 _fdd length 1 sub
{
/_fd exch _fdd exch get ddef
_fd
0 2 _fd length 2 sub
{
gsave
2 copy get dup _ ne
{
cvx exec _fc
}
{
pop
} ifelse
2 copy 1 add get dup _ ne
{
aload pop findfont _fm
12 copy 6 npop patternawidthshow
}
{
pop 9 copy 3 npop awidthshow
} ifelse
grestore
pop
} for
pop
} for
restore
swj rmoveto
} ddef
/_lp /none ddef
} def
/sc
{
_sm dup concatmatrix pop
} def
/P
{
/_sm exch ddef
9 -2 roll _pm translate sc
7 -2 roll _pm scale sc
5 -1 roll _pm rotate sc
4 -2 roll exch 0 ne
{
dup _pm rotate sc
1 -1 _pm scale sc
neg _pm rotate sc
}
{
pop
} ifelse
dup _pm rotate sc
exch dup sin exch cos div 1 0 0 1 0 6 2 roll
_pm astore sc
neg _pm rotate sc
_pd exch get /_sdd exch ddef
/_ps
{
save
0 1 _sdd length 1 sub
{
/_sd exch _sdd exch get ddef
_sd
0 2 _sd length 2 sub
{
gsave
2 copy get dup _ ne
{
cvx exec _sc
}
{
pop
} ifelse
2 copy 1 add get dup _ ne
{
aload pop findfont _sm
patternstroke
}
{
pop stroke
} ifelse
grestore
pop
} for
pop
} for
restore
newpath
} ddef
/_pss
{
save
0 1 _sdd length 1 sub
{
/_sd exch _sdd exch get ddef
_sd
0 2 _sd length 2 sub
{
gsave
2 copy get dup _ ne
{
cvx exec _sc
}
{
pop
} ifelse
2 copy 1 add get dup _ ne
{
aload pop findfont _sm
10 copy 6 npop patternashowstroke
}
{
pop 7 copy 3 npop ss
} ifelse
grestore
pop
} for
pop
} for
restore
pop sw rmoveto
} ddef
/_pjss
{
save
0 1 _sdd length 1 sub
{
/_sd exch _sdd exch get ddef
_sd
0 2 _sd length 2 sub
{
gsave
2 copy get dup _ ne
{
cvx exec _sc
}
{
pop
} ifelse
2 copy 1 add get dup _ ne
{
aload pop findfont _sm
13 copy 6 npop patternawidthshowstroke
}
{
pop 10 copy 3 npop jss
} ifelse
grestore
pop
} for
pop
} for
restore
pop swj rmoveto
} ddef
/_lp /none ddef
} def


/A
{
pop
} def


/nc 3 dict def
nc begin
/setgray
{
pop
} bind def
/setcmykcolor
{
4 npop
} bind def
/setcustomcolor
{
2 npop
} bind def
currentdict readonly pop end
/Z {findfont begin currentdict dup length dict begin
{1 index /FID ne {def} {pop pop} ifelse} forall /FontName exch def dup length 0 ne
{/Encoding Encoding 256 array copy def 0 exch {dup type /nametype eq
{Encoding 2 index 2 index put pop 1 add} {exch pop} ifelse} forall} if pop
currentdict dup end end /FontName get exch definefont pop} bind def
currentdict readonly pop end
setpacking
/annotatepage
{
} def

%%EndResource


%AI3-Grid.0 0 0 0 0 0 0 2
%%EndProlog
%%BeginSetup
Adobe_cmykcolor /initialize get exec
Adobe_cshow /initialize get exec
Adobe_customcolor /initialize get exec
Adobe_typography_AI3 /initialize get exec
Adobe_Illustrator_AI3 /initialize get exec
%%BeginEncoding:_Helvetica Helvetica
[
5/breve/dotaccent 11/ogonek/caron 14/dotlessi 39/quotesingle
94/circumflex 96/grave 126/tilde 145/quoteleft/quoteright
/quotedblleft/quotedblright/bullet/endash/emdash/ring 164/currency
166/brokenbar168/dieresis/copyright/ordfeminine 172/logicalnot
/minus/registered/macron/degree/plusminus/twosuperior/threesuperior
/acute/mu 183/periodcentered/cedilla/onesuperior/ordmasculine
188/onequarter/onehalf/threequarters 192/Agrave/Aacute/Acircumflex
/Atilde/Adieresis/Aring/AE/Ccedilla/Egrave/Eacute/Ecircumflex
/Edieresis/Igrave/Iacute/Icircumflex/Idieresis/Eth/Ntilde/Ograve
/Oacute/Ocircumflex/Otilde/Odieresis/multiply/Oslash/Ugrave/Uacute
/Ucircumflex/Udieresis/Yacute/Thorn/germandbls/agrave/aacute/acircumflex
/atilde/adieresis/aring/ae/ccedilla/egrave/eacute/ecircumflex/edieresis/igrave
/iacute/icircumflex/idieresis/eth/ntilde/ograve/oacute/ocircumflex/otilde
/odieresis/divide/oslash/ugrave/uacute/ucircumflex/udieresis/yacute/thorn
/ydieresis
]  /_Helvetica/Helvetica Z
%%EndEncoding
%%BeginEncoding:_Helvetica-Bold Helvetica-Bold
[
5/breve/dotaccent 11/ogonek/caron 14/dotlessi 39/quotesingle
94/circumflex 96/grave 126/tilde 145/quoteleft/quoteright
/quotedblleft/quotedblright/bullet/endash/emdash/ring 164/currency
166/brokenbar168/dieresis/copyright/ordfeminine 172/logicalnot
/minus/registered/macron/degree/plusminus/twosuperior/threesuperior
/acute/mu 183/periodcentered/cedilla/onesuperior/ordmasculine
188/onequarter/onehalf/threequarters 192/Agrave/Aacute/Acircumflex
/Atilde/Adieresis/Aring/AE/Ccedilla/Egrave/Eacute/Ecircumflex
/Edieresis/Igrave/Iacute/Icircumflex/Idieresis/Eth/Ntilde/Ograve
/Oacute/Ocircumflex/Otilde/Odieresis/multiply/Oslash/Ugrave/Uacute
/Ucircumflex/Udieresis/Yacute/Thorn/germandbls/agrave/aacute/acircumflex
/atilde/adieresis/aring/ae/ccedilla/egrave/eacute/ecircumflex/edieresis/igrave
/iacute/icircumflex/idieresis/eth/ntilde/ograve/oacute/ocircumflex/otilde
/odieresis/divide/oslash/ugrave/uacute/ucircumflex/udieresis/yacute/thorn
/ydieresis
]  /_Helvetica-Bold/Helvetica-Bold Z
%%EndEncoding
%%EndSetup
u
  0.000 0.000 0.000 0.000 k
 [] 0 d
0.2500 w
  0.000 0.000 0.000 1.000 K
1 j
  178.7500 290.7500 m
  179.0000 293.2500 L
  180.0000 295.7500 L
  181.5000 298.0000 L
  184.0000 300.2500 L
  186.5000 302.0000 L
  190.0000 303.7500 L
  193.5000 305.2500 L
  197.7500 306.5000 L
  202.2500 307.5000 L
  207.0000 308.2500 L
  211.7500 308.5000 L
  216.5000 308.5000 L
  221.2500 308.2500 L
  226.0000 307.5000 L
  230.5000 306.5000 L
  234.5000 305.2500 L
  238.2500 303.7500 L
  241.7500 302.0000 L
  244.2500 300.2500 L
  246.7500 298.0000 L
  248.2500 295.7500 L
  249.2500 293.2500 L
  249.5000 290.7500 L
  249.2500 288.5000 L
  248.2500 286.0000 L
  246.7500 283.7500 L
  244.2500 281.5000 L
  241.7500 279.7500 L
  238.2500 278.0000 L
  234.5000 276.5000 L
  230.5000 275.2500 L
  226.0000 274.2500 L
  221.2500 273.5000 L
  216.5000 273.2500 L
  211.7500 273.2500 L
  207.0000 273.5000 L
  202.2500 274.2500 L
  197.7500 275.2500 L
  193.5000 276.5000 L
  190.0000 278.0000 L
  186.5000 279.7500 L
  184.0000 281.5000 L
  181.5000 283.7500 L
  180.0000 286.0000 L
  179.0000 288.5000 L
  178.7500 290.7500 L
B
U
0 To
1.00000 0 0 1.00000 206.500 288.000 0 Tp
TP
/_Helvetica-Bold 9.2500 Tf
0.0000 Tc
 0 Tr
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(sdf\r) Tx
TO
u
  0.000 0.000 0.000 0.000 k
0.2500 w
1 j
  178.7500 326.2500 m
  249.5000 326.2500 L
  249.5000 361.7500 L
  178.7500 361.7500 L
  178.7500 326.2500 L
B
U
0 To
1.00000 0 0 1.00000 192.500 341.000 0 Tp
TP
/_Helvetica-Bold 9.2500 Tf
0.0000 Tc
 0 Tr
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(SDF files\r) Tx
TO
u
  0.000 0.000 0.000 0.000 k
0.2500 w
1 j
  72.5000 202.2500 m
  131.5000 202.2500 L
  131.5000 237.7500 L
  72.5000 237.7500 L
  72.5000 202.2500 L
B
U
0 To
1.00000 0 0 1.00000 93.5000 217.000 0 Tp
TP
/_Helvetica 9.2500 Tf
0.0000 Tc
 0 Tr
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(MIF\r) Tx
TO
u
  0.000 0.000 0.000 0.000 k
0.2500 w
1 j
  72.5000 326.2500 m
  131.5000 326.2500 L
  131.5000 361.7500 L
  72.5000 361.7500 L
  72.5000 326.2500 L
F
U
u
 [4 2 ] 0 d
1 J
  72.5000 326.2500 m
  131.5000 326.2500 L
  131.5000 361.7500 L
  72.5000 361.7500 L
  72.5000 326.2500 L
S
U
0 To
1.00000 0 0 1.00000 86.0000 347.000 0 Tp
TP
/_Helvetica 9.2500 Tf
0.0000 Tc
 0 Tr
 [] 0 d
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(Source\r) Tx
TO
0 To
1.00000 0 0 1.00000 91.0000 335.000 0 Tp
TP
/_Helvetica 9.2500 Tf
0.0000 Tc
 0 Tr
  0.000 0.000 0.000 1.000 k
(code\r) Tx
TO
u
  0.000 0.000 0.000 0.000 k
0.2500 w
1 j
  143.2500 202.2500 m
  202.2500 202.2500 L
  202.2500 237.7500 L
  143.2500 237.7500 L
  143.2500 202.2500 L
B
U
0 To
1.00000 0 0 1.00000 163.000 223.000 0 Tp
TP
/_Helvetica 9.2500 Tf
0.0000 Tc
 0 Tr
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(RTF\r) Tx
TO
0 To
1.00000 0 0 1.00000 155.000 211.000 0 Tp
TP
/_Helvetica 9.2500 Tf
0.0000 Tc
 0 Tr
  0.000 0.000 0.000 1.000 k
(\(& HPJ\)\r) Tx
TO
u
  0.000 0.000 0.000 0.000 k
0.2500 w
1 j
  1.5000 202.2500 m
  60.7500 202.2500 L
  60.7500 237.7500 L
  1.5000 237.7500 L
  1.5000 202.2500 L
B
U
0 To
1.00000 0 0 1.00000 17.0000 217.000 0 Tp
TP
/_Helvetica-Bold 9.2500 Tf
0.0000 Tc
 0 Tr
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(HTML\r) Tx
TO
u
  0.000 0.000 0.000 0.000 k
0.2500 w
1 j
  226.0000 202.2500 m
  285.0000 202.2500 L
  285.0000 237.7500 L
  226.0000 237.7500 L
  226.0000 202.2500 L
B
U
0 To
1.00000 0 0 1.00000 243.500 223.000 0 Tp
TP
/_Helvetica-Bold 9.2500 Tf
0.0000 Tc
 0 Tr
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(Plain\r) Tx
TO
0 To
1.00000 0 0 1.00000 246.500 211.000 0 Tp
TP
/_Helvetica-Bold 9.2500 Tf
0.0000 Tc
 0 Tr
  0.000 0.000 0.000 1.000 k
(text\r) Tx
TO
u
  0.000 0.000 0.000 0.000 k
0.2500 w
1 j
  296.7500 202.2500 m
  355.7500 202.2500 L
  355.7500 237.7500 L
  296.7500 237.7500 L
  296.7500 202.2500 L
B
U
0 To
1.00000 0 0 1.00000 315.500 217.000 0 Tp
TP
/_Helvetica 9.2500 Tf
0.0000 Tc
 0 Tr
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(POD\r) Tx
TO
u
  0.000 0.000 0.000 0.000 k
0.2500 w
1 j
  368.7500 202.2500 m
  427.7500 202.2500 L
  427.7500 237.7500 L
  368.7500 237.7500 L
  368.7500 202.2500 L
B
U
0 To
1.00000 0 0 1.00000 384.000 217.000 0 Tp
TP
/_Helvetica 9.2500 Tf
0.0000 Tc
 0 Tr
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(SGML\r) Tx
TO
u
0.2500 w
1 j
  214.0000 273.2500 m
  214.0000 262.5000 L
S
U
u
  214.0000 259.0000 m
  31.2500 259.0000 L
  31.2500 241.2500 L
S
U
u
  214.0000 259.0000 m
  398.2500 259.0000 L
  398.2500 241.2500 L
S
U
u
  214.0000 259.0000 m
  102.0000 259.0000 L
  102.0000 241.2500 L
S
U
u
  214.0000 259.0000 m
  172.7500 259.0000 L
  172.7500 241.2500 L
S
U
u
  214.0000 259.0000 m
  255.5000 259.0000 L
  255.5000 241.2500 L
S
U
u
  214.0000 259.0000 m
  326.2500 259.0000 L
  326.2500 241.2500 L
S
U
  0.000 0.000 0.000 1.000 k
*u
  216.0000 263.0000 m
  214.0000 259.0000 L
  212.0000 263.0000 L
  216.0000 263.0000 L
  216.0000 263.0000 L
F
u
  33.0000 241.7500 m
  31.2500 237.7500 L
  29.2500 241.7500 L
  33.0000 241.7500 L
  33.0000 241.7500 L
F
U
u
  400.2500 241.7500 m
  398.2500 237.7500 L
  396.2500 241.7500 L
  400.2500 241.7500 L
  400.2500 241.7500 L
F
U
u
  104.0000 241.7500 m
  102.0000 237.7500 L
  99.7500 241.7500 L
  104.0000 241.7500 L
  104.0000 241.7500 L
F
U
u
  175.0000 241.7500 m
  172.7500 237.7500 L
  170.7500 241.7500 L
  175.0000 241.7500 L
  175.0000 241.7500 L
F
U
u
  257.5000 241.7500 m
  255.5000 237.7500 L
  253.2500 241.7500 L
  257.5000 241.7500 L
  257.5000 241.7500 L
F
U
u
  328.2500 241.7500 m
  326.2500 237.7500 L
  324.2500 241.7500 L
  328.2500 241.7500 L
  328.2500 241.7500 L
F
U
*U
u
 [4 2 ] 0 d
  131.5000 344.0000 m
  155.0000 344.0000 L
  155.0000 344.0000 L
  155.0000 344.0000 L
  155.0000 344.0000 L
  173.7500 344.0000 L
S
U
u
  0.000 0.000 0.000 1.000 k
 [] 0 d
  173.2500 346.7500 m
  178.7500 344.0000 L
  173.2500 341.2500 L
  173.2500 346.7500 L
F
U
u
  0.000 0.000 0.000 0.000 k
  107.7500 96.0000 m
  167.0000 96.0000 L
  167.0000 131.5000 L
  107.7500 131.5000 L
  107.7500 96.0000 L
B
U
0 To
1.00000 0 0 1.00000 112.000 110.750 0 Tp
TP
/_Helvetica-Bold 9.2500 Tf
0.0000 Tc
 0 Tr
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(PostScript\r) Tx
TO
u
  0.000 0.000 0.000 0.000 k
0.2500 w
1 j
  214.0000 96.0000 m
  273.0000 96.0000 L
  273.0000 131.5000 L
  214.0000 131.5000 L
  214.0000 96.0000 L
B
U
0 To
1.00000 0 0 1.00000 221.250 116.750 0 Tp
TP
/_Helvetica-Bold 9.2500 Tf
0.0000 Tc
 0 Tr
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(Windows\r) Tx
TO
0 To
1.00000 0 0 1.00000 232.750 104.750 0 Tp
TP
/_Helvetica-Bold 9.2500 Tf
0.0000 Tc
 0 Tr
  0.000 0.000 0.000 1.000 k
(Help\r) Tx
TO
u
  0.000 0.000 0.000 0.000 k
0.2500 w
1 j
  72.5000 167.0000 m
  72.7500 168.5000 L
  73.7500 170.5000 L
  75.5000 172.0000 L
  77.5000 173.5000 L
  80.2500 175.0000 L
  83.5000 176.2500 L
  87.2500 177.0000 L
  91.2500 178.0000 L
  95.2500 178.2500 L
  99.7500 178.7500 L
  104.2500 178.7500 L
  108.5000 178.2500 L
  112.7500 178.0000 L
  116.7500 177.0000 L
  120.2500 176.2500 L
  123.5000 175.0000 L
  126.2500 173.5000 L
  128.5000 172.0000 L
  130.0000 170.5000 L
  131.2500 168.5000 L
  131.5000 167.0000 L
  131.2500 165.2500 L
  130.0000 163.5000 L
  128.5000 161.7500 L
  126.2500 160.2500 L
  123.5000 159.0000 L
  120.2500 157.7500 L
  116.7500 156.7500 L
  112.7500 155.7500 L
  108.5000 155.5000 L
  104.2500 155.0000 L
  99.7500 155.0000 L
  95.2500 155.5000 L
  91.2500 155.7500 L
  87.2500 156.7500 L
  83.5000 157.7500 L
  80.2500 159.0000 L
  77.5000 160.2500 L
  75.5000 161.7500 L
  73.7500 163.5000 L
  72.7500 165.2500 L
  72.5000 167.0000 L
B
U
0 To
1.00000 0 0 1.00000 84.0000 164.000 0 Tp
TP
/_Helvetica 9.2500 Tf
0.0000 Tc
 0 Tr
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(fmbatch\r) Tx
TO
u
  0.000 0.000 0.000 0.000 k
0.2500 w
1 j
  143.2500 167.0000 m
  143.5000 168.5000 L
  144.7500 170.5000 L
  146.2500 172.0000 L
  148.5000 173.5000 L
  151.2500 175.0000 L
  154.2500 176.2500 L
  158.0000 177.0000 L
  162.0000 178.0000 L
  166.2500 178.2500 L
  170.5000 178.7500 L
  175.0000 178.7500 L
  179.5000 178.2500 L
  183.5000 178.0000 L
  187.5000 177.0000 L
  191.2500 176.2500 L
  194.5000 175.0000 L
  197.2500 173.5000 L
  199.2500 172.0000 L
  201.0000 170.5000 L
  202.0000 168.5000 L
  202.2500 167.0000 L
  202.0000 165.2500 L
  201.0000 163.5000 L
  199.2500 161.7500 L
  197.2500 160.2500 L
  194.5000 159.0000 L
  191.2500 157.7500 L
  187.5000 156.7500 L
  183.5000 155.7500 L
  179.5000 155.5000 L
  175.0000 155.0000 L
  170.5000 155.0000 L
  166.2500 155.5000 L
  162.0000 155.7500 L
  158.0000 156.7500 L
  154.2500 157.7500 L
  151.2500 159.0000 L
  148.5000 160.2500 L
  146.2500 161.7500 L
  144.7500 163.5000 L
  143.5000 165.2500 L
  143.2500 167.0000 L
B
U
0 To
1.00000 0 0 1.00000 160.500 164.000 0 Tp
TP
/_Helvetica 9.2500 Tf
0.0000 Tc
 0 Tr
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(Word\r) Tx
TO
u
  0.000 0.000 0.000 0.000 k
0.2500 w
1 j
  214.0000 167.0000 m
  214.5000 168.5000 L
  215.2500 170.5000 L
  217.0000 172.0000 L
  219.2500 173.5000 L
  222.0000 175.0000 L
  225.2500 176.2500 L
  228.7500 177.0000 L
  232.7500 178.0000 L
  237.2500 178.2500 L
  241.5000 178.7500 L
  245.7500 178.7500 L
  250.2500 178.2500 L
  254.5000 178.0000 L
  258.2500 177.0000 L
  262.0000 176.2500 L
  265.2500 175.0000 L
  268.0000 173.5000 L
  270.2500 172.0000 L
  271.7500 170.5000 L
  272.7500 168.5000 L
  273.0000 167.0000 L
  272.7500 165.2500 L
  271.7500 163.5000 L
  270.2500 161.7500 L
  268.0000 160.2500 L
  265.2500 159.0000 L
  262.0000 157.7500 L
  258.2500 156.7500 L
  254.5000 155.7500 L
  250.2500 155.5000 L
  245.7500 155.0000 L
  241.5000 155.0000 L
  237.2500 155.5000 L
  232.7500 155.7500 L
  228.7500 156.7500 L
  225.2500 157.7500 L
  222.0000 159.0000 L
  219.2500 160.2500 L
  217.0000 161.7500 L
  215.2500 163.5000 L
  214.5000 165.2500 L
  214.0000 167.0000 L
B
U
0 To
1.00000 0 0 1.00000 233.000 164.000 0 Tp
TP
/_Helvetica 9.2500 Tf
0.0000 Tc
 0 Tr
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(HCP\r) Tx
TO
u
0.2500 w
1 j
  243.5000 155.0000 m
  243.5000 143.2500 L
  243.5000 143.2500 L
  243.5000 143.2500 L
  243.5000 143.2500 L
  243.5000 136.5000 L
S
U
u
  0.000 0.000 0.000 1.000 k
  246.2500 137.0000 m
  243.5000 131.5000 L
  241.0000 137.0000 L
  246.2500 137.0000 L
F
U
u
  172.7500 202.2500 m
  172.7500 190.5000 L
  172.7500 190.5000 L
  172.7500 190.5000 L
  172.7500 190.5000 L
  172.7500 183.5000 L
S
U
u
  0.000 0.000 0.000 1.000 k
  175.5000 184.2500 m
  172.7500 178.7500 L
  170.0000 184.2500 L
  175.5000 184.2500 L
F
U
u
  102.0000 202.2500 m
  102.0000 190.5000 L
  102.0000 190.5000 L
  102.0000 190.5000 L
  102.0000 190.5000 L
  102.0000 183.5000 L
S
U
u
  0.000 0.000 0.000 1.000 k
  104.7500 184.2500 m
  102.0000 178.7500 L
  99.2500 184.2500 L
  104.7500 184.2500 L
F
U
u
  172.7500 202.2500 m
  172.7500 190.5000 L
  208.2500 190.5000 L
  208.2500 190.5000 L
  243.5000 190.5000 L
  243.5000 183.5000 L
S
U
u
  0.000 0.000 0.000 1.000 k
  246.2500 184.2500 m
  243.5000 178.7500 L
  241.0000 184.2500 L
  246.2500 184.2500 L
F
U
u
  102.0000 155.0000 m
  102.0000 143.2500 L
  119.7500 143.2500 L
  119.7500 143.2500 L
  137.5000 143.2500 L
  137.5000 136.5000 L
S
U
u
  0.000 0.000 0.000 1.000 k
  140.2500 137.0000 m
  137.5000 131.5000 L
  134.5000 137.0000 L
  140.2500 137.0000 L
F
U
u
  172.7500 155.0000 m
  172.7500 143.2500 L
  155.0000 143.2500 L
  155.0000 143.2500 L
  137.5000 143.2500 L
  137.5000 136.5000 L
S
U
u
  0.000 0.000 0.000 1.000 k
  140.2500 137.0000 m
  137.5000 131.5000 L
  134.5000 137.0000 L
  140.2500 137.0000 L
F
U
u
  0.000 0.000 0.000 0.000 k
  296.7500 167.0000 m
  297.0000 168.5000 L
  298.0000 170.5000 L
  299.7500 172.0000 L
  302.0000 173.5000 L
  304.5000 175.0000 L
  307.7500 176.2500 L
  311.5000 177.0000 L
  315.5000 178.0000 L
  319.7500 178.2500 L
  324.0000 178.7500 L
  328.5000 178.7500 L
  332.7500 178.2500 L
  337.0000 178.0000 L
  341.0000 177.0000 L
  344.7500 176.2500 L
  348.0000 175.0000 L
  350.7500 173.5000 L
  352.7500 172.0000 L
  354.5000 170.5000 L
  355.5000 168.5000 L
  355.7500 167.0000 L
  355.5000 165.2500 L
  354.5000 163.5000 L
  352.7500 161.7500 L
  350.7500 160.2500 L
  348.0000 159.0000 L
  344.7500 157.7500 L
  341.0000 156.7500 L
  337.0000 155.7500 L
  332.7500 155.5000 L
  328.5000 155.0000 L
  324.0000 155.0000 L
  319.7500 155.5000 L
  315.5000 155.7500 L
  311.5000 156.7500 L
  307.7500 157.7500 L
  304.5000 159.0000 L
  302.0000 160.2500 L
  299.7500 161.7500 L
  298.0000 163.5000 L
  297.0000 165.2500 L
  296.7500 167.0000 L
B
U
0 To
1.00000 0 0 1.00000 310.750 164.000 0 Tp
TP
/_Helvetica 9.2500 Tf
0.0000 Tc
 0 Tr
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(pod2...\r) Tx
TO
u
  0.000 0.000 0.000 0.000 k
0.2500 w
1 j
  290.5000 93.7500 m
  361.5000 93.7500 L
  361.5000 129.2500 L
  290.5000 129.2500 L
  290.5000 93.7500 L
B
U
0 To
1.00000 0 0 1.00000 298.250 114.500 0 Tp
TP
/_Helvetica-Bold 9.2500 Tf
0.0000 Tc
 0 Tr
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(man pages,\r) Tx
TO
0 To
1.00000 0 0 1.00000 301.250 102.500 0 Tp
TP
/_Helvetica-Bold 9.2500 Tf
0.0000 Tc
 0 Tr
  0.000 0.000 0.000 1.000 k
(Latex, etc.\r) Tx
TO
u
0.2500 w
1 j
  326.2500 202.2500 m
  326.2500 190.5000 L
  326.2500 190.5000 L
  326.2500 190.5000 L
  326.2500 190.5000 L
  326.2500 183.5000 L
S
U
u
  0.000 0.000 0.000 1.000 k
  329.0000 184.2500 m
  326.2500 178.7500 L
  323.5000 184.2500 L
  329.0000 184.2500 L
F
U
u
  326.2500 155.0000 m
  326.2500 142.2500 L
  326.2500 142.2500 L
  326.2500 142.2500 L
  326.0000 142.2500 L
  326.0000 134.0000 L
S
U
u
  0.000 0.000 0.000 1.000 k
  328.7500 134.5000 m
  326.0000 129.2500 L
  323.2500 134.5000 L
  328.7500 134.5000 L
F
U
u
  0.000 0.000 0.000 0.000 k
  107.7500 1.5000 m
  167.0000 1.5000 L
  167.0000 37.0000 L
  107.7500 37.0000 L
  107.7500 1.5000 L
B
U
0 To
1.00000 0 0 1.00000 127.500 16.2500 0 Tp
TP
/_Helvetica-Bold 9.2500 Tf
0.0000 Tc
 0 Tr
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(PDF\r) Tx
TO
u
  0.000 0.000 0.000 0.000 k
0.2500 w
1 j
  107.7500 66.5000 m
  108.2500 69.0000 L
  109.2500 71.7500 L
  110.7500 74.2500 L
  113.0000 76.5000 L
  115.7500 78.7500 L
  119.0000 80.5000 L
  122.5000 81.7500 L
  126.7500 83.0000 L
  130.7500 83.7500 L
  135.0000 84.2500 L
  139.5000 84.2500 L
  144.0000 83.7500 L
  148.0000 83.0000 L
  152.2500 81.7500 L
  155.7500 80.5000 L
  159.0000 78.7500 L
  161.7500 76.5000 L
  164.0000 74.2500 L
  165.5000 71.7500 L
  166.5000 69.0000 L
  167.0000 66.5000 L
  166.5000 64.0000 L
  165.5000 61.2500 L
  164.0000 58.7500 L
  161.7500 56.5000 L
  159.0000 54.5000 L
  155.7500 52.7500 L
  152.2500 51.2500 L
  148.0000 50.0000 L
  144.0000 49.2500 L
  139.5000 49.0000 L
  135.0000 49.0000 L
  130.7500 49.2500 L
  126.7500 50.0000 L
  122.5000 51.2500 L
  119.0000 52.7500 L
  115.7500 54.5000 L
  113.0000 56.5000 L
  110.7500 58.7500 L
  109.2500 61.2500 L
  108.2500 64.0000 L
  107.7500 66.5000 L
B
U
0 To
1.00000 0 0 1.00000 120.000 63.5000 0 Tp
TP
/_Helvetica 9.2500 Tf
0.0000 Tc
 0 Tr
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(Acrobat\r) Tx
TO
u
0.2500 w
1 j
  137.5000 96.0000 m
  137.5000 90.2500 L
  137.5000 90.2500 L
  137.5000 90.2500 L
  137.5000 90.2500 L
  137.5000 89.0000 L
S
U
u
  0.000 0.000 0.000 1.000 k
  140.2500 89.7500 m
  137.5000 84.2500 L
  134.5000 89.7500 L
  140.2500 89.7500 L
F
U
u
  137.5000 48.7500 m
  137.5000 43.0000 L
  137.5000 43.0000 L
  137.5000 43.0000 L
  137.5000 43.0000 L
  137.5000 42.0000 L
S
U
u
  0.000 0.000 0.000 1.000 k
  140.2500 42.5000 m
  137.5000 37.0000 L
  134.5000 42.5000 L
  140.2500 42.5000 L
F
U
u
  214.0000 326.2500 m
  214.0000 317.5000 L
  214.0000 317.5000 L
  214.0000 317.5000 L
  214.0000 317.5000 L
  214.0000 313.5000 L
S
U
u
  0.000 0.000 0.000 1.000 k
  216.7500 314.2500 m
  214.0000 308.5000 L
  211.5000 314.2500 L
  216.7500 314.2500 L
F
U
u
  0.000 0.000 0.000 0.000 k
  167.0000 403.0000 m
  167.2500 406.0000 L
  168.2500 408.7500 L
  170.0000 411.2500 L
  172.2500 414.0000 L
  175.2500 416.5000 L
  178.7500 418.7500 L
  182.7500 420.7500 L
  187.2500 422.5000 L
  192.2500 424.0000 L
  197.2500 425.2500 L
  202.7500 426.0000 L
  208.2500 426.5000 L
  214.0000 426.7500 L
  219.7500 426.5000 L
  225.5000 426.0000 L
  230.7500 425.2500 L
  236.0000 424.0000 L
  241.0000 422.5000 L
  245.5000 420.7500 L
  249.2500 418.7500 L
  253.0000 416.5000 L
  255.7500 414.0000 L
  258.2500 411.2500 L
  260.0000 408.7500 L
  261.0000 406.0000 L
  261.2500 403.0000 L
  261.0000 400.2500 L
  260.0000 397.2500 L
  258.2500 394.5000 L
  255.7500 392.0000 L
  253.0000 389.5000 L
  249.2500 387.5000 L
  245.5000 385.5000 L
  241.0000 383.7500 L
  236.0000 382.2500 L
  230.7500 381.0000 L
  225.5000 380.0000 L
  219.7500 379.7500 L
  214.0000 379.5000 L
  208.2500 379.7500 L
  202.7500 380.0000 L
  197.2500 381.0000 L
  192.2500 382.2500 L
  187.2500 383.7500 L
  182.7500 385.5000 L
  178.7500 387.5000 L
  175.2500 389.5000 L
  172.2500 392.0000 L
  170.0000 394.5000 L
  168.2500 397.2500 L
  167.2500 400.2500 L
  167.0000 403.0000 L
B
U
0 To
1.00000 0 0 1.00000 195.000 406.250 0 Tp
TP
/_Helvetica-Bold 9.2500 Tf
0.0000 Tc
 0 Tr
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(any text\r) Tx
TO
0 To
1.00000 0 0 1.00000 200.000 394.000 0 Tp
TP
/_Helvetica-Bold 9.2500 Tf
0.0000 Tc
 0 Tr
  0.000 0.000 0.000 1.000 k
(editor\r) Tx
TO
u
0.2500 w
1 j
  214.0000 374.7500 m
  214.0000 372.7500 L
  214.0000 372.7500 L
  214.0000 372.7500 L
  214.0000 372.7500 L
  214.0000 366.5000 L
S
U
  0.000 0.000 0.000 1.000 k
*u
  216.7500 374.0000 m
  214.0000 379.5000 L
  211.5000 374.0000 L
  216.7500 374.0000 L
  216.7500 374.0000 L
F
u
  216.7500 367.2500 m
  214.0000 361.7500 L
  211.5000 367.2500 L
  216.7500 367.2500 L
  216.7500 367.2500 L
F
U
*U
u
  0.000 0.000 0.000 0.000 k
  296.7500 326.2500 m
  355.7500 326.2500 L
  355.7500 361.7500 L
  296.7500 361.7500 L
  296.7500 326.2500 L
F
U
u
 [4 2 ] 0 d
  296.7500 326.2500 m
  355.7500 326.2500 L
  355.7500 361.7500 L
  296.7500 361.7500 L
  296.7500 326.2500 L
S
U
0 To
1.00000 0 0 1.00000 302.000 347.000 0 Tp
TP
/_Helvetica 9.2500 Tf
0.0000 Tc
 0 Tr
 [] 0 d
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(Formatting\r) Tx
TO
0 To
1.00000 0 0 1.00000 315.500 335.000 0 Tp
TP
/_Helvetica 9.2500 Tf
0.0000 Tc
 0 Tr
  0.000 0.000 0.000 1.000 k
(rules\r) Tx
TO
u
 [4 2 ] 0 d
0.2500 w
1 j
  326.2500 326.2500 m
  326.2500 322.7500 L
  326.2500 322.7500 L
  326.2500 322.7500 L
  326.2500 290.7500 L
  254.5000 290.7500 L
S
U
u
  0.000 0.000 0.000 1.000 k
 [] 0 d
  255.0000 288.0000 m
  249.5000 290.7500 L
  255.0000 293.7500 L
  255.0000 288.0000 L
F
U
u
  0.000 0.000 0.000 0.000 k
  368.7500 164.5000 m
  369.0000 166.2500 L
  370.0000 168.0000 L
  371.7500 169.7500 L
  373.7500 171.0000 L
  376.5000 172.5000 L
  379.7500 173.7500 L
  383.5000 174.7500 L
  387.5000 175.5000 L
  391.7500 176.0000 L
  396.0000 176.2500 L
  400.5000 176.2500 L
  404.7500 176.0000 L
  409.2500 175.5000 L
  413.0000 174.7500 L
  416.7500 173.7500 L
  420.0000 172.5000 L
  422.7500 171.0000 L
  424.7500 169.7500 L
  426.5000 168.0000 L
  427.5000 166.2500 L
  427.7500 164.5000 L
  427.5000 162.7500 L
  426.5000 161.0000 L
  424.7500 159.5000 L
  422.7500 157.7500 L
  420.0000 156.5000 L
  416.7500 155.2500 L
  413.0000 154.5000 L
  409.2500 153.5000 L
  404.7500 153.0000 L
  400.5000 152.7500 L
  396.0000 152.7500 L
  391.7500 153.0000 L
  387.5000 153.5000 L
  383.5000 154.5000 L
  379.7500 155.2500 L
  376.5000 156.5000 L
  373.7500 157.7500 L
  371.7500 159.5000 L
  370.0000 161.0000 L
  369.0000 162.7500 L
  368.7500 164.5000 L
B
U
0 To
1.00000 0 0 1.00000 380.750 161.500 0 Tp
TP
/_Helvetica 9.2500 Tf
0.0000 Tc
 0 Tr
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(sgml2...\r) Tx
TO
u
  0.000 0.000 0.000 0.000 k
0.2500 w
1 j
  367.0000 93.7500 m
  429.5000 93.7500 L
  429.5000 129.2500 L
  367.0000 129.2500 L
  367.0000 93.7500 L
B
U
0 To
1.00000 0 0 1.00000 375.000 114.500 0 Tp
TP
/_Helvetica-Bold 9.2500 Tf
0.0000 Tc
 0 Tr
0.0000 w
0 j
  0.000 0.000 0.000 1.000 k
(GNU info,\r) Tx
TO
0 To
1.00000 0 0 1.00000 373.500 102.500 0 Tp
TP
/_Helvetica-Bold 9.2500 Tf
0.0000 Tc
 0 Tr
  0.000 0.000 0.000 1.000 k
(Latex, etc.\r) Tx
TO
u
0.2500 w
1 j
  398.2500 202.2500 m
  398.2500 189.2500 L
  398.2500 189.2500 L
  398.2500 189.2500 L
  398.2500 189.2500 L
  398.2500 181.2500 L
S
U
u
  0.000 0.000 0.000 1.000 k
  401.0000 182.0000 m
  398.2500 176.2500 L
  395.5000 182.0000 L
  401.0000 182.0000 L
F
U
u
  398.2500 152.7500 m
  398.2500 141.0000 L
  398.2500 141.0000 L
  398.2500 141.0000 L
  398.2500 141.0000 L
  398.2500 134.0000 L
S
U
u
  0.000 0.000 0.000 1.000 k
  401.0000 134.5000 m
  398.2500 129.2500 L
  395.5000 134.5000 L
  401.0000 134.5000 L
F
U
%%PageTrailer
gsave annotatepage grestore showpage
%%Trailer
Adobe_Illustrator_AI3 /terminate get exec
Adobe_typography_AI3 /terminate get exec
Adobe_customcolor /terminate get exec
Adobe_cshow /terminate get exec
Adobe_cmykcolor /terminate get exec
Adobe_packedarray /terminate get exec
%%EOF
155.0000 m
  172.7500 143.2500 L
  155.0000 143.2500 L
  155.0000 143.2500 L
  137.5000 143.2500 L
  137.5000 136.5000 L
S
U
u
  0.000 0.000 0.000 1.000 k
  140.2500 137.0000 m
  137.5000 131.5000 L
  134.5000 137.0000 L
  140.2500 137.0000 L
F
U
u
  0.000 0.000 0.000 0.000 k
  296.7500 167.0000 m
  297.0000 168.500sdf-2.001/doc/paper/mydoc.sdf010064400042570001753000000020670645304557600156260ustar00iancmtr00000400000236# Build the title
!define DOC_NAME           "GalaxyBuilder"
!define DOC_TYPE           "Discussion Paper"
!define DOC_AUTHOR         "Joe Bloggs"
!build_title
 
H1: Introduction

After extensive market research, I believe there is
an excellent opportunity for us to develop software
for the I. Potential
customers include:

* NASA
* European Community
* China
* Japan.

Note: The proposed name of the software package to be
developed is [[DOC_NAME]]. If you want to suggest a
better name, send email to {{EMAIL:joe@bloggs.com}}.

H2: Software Requirements

The key requirements are:

^ support for the design and simulation of galaxies
  containing up to:
  - 1000 large planets, or
  - 5000 small planets
+ the package needs to be easy to use
+ the package needs to be well documented.

H2: Project Team

Exploding galaxies will be B bad for business,
so we need the best team possible for this project:

!block table
Person          Role
Mary Jones      Project Manager
Hans Blass      Architect
Bill Smith      Software Engineer
!endblock
sdf-2.001/doc/paper/sdfarch.vsd010064400042570001753000000570000645305116200161260ustar00iancmtr00000400000236ÐÏࡱá>þÿ	,þÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿýÿÿÿþÿÿÿ	

 !"#$%&'()*+þÿÿÿþÿÿÿþÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿRoot EntryÿÿÿÿÿÿÿÿÀFpAýï&½-@VisioDocumentÿÿÿÿÿÿÿÿÿÿÿÿ½RSummaryInformation(ÿÿÿÿÿÿÿÿÿÿÿÿþÿÿÿÈVisioInformation"ÿÿÿÿÿÿÿÿÿÿÿÿþÿÿÿVisio (TM) Drawing
½R„R<
tkQ0ídêñéòÿÿÿƒÿöòÿóûðøñ‰€êñ€ €ÿÀÀÀæææÿÍÍͳ³³ïššš!€fÿffMMM333ÿÿÿÖq0ÜÿáúëðßTëðdÿ ArialWica)-3ÿTimes Nÿew Romanê)-
ëðä":5Tëð?èóÐ?òÿÚêñ èóY@-1ÿÿÿÖ(¹Üÿëð(Jëð/T éòÿ
àû÷hëðTë¼èóJ¿bþOòSSëð0{®ÿGáz„?@æõCPjVÉ]„uVbUU––– €ÒO
—O–S»?æõ
Ò„T¡666ú
úÿ€N—•—Põ—»—–	–U
–––
–U––––¥–vŽPa«þC G#G#ªG#G#G#G#ðG Òä&ýÿH¦#‚O`—À$À$ýÀ!>£^ÿ„M¤ìÿ 4‡Äÿ†Š…!}“7–iú>xßü'0U2Å?Ž„¬,¯„!èóðÃú„6þg”>7mjP>±¤åö¡603´2óƒ¿0«6&0B¨Z£!´4?¡¼6ÐV2GÀT•2œ—k=°-Ì	Kˆ2
ÒT+5ª7@ßü9ÜÇ6L^pu?5ŒÖB2¡?÷O€Õ?ç?Z®´‡Xñ Fõ&È…03P?„_³?¨¨V×Ã.CG
eOwN9:–O ¨OºOÌOÞMbY_PJ7@Ò_|öYoo¿2ÇqË`¬?ÊoÜf.Üf#Röjêöjög‡÷$„
€0ÓTÛ_o?u€Ö45e%Ô[b,u4:«pŒ0qÕ7@û"S@U
B ®`S@
ÏpUÓp×pÛpƒUãpçp[@ïpUópõðûpÿpU€€Ç`íðU€=@ €!€U"#€#$÷ %/€&;€'
9K]o~Ò
¢yJB J\ n€‚}€1Ö°ÁÓå÷~ÐPÕµ²‹	9ŸKŸ]ŸoŸ~p`
Õ°
±ŸÃŸÕŸçŸ(~À€Õ°)¯;¯ M¯_¯~°pÕ°€¡¯³¯Å¯×¯~H€Õ‚°
¿+¿=¿O¿~Ó	°ê°“¿¥¿·¿É¿
ƒ|Ó	°bÀÏÏ@÷X?‰Ø‡xjtTÞCeõ&cPJçp ‚Ï”Ï.Ï@Ï‚}Ó	°fÐß!ߧϹÏËÏm%åÏ´üÍ…ß—ß 1ßCß~( Õ
°€ï#ï5ïGï~°Õ
°‰ï›ï­ï¿ï~°
Õ	°ÿÿ%ÿ7ÿ(~°Õ°yÿ‹ÿ ÿ¯ÿ~8Õ°€ñÿ'~  •w°i{Ÿ~ˆà
•w°áó(~xð•w°Yk }~h•w°ÀÑãõZÀ ¹ßËß0ÿOè´Nk?AäÍ)1¢&66þÇTE I/[/m//‘/+f¬/¾ +eÉ/Û"á/ó/?ü?)?¸…ëQ¸AžB?¼"Ó5a?Û"y?‹??¯?Á?£/µ/Ç/	DO#Oõ_GOYOkF¢éß¡„O–K\E  J©@ÕR³OÅH9N€¨a+,5$cÜo«_–tœ³a*wTiPža<üÇF>a'2%r¬RÁí`ñaùV¶at’cД’1j°`ÊžaPÇF?0oèU03NTbó¿0Kf|[Ãb•’GE !I_[_m_ _‘_¬_ènTžqÒYjßT.o+RodgSË2zei'dæ_øZš•kê`eJ/€†o˜oªo¼oÎoéoòoÚ_„–¨@"o1:Ljo|e#ÁÓå÷	$µ_Ç_QŠÀ&ñÒô_è@®AcÐð?„Œd7¸ÁÓåb$ýŸ!Ÿ3ŸEŸ`Ÿ-?ŸŸŸ±ŸÃŸÕŸçŸ0¿¯¯wj%=¯O¯a¯s¯…¯ ¯©¯»¯4¿=¿€O¿]o|Ú¯ì¯þ¯»J&}¿¿¡¿³¿Å¿à¿ iŸ{ŸÍ¯cŒ Ó¼fnÕ#R™Ä@¿ϯß>Ï$\¿vk'©@—ÃÇÏÅHÑF”ñÆøÅìE%ÓÀjOfƒ[Ç$[(ßïÊåBa‡S€:U„Qßcßu߇ߙÒÿPCanoÿn PS-IPUÿ Color Lïaserþðpieÿrœÿ´O	š4dß=ëðA4t>ðPbtçõRIV A|¥·Éä÷éòã'ìêæõ%ÿ/,>}Mëð7ëðÿwinspoolÿCanon PÿS-IPU Coÿlor Laseírpiv52ÿ.3FILE:ÜþÿFÿÿÖ… ëðïðüóÜÿøñh¾ëðTèçõßï÷ûý~@*ÿÇãñx<¾?þ<¿F
…B¡Pw(¤?Nöñ,fxêñùð*•þ‘•
<žþEþbÝÈbÏb½Ï	b žôNží’N‹ße‹çô×Héòƒ
ë1êñ óð#þïòÿˆßÿ‚øŽw…wßxƒˆ…ƒïˆ„„wÿÿÿp‡ƒþƒwp…ÿûðˆ5…ÿ
÷ÿ‡wwøøww¿p‡ÿ	ðˆPöW÷PˆÿüNRpˆÿpžs‰ÿð~‰³ÿ›yphØ\ÂVðB†ÿ[5p'.Á' H
ˆøÿøý;ëðGeneriÿc circleÿ or elliÿpse withÿ text anÿd connecÿtion points.ýbéòº\.—Ëåëâ¿ôô?üü¿ð,˜šhã¿òù?ð÷ûý~·¿À4ßï5÷¿DÿHÿÿÖÕ"ëðëðÿþòw&áú}hTäèóÿ@ßï÷ûý~ÿý?,¹\.—ËåÕò=âOP
«+þqu
ô>~‘ïu` èóà?N¨u¯	qb¿þbØúß	ß@nëð÷ª
Dö)ó÷&ÿB BBH
6#ð6/	Û€L@ÿþýÿýÿþô
A€`9Coÿpyright ÿ© 1995 Vÿisio Corÿporation.  All ¬ÿs reserv¿ed.þr`ÿShape.hÿlp!#1500ÿ0þ£bß„K›÷ÓløU¸|%aþ •### @æõPµ©­¹¢¿
ùð's N
IG‰-òa°ðE.Qð¸],©­¿´Æ!qO&þ¼`¿¿(4/-7æõ¤/·rrs 5þ\0`1Û/í,øV!??ûŠ‰>¢qùð 4%“.F-·]( 2Qò?È/"?(OV/LB7>*OàtMrA€/¶/tOþ™¿ä™¬û@tjû@<û@}˜ëð*-éòÿC ÿÿòâùõôÞýFÿÆdtk	שëð#)ô9Wtk»3¾ëð
)/y
)HD¿´tk¿Súëð+)tkÀªS9ëðH+|oùSP#$&/ÿFÿÿÖ… ëðïðüóÜÿøñh¾ëðTèçõßï÷ûý~@*ÿÇãñx<¾?þ<¿F
…B¡Pw(¤?Nöñ,fxêñùð*•þ‘•
<žþEþbÝÈbÏb½Ï	b žôNží’N‹ße‹çô×Héòƒ
uÞéò óðÐéòÿÿˆÿï‚øŽwwŒÿˆ‡øøpŒ‹ÿð&8Jà\n€’œŒûwø	ŽˆøÿøýQëðGeneriÿc box wiÿth text ÿand connÿection pÿoints. Cÿan be stÿretched ûtoy dimwenss.ýbéòL&“Éd2ÿ鿺\.—Ëå·â?Jõó?¶ýó¿ÿ‚öüÌié¿ÿò,˜šhã?ö?ì¿ð÷ûßý~¿À4ßï5÷¿DÿHÿÿÖÕ"ëðëðÿþò×&áúùð}hT´èóÿ@ßï÷ûý~ÿý?,L&“Éd2ÿù?@·\.—Ëëåò=éFâ?P^
+þq¥u
>~Gþÿu` îèóà?¨uô¯	qbþ«bØß	ß(ï¦ëð÷Ró÷ý***ø%Û€L@þýÿýÿþ_ú
A€`9Copÿyright ©ÿ 1995 Viÿsio Corpÿoration.¿  All |sÿ reserveßd.þr`ÿShape.hlÿp!#15000ÿþ£2„{løUXB¾aþïÊóó@æõ&Z©­¹¿ª&!
ùð
C D*B >/èóð¸-,>b/t-ª!'’/ /´¶/)rrC Õþ01É‹¿‹Ø#0 þ#0hŠ‰>:qr 4%QÐ/·é-QZ/l?~(Á,âÑ/'.·PÀš?ä?†/Oª/·™_䙬k@tk@5tkÇCý\GDd0tk»#+)œ¯Ctk$cLëðH¾+T?tkpc,ÿFÿÿÖ… ëðïðüóÜÿøñh¾ëðTèçõàï÷ûý~@*ÿÇãñx<¾?þ<¿F
…B¡Pw(¤?Nöñ,fxêñùð*•þ‘•
<žþEþbÝÈbÏb½Ï	b žôNží’N‹ße‹çô×Héòƒ
ë{êñ óðmþïòÿ3ÿÿ‚󎻂óƒÿ»¸ƒx{†ê·‹‚»ß³833»‚»ßƒ»!»ß³ÿÿ-»ý‡B‡‡‹óßó»{ùD…»û{W‹™ó»‹aV»¹;»†_»°yn†`þ€ƒ3ƒƒ3‚{»Ž†zeo»»¶VaÂü¹Ë‹»3“3;¾ã°	™;Õ
ß‹°ÿŸðþ‡x¿pÿÿðxd‡{»	ÿð;»(¿{°ƒ‚‡›»Ý‹ƒ>Ï{ÎHƒ‡G
Ž3?óÿóýnëðConnecÿtor withÿ up to 5ÿ legs. Use cóö ÿshapes by pointö2, ùñalkiÿng glue ÿmethods.VýbéòL&“Éd2ÿÙ¿¸\.—Ëå·â?Põó?¼ýó¿ÿ¼ÆfОŸÙ¿ÿð,˜šhã?-À?ò¿üüûõ¿ÿHÿÿÖÕ"ëðëðÿþò'tâùùðhÏT¤úñëð@àï÷ûý~ÿ?,ÿN&“Éd2é¿ÿ@º\.—Ëåòu¿>ÙFâ¿P
ÿu`ÿu
`þÿu
`u`ÿ€A@þ>bþxu¿äb™ø„¤uw` èóà?»÷uÂ	§bˆàä÷	äþ.pG	þ
€
ùð()Hÿ@@Çãñxï@@L@ù?@ÿ„Á`0ö?#Œ[‹e‹én‹wþ:	>PúñÅÉ/ÞàºÃÕç41#ç".-!ð/7/I/[$§nh~a¥õ¦õ¶"
þ´!
tN`_€s@Ç!Ì&@<w#	#%Sƒ/íâ æ/ø/
?ø%
ö€L@þ-å €0 z0

*Qû2U¯2Õ?2Ÿô­I¸0Ï?®4Ŷ5¿õ?brL`û-@¼ r_À	Šå0ÿu`€.@þDÜ›ï0À
AÀr¼ äDÀ
~ï0	À€@=@rP×€‹ÿ‹\Šï‰ÅPüSi› 0åöéò7'"T¼?ëðÓ@éŽ3ëð”ÅP%p» h™0(Q–@¯œ  ½
AâB„À¹qe@þ°i mBq¯ºpg@åQ­ ;›D‘¬ŸéDBßuf`uga€i-@äd@¯¡´¯ia°žˆBاkã¥àê7Bß{Bþ»
&aÎc<°3`/0aØcR¯t¿œ yj¤w¥€f@þ°mB¥¶h§¦/±¯É¦Ø§Ajã¥Ì°î­¶Ø§lº8P/´"þ(=»	#K²RPµ@À[¹w#g²$l¶~¶á.ï|¸šÅ˜¿Zª±t¯¿€u§¦5Í¿ɯۤvã¥èÀþ¿¿Ý¢áwºV0³(þ!dJ±ÐaHƒhÐ%/ÚaþRƒ¢T¢8:“лXd)¡!Å£ýVýVÃ@¶Ã@ôTð?Ãð‚rŸ°v‚fï`€n@Û£þúìÐðÚg`€o@4Ø ã)j¬€x áx%Û ¡â&Š¬ûÄü1ÓÙ¢€m@þd5?³;"((¬âP±j¶ÍcQƒGƒ3`8»ïÍí“€“â &‘ï4?F6íX€-#ÿ5ÿ£ìC6¯éX:ž)¢}˜ëðÒ-éòÿ²‹ÿÿÞâù"ÜÿÿFƬ?tk©ëð}#)ÔLtk¼3ó
D)EtkßÆeëð
ÿD„tk+î+)¤Dt«k,cAëðH+TïKtkmcðõ,éòêñ#‘H$ÿ‰ @Y,‹ÏÅb'@öñéòýõ,éòêñ#‘H$ÿ‰ @Y,‹¯Åb'@ëð$éòûõ,éòóð#‘Hÿ$‰ @Y,_‹Åb'@ëð&ëð_ õ,éòêñ#‘H$ÿ‰ @Y,‹¯Åb'@ëð/éòûýláú@Fÿ”EtkÛé)ÜÿýòÄû+Ltk/R'-ýò43\'ÿFÿÿÖ… ëðïðüóÜÿøñh¾ëðTèçõàï÷ûý~@*ÿÇãñx<¾?þ<¿F
…B¡Pw(¤?Nöñ,fxêñùð*•þ‘•
<žþEþbÝÈbÏb½Ï	b žôNží’N‹ße‹çô×Héòƒ
uðéò óðâéòÿÿ3ÿï‚󎻉»ƒß3;»ó;á„%
&„3ÞAƒA»³ï‡3'»ˆYiDƒWaàD5¡	

3óÿóýHëðDrag cÿontrol hÿandle inÿ center ÿto creatÿe a treeÿ with upþsix branches.ýbéò¸\.—ËåÓâ¿æõôô?æõî,ÿ˜šh㿤ÿ1ÓžŸÙ?à¿Æ›µï?¿ºõÿ
ÿHÿÿÖ	Õ.ëð	ëðÿþòW&áúùðýhëðTdþèó@Clb±Xÿü?@ßï÷ûýÿ~ÿ?@¹\.—ŸËåò?@æõJâzRPãøÿu
`u`äßbþ}uï`u
†!)„ˆ•’þ©€@þûSþïu` èóà?îÍuÔ	ù¯£€@þObË}	^*#@øñ6#:D#9DP#9\#9äh#9t:+$**øðDP\øht
z*6»Õ–OnBº¸N@A#ÀÿA¿Ö¿ý$%##" #+-™Œ.*ÀW*wt(
bE˜#âùzÁçaþ¦+€L½@» 2ÇqÕ ¬Y?Ô/æ&È"‰‘þ\J?QoÎJÒðÝäW4Ò©äÎÔ Ô	9þó`Q(-DT¿û!ù?
¹9
Ï@:6¼4	@€@þ¸#,ð¸,6ýÿýÿéþ@¦+A`9Cÿopyrightÿ © 1995 ÿVisio Coÿrporatioÿn.  All þ$Bs reserved.þÿ`Shape.ÿhlp!#150ÿ60þ£ÎÿœÐ‡žÿ„ˆ¤pÿ FŽû›?l^%U„s´!¹¹ µ a±A ¶@7rêÅ€3‰ð?Æ$p1áJ‹Jߊ‰'tlœA }$¨OкDñO_‹F#"åGS†Q
àS’QèNžQÜSªQSU"O$™
™™í™PW8f]¿Ìd2Ù¿PÛròQÀþôPrò–Àí1¥@G?¶EÊd2ùè^øñøýT~P`‹àú?`¬V
lœA¼¡OC_U\ô]Ž` ;bà^çoio¹gª/h;d|?`FGh¦‚'PWoio{ooŸo@ÿægﮃ™3¼xV¢g
@r2íx~P1f
v$!3EWi{ýT¨Bg£I…\1fËvçù/AûV®gk•h1f	“v¯ÁÓå÷	ŸûV´gÞP5ŸóS$t1f[Ÿtp“ ,cœ2nœŸ„îbbʘ!n3åfþãG”§L1¿
c8a¸_aÜo^¯€p¯‚¯”©ò£®µ¯Ç«Ö¦üŸö¯¿¸m4&4Ð?ž«Ò”<´¯Æ¬
Ö¦
w¿‰¿›¿­¿¿¿(Ñ¿ã¿Ê¨Ö¦ÏÏ@/ÏAÏSÏeÏwÏʨÖ¦ŸÏ±ÏÃÏÕÏçÏùÏßúʨÖ¦¢ìï¢XËÐÄ¢«0ÓЙÇÐ#€}˜ëð*‡éòÿOçÿÿòâùÿFÆ”Otk_¾©ëð#)ÿtctkgõkëð
)dLtkõÒCRGD”Dïtk$+¾)„Rtk%c8úëðH+ÄTtk]c/ùˆÜÿáúÿW|
tkIï
tëð4D¿ütk½üëðdãøsdfiÅný<Ð'0rŸÇqÇÁý@•Wb7õfþëð”W1o½:H0Í?ìß>r@Þú5æy/gÞ™ 	HëN|s,O>AauJCjufC|uXL„uO‡L:—EåS`¨@Y
›B‚
§B ›B¦&‚ §BÌGÜ×FˆáO,hþIbzw6YŠ`‰W‹X»€D»€0»€ÒvW×@„YÝþL&“Éd2ù?·«^éàÀSãøSDF? files½PÄcàÇ^|uTc&‰fa&‰BoTc‰fa‰”†e‰faà‰„ÌVyv*a™´ª­` ­`l­`8¹dÈ Ùoëoýoo½6"e5tRâ;Èg`wÿ‹œ#çȹ@¾!À<@@ðr¿Ú!°¼¥¿¿–|ÿ0Oè´N—k?§—Wþbþh~`w&¾‰oâppþù6ʼ3ïÌ;Š5PIp$p?´ÿ€@z3@þ2<°@¿RµpÜ`±Äw²N¹v¿R²°óä†Ü
ÿtN`zs@þ»°¿°òÏâP䌜GÑ-eͨ@«ªnÁÚ?@8£Ñ?ÄåÊÅÁ•zèóœb¿„7¤‹ ¿v…IÏBW©ØMéH€u‰{ÆÐ¥6Vͨ Ï²È»¦ÆÏ䡺l»yT€èƒZ<{êñN÷‚鿺º£S¿²Wp¿T˜Èª‹	É·ÏÜS@‹Á`0æ?ÇÖ‰Þ‚ÔŠÒÖ?7@Ð'ø©¿´ß¬ÕW¢Y# -# g…³`Äcöñ]Š!³µ@³³¥ð?³ð*¯žW<¦4åöäƒ4¬K¯W)oX¿8ÒAô6à=Ðñ5@v¿d@@T@õÿO@@“ò£ü(?ê?`t@ÑãÀas”>A¿åJCÈåfCÚåXCÑå܆M"—@ç `òWlòkðÌGÄCÜïþ@Ñæ¨ÿØç 6YÐÿ°üÏÔå÷rd–ÊiMIF/–À–…ãìP•`ùfcb÷âçLklùfalùÚý*bãîúT×棔­`€¬¨¯ Oe5¯±gïv½:>ø“ïG–…/bê§uˆ|&žBÔ»0ÿp‚H¿“Ï–#¶YÀœ#£/µ/y…Voˆš? ? 2?ÍAH?Z?k3s6þ™ource
code/–nÅ!]P‘!W~—¨ŸáoxV¸šÈTÌ–®ÈT™T @ ,
 ¤ˆvOM_¬OÊc ƒêÐOâOä®7e8rŽ­ 
Æè’Öƒí:Z…ÿ&-…”y_Lý4]ò«©€!9Ⳃ²€–!9âÅ‚K•"h@œ%Öä_ö_Ý#†Ÿê/ü/Mo_o qo”²ˆošok2²oàÿRTF
(& HPJ)’?*Œ©‡¤©‡)‡T'·1³‰Å‰Ó1/¯Ëƒ#OáŸs¨ROdF2uO¡³‚ƒê§PÚü¥îxô$=IOö?ÇçVÞ"V3=W>µW&-q_‹Ü#@_ð)«á°׉²äö€oÎ?Ÿ=ŸOŸaŸsŸ¨†Ÿ˜Ÿk4s6
OøHTMLÒob¼á·¤€á·÷oÉ-Hb¾1yt
^@`^@L/}‡O™O믂	ƒê	¿"¿wĶ°-lÆèŠÖ%ãh¿:Zå¿&-%广˿^ñ«¶àê¿ü¿^Ï$çìï=ÏOÏaÏ@sÏ…ÏᱛϭÏk3	s?þ…1lain
tex‘7èÆ7ì¶ç¤¶ç6ç.ß+J7î%gßyß‹ßP߯ßÁßþ 
×Ú
åßö÷ßÐ7e¿´/íKû
>ï;Yî dïiˆïšïBñ"ܲÒ‘ÍÒ›š–+ÄÍïß)ÿþ9ÿDKÿ5>
oÿÿk4
›öÑ€6ODÒ–5¶äŸÔ‘Ó‘¯Ó›A›P­/‡¯I”^@€^@lZ¨fȯگœþ e×ÚÀÒø7e~¿ß
õ;Yò5?Qc…_7¡XÈ“¯]‹Ò¹@%ÍÒÃBÂ@Ñ_è¸ÊÜ@î/*_$/6/tnZ/$l/}$ÆÏÄaGÝȧ/ú͹GÓ¹Gã/ÓÃI1ÃI?Ú_;?M?_?q?ƒ?•?»{·@T€VÇ3+ÿÿ•‰¼Bø ±¡‰„õuÔ•A;Qô1ýÿ~@@8ñM|¿ß@@€˜RÉôë'óμ3ïø¿PîE@§úŸ¨‘š`¯ü%¯­†œö¥}i_…âG¡ïE¤§^¯¨‘Hu¯‡¯!˜¤¥£2QñE·Â¯¨‘Ù¯ë¯5¯2QòL¬#¿Ñ¢(’Ä)âªc¹´ÄSU»ÇpŒãÑp`8TƒžN¿
àr™ÁÂòsùtÏ(ÁzæŸú¿Ç…QvÂ#ËvÏCÃK®ZÏÇ2ÄÖÂ#ËÖÏC﮺ÏÇ€‚6Ò#Ë6ßCþßÇnñ–Ò#Ë–ßCÃw¾zßÇY!öÒ#ËößþC¢ã¢ƒú+à#+àâc7àsQC¾pnú	iÂ1p4€á³°lÇo*9b)ß`
²¶1Á‘
ø ôoYQÚ	#u:þA¢@@æygÿÞ™ @@@õOOýSÿä´ˆêãÔVx¨(Kh€Žw–£uÓbp«zR`ô$ï=IOßèâñxO<ßçÞt9``~òò{~ÿ÷tpO ˆ‚´òòy³ÿörŒçá´“B
ÿtN`zs+@þøðüðÎ<¥Œ
9b%%ö%Ñúï@«ªXS`ƒÑ?QÊYéÁ&JÜ…jå€?¤«é€~Ø@I°k±ù† Ÿ€Y€üîÉÛíÿðè[Ql„\_nT…`yY»YªcN®˜R鿺½³¿{'
D×°µS˜ôï’TT
ùû`«&‹Åb±·XÜ?Å¿Z¿WÖ•ueÝÍ̹?ñé¢Y7à-*;âØ@dÍTD=&
 ªc@O$ª7UO$ðÀ ž9b<²PšcLì Ø ^ïpï‚ï”ä¶:6AôÇ?Ù=Ä7U7Æÿqc@@Y‚– %h@@“N€#3O.J5CC5QOP"6mOyA§IA€2ز2±0Ñ@„ÚD¸äOöOù£#6î?)_;_€M_5q_mq‡_™_¯ãú²Vï(Windows
HelpËV«4=ìU²9a²947PDoÍO'Xslt```ÅL‹hˆ—oN4°ob)Åo×hÕ*Û"è/úú+ؤvdÿ@@ÖÀ5p
\@lg9ýåYf
cÄE?W0òUb3ûUƒmePp3
eŒ?ž=(A€2È“b’`À1&¥b.¿1Ä7ÊÏ6« Àá4Geü lÄnÔ&g ¥ájÀã‘ÚngþNxT\pœ™ŒN ÃQ®¿À±¼µÌ·¾@‹À"E~áC“ióA“ioâ9ùx8~áC¥ióA¥iíošQQ”V_¨¸ ÁCþÐXfmbatch@j_$…„_zaš_¬VÕ*ðÇ_Ù_#D8rŽœ#ç
ù_ooN9• CoUogoyo‹e2»’dºÀ1&Í’²oÄoÖoèoúo0B@Tfxr‰‰ŽKª¼âB»™óA»™=Ÿ%‡Í™óAÍ™¯]o[Word’¤¶Èˆ˜àÀ0×(ìþèW5#Ÿ5ŸGŸ1g?ÅkŸ}Ÿ€Ÿ¡Ÿ‹e²2æCö@Û‘2ò¿2ߟñŸ¯s¿ã¯q¯K¯]¯o¯¯“¯Á©¯»¯¯áÒ¯ä¯âBòÉóAòÉbÏ)¿;¿%‡àÉ óFåÄ:ß…¿oÈHƒCP·¿É¿Û¿í¿Ñ $Æ ÑùÐÃÿÂÏÒ3Èá0%B5‚Áß`0`%à¼j«¿·Ð|õÄ¿tÌÿ0Oè´¿Nk?4Fô&ÃÀ¿Äb÷þ·>Ç,AKг´rð6ØAóQÚoÐ7`pùÐþÿô€@z3Ë@þüðppA 7	6PϤ#Þ3
ÿtN`zWs@þ{ƒ’ÌÝδ7ÑEø@c«ªÖ;0óÑ?ÔåÊÜÁsÊP#œbÿ„7¤
¯v* I	ÒG©ݾ%Ö€I;õFø`r{ö†ä‚ñFAlGOYD€êcJqNNƒB鿺º‹C¿’GpùÔ˜È6KÉ	wá0?ð@붰-lã¿ËÖI.B$ûJ"Ó¿ÿ@4Ä1CÌÀ¹¿t/l%¢YŸ -ºŸ ùÐ…dÀDDˆ^—Öîä@Ò$ 0¸óðU?Ò$ðà@ž¿ò<ÛæA4£6oôìÿ¿ò)²P…'ú5ÿGÿY÷–*?À
°¬sõ'@Pû—6–ÿ¨ÿºÿÌõûm	—Õ?á@—€@ ùõ"Ñ!BO.@ SBDSOdv	ƒ	¢»’ú£
ºÀ©8Ôæø
.@ZS¬5pÙt_†_˜_”;°Â"swßñïÔ/ßO§_m%ÛJ#?çGenl&ecÓ?@T%‘n˜/ª/¼/Î/à/ò/??(?Š:5'úQ?c?Y÷@ôñ†?˜?ª?¼?Î?Äý‰™xü6›vLøq 9‚9.So‚D(o€Ov	ƒ	¬O¢)÷rà‚à‚à‚ÛOíOÿO_#_5_G_Y_k_€ù—Ÿ©Ÿ»ŸÅ_×_Íû_
oïÔ'oûß]oooo“o¥o·oÉoÛoío@ÿo#5G=2'úÑmY÷6KÀ×ý¢xðï÷ûý~„ðɳ߈§Ðâôê?ü6×öO;O2O(ÊÑ A‹Ïœ’Oˆ‚Í âã/êÀÛ¾ŸŸ0ŸBŸTŸfŸxŸŠžÛ¾€´ßÆØ϶ÚßäŸöŸÐ¯)¯$C¯ßËßA%fYWÖ•uùˆ¨üîl&¯¨)jŠšô´¨ÉîЯâ¯ô¯¿¿ *¿<¿N¿`¿rµC:艿›¿‘w>å²@@ÿ‚Á`0@K@àܵ0·uåóÏìõðê¿ü¿Ï@@,AïKдâð?P?b?t?†?˜?’rµ{¶ÞAÕrÇ1ô!\Ú9ØØ•¿´/íÿKû@@ÖÀ5þ¸°@@’ò£ü¿(?ê?@95c?ˆ„gP&ƒÄƒZ°s	‡þ’³p†\†\%†WATDTA‘‚êyÅ(Ý€	Ò¬‚«€gKB¾‚¹¿„‘©RÊ?`´[qÁÖ—8… ÐªŒÄ-ŽÔƒW „±ƒMÀò.‡ÐU*ŸÏTuPgQŒ	ªÜqˆ[¹1£?¨•.8§qE¤ÀV¥žcpE ¬‰•@¬‰.Jy€¨Qžæ“¾‰ø‘¾‰Ÿ»™o°™`w L*w 8w p¨²p>sýéxpod2..E.‹v<†\¤|X@TAT³KB1w°ÏzI@ôàÖ=Ä@•þ~¿ßûï÷€Ñh4FnpåóÏ°ÞܵåöN³Ï?Q€3µ\ƒ<µxƒNµ jƒEµ†˜¤ð¾‚P¾‚Ó°ºÒ‡¸Ý†ˆüHLäùÐÏL·<™8ÏɤBoTc?`&é…^L.}bù?·±ž²pbãý¸man paÿges, Latÿex, etc.Ã>sºUV½ßå”Ô¹T¦Ù´'·BÍÏ¡W¾Š&K¶SÑ™t{¯ù°¬¯œ-Cįbٯ먗úÁ?¿É÷†*À
°¬ouÐð¦ãÀôð0ì"O4OFOXE:¶
‡Õ?Lá@
‡€¿@ i
î­@¼â~¼ïºFÜq¬A òâÐKòïðOæ	
Y_¬‚ë“ûš0Bî`_r_„_–_¨_º_Ì_ùóKå<™%73ëùg?y3Ï’³º{ùƒÅ«?½?Ï?á?ó?OO1ãƒÅcyKï]ïoïkˇO™O"¶OÈO¾âO¶ß`~ïü¿Ö<þ'°ÃM ?gÿo__“_¥_·_ É_Û_í_ÿ¿eþø(Ï:ÏLÏ@^„áExfÈ â‰Ï8›Ï­Ï¿Ï@@2LþVf‰D"‘H$ìÅô$å+6µqÑF;FWßiÙ‚Ó_4ƒßy3á›5‡³ÙŸÇßÙßëßýßï!ï3ïM#Ÿcyg/y/‹/‡£ïµï«GÒïäïÚtþïÒš/4þÛX>_ÿ°ðwúŽ4‹ÿÿ¯ÿÁÿÓÿåÿ÷ÿ	”e Ê DVù~ºd@@†mßa[ØV!ò5À¼§@€ð‡‚<5°§E¿Þ¦
ü1	BÒ@ÖC¹ËÏèÄÀÛ“@ßEg]YçWÖ•@ŽF¥}i/_Ú!ìÅ!,@RÛ@_!Ö~ÑvR7Ûv_DsÒ@ÖNxnÔ!vÙ)ŸÒ@ÖFµUŠÞ ÎbªP5b²×¸@p»ßï·â¨ô/ ž s  2*$ Š¼0],$å4/F/<ì3ecv0hÇoÙh¦@ço€§G¿/Ñ/«wü4ô/?ÿE 6èL‹0iÞo`ùIÒ€rõÀ³q¸rÀuÿ`u
`u`rýÙ@Àuf`ugý`¶€k@u`÷b}iyÿ<ž?€d@þþñpÓ¾´/íKëῺF÷§2§W@×¾ùrÛ¿@Ð'Yq©©¿+§7«®0v¶4Õ¾6dÈ?Ú?ì?þ6ÒOÚB	µUCZO O2ODJE!ÀVBÐbD•ü\^8jV~YÀÐ="@@?¸"oô?@¸"ä?g”„wq“Ô^jûƒT—ý±$^–ý±g–ý±p–
Q¥××Ü2’q¬?åŸ÷–å@™’÷–§’Jªª§Ó°pè
QÖkKnÿ„‡‘,"(ŒnÑw‡ƒ•ÔàhœÔxžä^g à	ô黯«eÕ¯sT °+wŒ8z”'‘+¹ìã?Sµóç!Cq4•eï}¿Ô±ž®‘¹Ý¸`@iÏ°cl¤¾±¯™tÀ@ªÀ,ÀÀØ€ˆôý€Á3lHany ÿtext
editorÖ†xkKîÓ¡I¡š‘Ev
Q×R××þ€A´ðÐ’ùÄŸmj„\Ã1¤nF@ÏÏÇ03ñÂó¿0èÆ«f£¨ÞƧ’Ú×]!ñÄ?ÑùÆ“ÂK×tRJ •Îœk”PXÃ1N8˜Q¢	À*Ï2"6쀣Ӵ-Ÿ[Øõ~¿Qÿ@@M§Óét:ÿ@@’ò£ü(?ê?@9¼¥ìÓB`õÓÄŠŸœÚÕ§“ãÕµ“ ìÕÓõÕÑžal8pÃ%b{âzàu 'ìÎâ't¢„~¤Êp‹®vˆå$« ìÜÄüÞ‰˜ ?ƒ@æªßï¿÷!¿3»‘E¿W¿fA"n¶À$5èîͳ{éß±{éýß¿ïçò þͳ éß±éÕïÁ”À`ªÀLÀ8ĨÆþ¸Øsgml2..%.Ö†Æ4v:ƒ¨¿lÖo½)î`&òj&ìÐûÖ•uÿe]Ù@@ͼÿ3ïÌ;@@Dÿ÷Ð=tñ¿@Uà¿[´ácµÏb}’‡™s¬èÐÔ¾rîWB@@NPâÄuÆêrð²(Ù{ð¿ùv–’%Ë(&Ï/A‰#N‰[mƒÚ}áÚÑæ™x´Ÿ\±ÃœjØ€?Ü€à€~䈱ðépŸ
™M¶R©f˜EßWß”@f´eP\¾{ŸŸ[÷&ªŸ€¼ŸÓןïi]c¢&°@¿èóù|>ŸOp@ÍðsA¿¿7ï/ìç¿ÿ@øõz½^¯Ó€Håjè/åk¯}¯¯¡©>u¥¥¿¯Ñ¯ã¯õ¯³e'òj'¿.¿^Ä~³wù§þ©ê	¢hV@®óø˜‰óÄb}
{8`	²ðÀð@¸ñ~pu£¿™£'ßéIz’²xO(_
…Bèµ"üÐ!ƒ"Ù{ ùv£QÁV‹VÞq²ð2`¸üXÏF„¤ZƒS„$N‚²ð¶ö •†Î9b"c2j'M(›õ¸ÃÏÕÏçÏœžØ€sªÜ€2à€Šñ]è„åߟœ›õeYŸ±ÃƒûŸß±ß”'¶ñÑßãß11E'úÖèàžÒ}ùJÀÌ@rõÀ“!˜"Àuÿ`u
`u`rý¹ðÀuf`ugý`Ì@€k@u`þ¿°@‘áFÂÿÒ©?€d@ÿþû@…B¡P‡(ä?Ø.c¢‡Ôþé$Ô?@3Ä1GCÌÀè%8c§«Žàw–äÕžæd¨ïºï¨¯HÞæ²ÿºò•çãZîïÿÿ$øýdéò#ÿ‘H$‰ @Y,‹Åb'@éòÿ#$&'ÿ()*+ÿ,-./ÿ0123ÿ4567ÿ89:;ç<=éòöð5PIõðVýáú@FÿldtkvMgÜðý>ãøÿÇDwtk%ÿ^(4ÿDtkrM÷ëð?V_ÔtkÝÜòÿ”ÿÿÿPage-1÷õðBlacÿk fill}õðWhite	õuReýd	Greeun	-õðCya@ÿYellowê	GõðMùðntaö3ay(10% üx	lineõƒõð3…Long dash1š"—dar IÍ­9ÍÀeÍ.X®Í5…7…9…1pxl™¢m½9mHairq¿Short¸
ÿArial cþkeredü™°top leŸftœÁõðT/imesµ¼™äôÞÊáÁ 8ptþµ¼CirûclÃBoïx!JonnÿectorUnivers³2D'A < .4i U5m$6m$7m$8m$M9m$10¾e$1ýðý˜9 Multi-ýt= squar•Ýtéò#òð‘Hÿ$‰ @Y,ß‹Åb'@ëðýõðÿ	
ÿ
ÿÿÿÿÿ !"¹%éò`
hláúÜÿ 2åöÿ@F






SDF 2.001: The SDF Document Development System




      

      

      Home | Catalog
      

      

      

      

      

      The SDF Document Development System
      

      Ian Clatworthy (ianc@mincom.com), Research Architect, Mincom Pty Ltd
      

      25 May 1999
      

      

      

      

      

      Table of Contents
      


      

      

      

      Abstract
      

      SDF (Simple Document Format) is a freely available document development system which generates high quality outputs in a variety of formats from a single source. The output formats supported include HTML, PostScript, PDF, man pages, POD, LaTeX, SGML, MIF, RTF, Windows help and plain text.
      

      SDF documents are simple to create and maintain, minimising the time spent on documentation. In particular, SDF directly supports the creation and maintenance of large, on-line documentation systems (including intranets) via centralised hypertext management and rule-based hypertext generation.
      

      SDF has been completely developed in Perl, a popular and highly portable scripting language. Like Perl, SDF is freely available for commercial and non-commercial use.
      

      

      1. Overview
      

      1.1. Introduction
      

      SDF is a document publishing system which aims to solve some common problems that many software organisations encounter with documentation:
      

        

      1. How do we support multiple formats (and produce high quality output for each)?

      2. How do we reduce the time it takes to create documents?

      3. How do we maintain a large on-line documentation system?

      4. How can we generate and easily maintain hypertext links?

      5. How do we keep the documentation up to date with the code?

      6. How can we centrally manage corporate formatting standards?
      

      The basic design principles are:
      

        

      1. Documents should be specified in a logical manner.

      2. Make common things easy.

      3. Give power users full control when they need it.

      4. The architecture should be open and easy to extend.
      

      The key feature of SDF is the division of responsibility:
      

        

      • content is supplied as text files or generated where feasible

      • formatting is generally implied by the semantics of the content or supplied by rules or external templates.
      

      SDF consists of the following key components:
      

        

      • SDF - Simple Document Format, a text format for defining documents

      • sdf - a utility for converting SDF files to other formats.
      

      Unlike SGML, XML, HTML and many other markup languages, the SDF language has been designed to be author-friendly, rather than parser-friendly. As a result, most SDF documents look quite similar to plain text email, making them easy-to-write and easy-to-read.
      

      1.2. A Sample SDF Document
      

      A sample SDF document is shown below:
      

          # Build the title
    !define DOC_NAME           "GalaxyBuilder"
    !define DOC_TYPE           "Discussion Paper"
    !define DOC_AUTHOR         "Joe Bloggs"
    !build_title
    
    H1: Introduction
    
    After extensive market research, I believe there is
    an excellent opportunity for us to develop software
    for the I<galaxy construction industry>. Potential
    customers include:
    
    * NASA
    * European Community
    * China
    * Japan.
    
    Note: The proposed name of the software package to be
    developed is [[DOC_NAME]]. If you want to suggest a
    better name, send email to {{EMAIL:joe@bloggs.com}}.
    
    H2: Software Requirements
    
    The key requirements are:
    
    ^ support for the design and simulation of galaxies
      containing up to:
      - 1000 large planets, or
      - 5000 small planets
    + the package needs to be easy to use
    + the package needs to be well documented.
    
    H2: Project Team
    
    Exploding galaxies will be B<very> bad for business,
    so we need the best team possible for this project:
    
    !block table
    Person          Role
    Mary Jones      Project Manager
    Hans Blass      Architect
    Bill Smith      Software Engineer
    !endblock

      

      1.3. A Brief Explanation
      

      Comments begin with a # character as the first non-whitespace character on a line.
      

      Macros are embedded commands which begin with a ! as the first non-whitespace character on a line. The define macro is used to set variables. The value of a variable can be embedded in paragraph text  by using the [[...]] syntax.
      

      The DOC_NAME and DOC_TYPE variables are used by the build_title macro which creates:
      

        

      • a cover page (or two) for paper-based outputs

      • a title header for online outputs.
      

      Paragraphs can be tagged in different ways. For the vast majority of SDF documents, the only tags used are:
      

      

      

Tag


Meaning


      

      

H1:


level 1 heading


      

      

H2:


level 2 heading


      

      

*


item in level 1 bulleted list


      

      

-


item in level 2 bulleted list


      

      

^


first item in level 1 ordered list


      

      

+


next item in level 1 ordered list


      

      

>


fixed-width, verbatim text


      

      

Note:


note


      

      


      Phrases can also be tagged in several ways. Any phrase can be tagged using the syntax:
      

        {{XYZ:...}}

      

      where XYZ is the tag. For single, uppercase character tags like I (Italics) and B (Bold), POD-style syntax is also supported:
      

        X<...>

      

      where X is the tag.
      

      Tables can be specified using the table filter, typically in combination with the block and endblock macros. The first row is the headings. Remaining rows are data.
      

      1.4. Generating Output Formats
      

      The sdf command is used to convert SDF to other formats. The general syntax is:
      

         sdf [options] file ...

      

      If an extension is not given (and a file is not found with that name), an extension of sdf is assumed.
      

      The most commonly used option is the -2 option. For example, to convert mydoc.sdf to HTML and PostScript, the respective commands are:
      

         sdf -2html mydoc
   sdf -2ps mydoc

      

      These commands create files called mydoc.html and mydoc.ps respectively.
      

      To convert mydoc.sdf to a set of HTML topics, the command is:
      

         sdf -2topics mydoc

      

      This creates the following files:
      

        

      • mydoc.html - the table of contents

      • mydoc_1.html - the first topic

      • mydoc_2.html - the second topic.
      

      By default, topics are created whenever a level 1 heading is encountered or a file is explicitly included. The -n option can be used to specify a different level for splitting into topics, e.g.
      

        sdf -2topics -n2 mydoc

      

      1.5. Requirements
      

      SDF requires the following:
      

        

      • Perl 5.003 or later

      • for generating PostScript, the freely available pod2ps program or SGML-Tools and LaTeX packages. Alternatively, you need a word processor which can import MIF or RTF (Adobe's FrameMaker 5.x is preferred)

      • for generating PDF, Adobe's Acrobat

      • for generating Windows Help files, a help compiler (e.g. hcp.exe).
      

      1.6. Architecture
      

      The architecture of SDF is given in the diagram below.
      

      

      

      2. Alternative Systems
      

      2.1. WYSIWYG Tools
      

      WYSIWYG (What-You-See-Is-What-You-Get) tools are great for creating small to medium-sized:
      

        

      • World Wide Web documents (i.e. HTML), or

      • paper-based documents (i.e. PostScript), or

      • Windows help files.
      

      However, the WYSIWYG approach is inefficient when it comes to creating and maintaining large documentation systems, particularly if you want high quality paper-based and on-line outputs.
      

      The reasons are:
      

        

      1. WYSIWYG is meaningless when it comes to supporting multiple formats. For example:
          

        • paper documents are formatted on fixed-size pages; on-line documents are formatted as topics displayed in user-sized windows
          

        • different browsers may display a given HTML document differently.
        

      2. For good-looking results, the formatting rules need to be tuned for each format. For example, a certain phrase may be:
          

        • a hypertext jump within HTML
          

        • emphasised using italics for paper-based formats
          

        • a pop-up window within Windows help.
        

      3. The content often needs to be tuned for each format. For example, you may wish to describe a given procedure in different ways:
          

        • in detail for a paper-based document
          

        • terse for on-line help.
        

      4. Centralised management of formatting rules and hypertext generation is essential for minimising the cost and maximising the quality of a large documentation system. By making it too easy for individual authors to customise formatting, WYSIWYG tools often make it harder for workgroups to centrally manage formatting!
      

      Nevertheless, WYSIWYG tools are often used in combination with SDF when they save time. For example, diagrams can be created in most packages and imported into SDF documents.
      

      2.2. SGML/XML
      

      The SGML/XML approach of specifying documents semantically is an extremely powerful one and SDF uses the same approach whenever possible. However, as SDF does not use document structure rules and DTDs, it is much simpler than SGML. SDF is also more readable than SGML, so high-cost authoring tools are not needed on every desktop, making SDF much cheaper to implement than SGML.
      

      Like SDF, XML has built on SGML's good ideas but minimised the overall complexity. However, XML has retained SGML's unfriendly appearance.
      

      2.3. POD
      

      In many ways, the system closest to SDF is POD (Plain Old Documentation) which is widely used in the Perl community. Like SDF, POD:
      

        

      • is simple, readable and free

      • supports a large number of output formats

      • supports literate programming (i.e. POD documentation can be directly embedded in Perl scripts and libraries)

      • is built on Perl.
      

      Currently, SDF has several advantages over POD:
      

        

      1. SDF supports more features, e.g.:
          

        • tables
          

        • figures
          

        • formatting within example text
        

      2. SDF is more extensible as sites can add their own:
          

        • paragraph and phrase styles
          

        • paragraph and phrase attributes
          

        • filters, macros, etc.
      

      Furthermore, versions 2.000beta10 and later of SDF are POD friendly:
      

        

      • POD can be converted to SDF and vice versa

      • SDF can be nested inside POD and vice versa

      • SDF is largely upwardly compatible with POD in terms of syntax and functionality.
      

      As a result, POD users can use SDF or migrate to SDF when POD isn't powerful enough. Refer to SDF for POD Users for further details.
      

      

      3. Language Overview
      

      3.1. Basic Concepts
      

      The basic concepts within SDF documents are:
      

      

      

Concept


Description


      

      

paragraph


one or more lines of text


      

      

phrase


a section of text within a paragraph


      

      

style


the type of a document, paragraph, phrase or table (e.g. H1)


      

      

macro


a command embedded in a document (e.g. !define)


      

      

variable


a named value (e.g. DOC_NAME)


      

      

filter


a rule to use when processing certain sections of text (e.g. table)


      

      

attribute


a named parameter of a paragraph, phrase or filter (e.g. jump)


      

      

expression


a literal or expression to evaluate (e.g. "Ian Clatworthy").


      

      


      Further details about these are given below.
      

      3.2. Paragraphs
      

      Paragraphs have the following format:
      

         line1
   ...
   lineN

      

      Leading and trailing whitespace on lines is generally ignored. Paragraphs are separated by:
      

        

      • blank lines

      • comment lines - first non-whitespace character is "#"

      • macros - first non-whitespace character is "!" or "=".
      

      For normal paragraphs, simply specify the text on one or more lines. For example:
      

         I like products which are simple to use and
   do what I expect. We should encourage engineers
   to design more products with these qualities.

      

      A paragraph can be given a style using the following syntax:
      

         style":"line1
   ...
   lineN

      

      Some commonly-used paragraph styles are:
      

      

      

Style


Description


      

      

N


normal paragraph (the default)


      

      

H1 .. H6


chapter heading at level 1-6


      

      

A1 .. A6


appendix heading at level 1-6


      

      

P1 .. P6


plain heading at level 1-6


      

      

Note


a single paragraph note


      

      

E


fixed-width (example) text


      

      


      For example:
      

         Note: Life is too short to drink bad wine.

      

      The result is:
      

      
Note: Life is too short to drink bad wine.

      

      3.3. Special styles
      

      For certain styles, the following syntax is also supported:
      

         special_style line1
   ...
   lineN

      

      The special styles available are:
      

      

      

Style


Description


      

      

>


fixed-width, verbatim paragraph


      

      

. .. ......


paragraph or plain list item at level 1-6


      

      

* .. ******


unordered list at level 1-6


      

      

- .. -----


unordered list at level 2-6


      

      

& .. &&&&&&


enumerated list at level 1-6


      

      

^ .. ^^^^^^


first entry in an ordered list at level 1-6


      

      

+ .. ++++++


next entry in an ordered list at level 1-6


      

      


      For example:
      

      ^ fruits:
  - peach
  - banana
+ vegetables:
  - potato
  - carrots.

      

      The result is:
      

        

      1. fruits:
          

        • peach
          

        • banana
        

      2. vegetables:
          

        • potato
          

        • carrots.
      

      3.4. Phrases
      

      A phrase is a section of text within a paragraph enclosed in the symbols {{ and }}. Like paragraphs, phrases are optionally tagged with a style.
      

      The commonly-used phrase styles are:
      

      

      

Tag


Description


Sample Output


      

      

Emphasis:


 


 


      

      

1


1st level emphasis (default)


emphasis 1


      

      

2


2nd level emphasis


emphasis 2


      

      

3


3rd level emphasis


emphasis 3


      

      

Formatting:


 


 


      

      

N


normal


some normal text


      

      

I


italic


some italic text


      

      

B


bold


some bold text


      

      

U


underline


some underline text


      

      

EX


example


some example text


      

      

Types:


 


 


      

      

EMAIL


email address


ianc@mincom.com


      

      

F (or FILE)


Filename


myfile.sdf


      

      

SECT


Section


Paragraphs


      

      

URL


Uniform Resource Locator


http://www.mincom.com


      

      

Classes:


 


 


      

      

DOC


document title


SDF User Guide


      

      

REF


reference (document code)


MTR-SDF-0002


      

      

ORG


organisation


Mincom


      

      

PRD


product


MIMS


      

      

Specials:


 


 


      

      

E (or CHAR)


escape (i.e. special character)


© 


      

      

S


spaces are non-breaking


section 2.1


      

      

IMPORT


name of a figure to import





      

      


      For single character, uppercase phrase styles, POD's [A-Z]<..> syntax can be used. For example:
      

      E:  I<Please> reply to {{EMAIL:customer@xyz.com}} quickly.

      

      The result is:
      

      Please reply to customer@xyz.com quickly.
      

      This example also illustrates the advantage of specifying documents in a logical manner:
      

        

      • when generating PostScript, the EMAIL style is mapped to italics

      • when generating HTML, the EMAIL style is mapped to a 'mailto' Uniform Resource Locator (URL).
      

      3.5. Types vs Classes
      

      A type (e.g. EMAIL) simply marks a phrase as a logical entity. Rules may be defined for processing (e.g. generating hypertext) for these types. Refer to Rule-based Hypertext Generation, later.
      

      A class (e.g. DOC) is a special kind of type where the entity must be a member of a predefined set. As a result, SDF can validate the entry name, lookup a hypertext jump and do other clever things (like replace the text with a longer name).
      

      Rules can also be defined for processing classes, although hypertext jumps are often defined for each entity in the tables which define the known entities. Refer to Centralised Hypertext Management, later.
      

      3.6. Special Phrases
      

      Special phrases are used for entering things like:
      

        

      • special symbols (like {{)

      • special characters (like ö)

      • images within paragraph text

      • the current page number in the header or footer.
      

      3.7. Macros
      

      A macro is a command which can be embedded within SDF. Macros begin with an exclamation mark (!) or equals sign (=) as the first non-whitespace character on a line. !-style macros terminate at the end of the line, unless explicitly continued using a backslash character at the end of the line. =-style macros terminate at the next blank line (ala POD).
      

      Some examples are:
      

        !define DOC_NAME   "The SDF Document Development System"
  !define DOC_AUTHOR "Ian Clatworthy"
  !build_title

      

      Some commonly-used macros are:
      

      

      

Macro


Description


      

      

init variables


initialise variables


      

      

define variable [expression]


set a variable's value


      

      

build_title


build a title page


      

      

block filter


begin a block of text


      

      

endblock


end a block of text


      

      

include file[; filter]


include another file


      

      

import file[; parameters]


import a figure


      

      


      3.8. Variables
      

      A variable is a named value. Document-wide settings are controlled in SDF using variables. Likewise, authors can define and access their own variables. In either case, the value of a variable can be referenced in a paragraph by delimiting it with the special symbols [[ and ]].
      

      For example:
      

        !define MY_EMAIL 'abc@xyz.com'
  My electronic mail address is [[MY_EMAIL]].

      

      The result is:
      

      My electronic mail address is abc@xyz.com.
      

      Some commonly used system variables are:
      

      

      

Variable


Description


      

      

DOC_NAME


the title, excluding the type (e.g. SDF)


      

      

DOC_TYPE


the title type (e.g. User Guide)


      

      

DOC_AUTHOR


the author


      

      

DOC_TOC


the number of heading levels in the table of contents


      

      

DOC_START


the time processing of the document started


      

      


      The define macro is usually used to set variables. However, variables beginning with OPT_ need to be set before processing of the document begins. The init macro is used on the top line of a document to set these variables. For example:
      

         !init OPT_STYLE="manual"

      

      3.9. Formats
      

      As the value of date-time variables is the number of seconds since January 1, 1970, a format is typically applied to them when they are embedded in text. For example:
      

        The date is [[DATE:DOC_START]].

      

      The predefined formats available include:
      

      

      

Format


Description


      

      

FULL


complete date-time format


      

      

TIME


time only


      

      

DATE


date only


      

      

CONCISE


concise date only


      

      

YEAR


4-digit year


      

      


      New formats can be created and the definitions of existing formats can be changed. Furthermore, a format can be applied to any variable (or embedded Perl expression), although the date-time formats are obviously only useful when applied to date-time values.
      

      3.10. Document styles
      

      The general type of an document can be controlled by either:
      

        

      • initialising the OPT_STYLE variable on the top line of a document

      • using sdf's -s option (which overrides the init macro).
      

      The available document styles include:
      

      

      

Style


Purpose


      

      

General:


 


      

      

document


a normal document


      

      

manual


a manual


      

      

paper


a technical paper


      

      

Administration:


 


      

      

fax


a facsimile


      

      

memo


a memorandum


      

      

minutes


minutes of a meeting


      

      


      It is relatively simple to create new document styles by inheriting details from an existing one.
      

      3.11. Filters
      

      A filter controls how a block of text is interpreted. The text is usually delimited by block and endblock macros.
      

      For example, tables are usually defined via the table filter:
      

      !block table
Option  Description
-h      display help
-o      specify the output extension
!endblock

      

      The result is:
      

      

      

Option


Description


      

      

-h


display help


      

      

-o


specify the output extension


      

      


      Other macros also support filters. These include:
      

        

      • include - include text from another file

      • execute - include the output of a system command.
      

      Some of the commonly-used filters are:
      

      

      

Filter


Description


      

      

table


the lines are a table in SDF's TBL format


      

      

example


the lines are example paragraphs


      

      

title


used to build a title block for memos, faxes, etc.


      

      

topics


include files as sub-topics


      

      

appendix


replace H1 styles with A1, etc.


      

      

plain


replace H1 styles with P1, etc.


      

      


      For example, the following macro includes another SDF file and formats it as an appendix:
      

         !include "tips.sdf"; appendix

      

      
Note: The appendix and plain filters enable authors to construct topics without needing to worry about how those topics will be used, e.g. a topic may be a chapter in one document and an appendix in another!

      

      3.12. Attributes
      

      Paragraphs and phrases can be given attributes via the syntax:
      

        style"["attributes"]" text

      

      where the syntax of attributes is:
      

        name1["="expression1]";" name2["="expression2] ...

      

      Attributes are used for specifying custom formatting, hypertext targets and jumps, indexing information, etc.
      

      Some commonly used attributes are:
      

      

      

Name


Purpose


      

      

Paragraphs:


 


      

      

align


Left, Right, Center, or Full (i.e. justified)


      

      

notoc


take this heading out of the table of contents


      

      

Phrases:


 


      

      

family


font family


      

      

size


font size


      

      

id


hypertext target tag


      

      

jump


URL (Uniform Resource Locator) to jump to


      

      


      For convenience, phrase attributes can be applied to paragraphs.
      

      For example:
      

        N[align=Center;size='12pt']
  Life is too short to drink bad wine.

      

      The result is:
      

      Life is too short to drink bad wine.
      

      

      4. Web Publishing Features
      

      4.1. Centralised Hypertext Management
      

      SDF has a generic object management feature which enables:
      

        

      1. the definition of objects in configuration files

      2. the use of those objects in documents.
      

      For example, a configuration file may have the following declaration of products:
      

        !block products; data
  Name     Jump
  SDF      http://www.mincom.com/mtr/sdf/
  MIMS     http://www.mincom.com/mims/
  !endblock

      

      If an object with a Jump attribute is specified in a document, SDF will automatically include a hypertext jump to the appropriate place. For example, the objects above could be specified in a document like this (PRD is the style used to specify a product object):
      

        The user documentation for {{PRD:MIMS}} is now
  produced using {{PRD:SDF}}.

      

      SDF has built-in support for the following classes of objects:
      

        

      1. references/documents

      2. terms/definitions

      3. organisations

      4. products.
      

      Additional classes of objects can be easily added, so workgroups can centrally manage all sorts of URLs: mail addresses, FTP sites and so on.
      

      4.2. Rule-based Hypertext Generation
      

      SDF provides a generic, rule-based feature called event processing for automating tasks like hypertext generation, index generation and custom formatting.
      

      The on macro allows you to execute an arbitrary piece of Perl code when an event occurs during document conversion. Its syntax is:
      

       !on type pattern; [id]; action

      

      where:
      

        

      • type specifies the event type

      • pattern is a Perl regular expression string, anchored at both ends, which specifies which styles (or names) the action is to be executed for

      • id is optionally used to name an event for later disabling via the off macro

      • action is the block of Perl code to execute.
      

      The types supported and the Perl symbols available in the respective actions include:
      

      

      

Type


Symbols


      

      

paragraph


$style, $text, %attr, &ParaPrepend, &ParaAppend


      

      

phrase


$style, $text, %attr


      

      

macro


$name, $args


      

      

filter


$name, $params


      

      

table


$style, %param


      

      


      Some examples are:
      

        # Make every heading a hypertext target named itself
  !on paragraph 'H\d';; $attr{'id'} = $text

  # If the target is HTML, add a line above level 1 headings
  !if $var{'OPT_TARGET'} eq 'html'
  !on paragraph 'H1';; &PrependText("Line:")
  !endif

      

      4.3. Embedded Perl Scripting
      

      As systems built by embedding scripts within HTML are typically easier to customise than systems build by generating HTML from scripts, embedded scripting is now a well established web-publishing solution.
      

      Likewise, Perl embedded in SDF can be a powerful combination providing this same flexibility with some additional benefits:
      

        

      • SDF is arguably easier to read than HTML

      • the information can be published in several formats.
      

      To embed a block of Perl code, the script filter is used. For example:
      

          !block script
    for $i ('a' .. 'z') {
        print "$i";
    }
    !endblock

      

      To embed an expression within paragraph text, the [[..]] syntax is used. For example:
      

        Hello [["wor" . "ld"]]

      

      
Note: If the expression is a single word, it is assumed to be a variable name, otherwise the expression is treated as a Perl expression.

      

      For single line scripts, the script macro can be used. For example:
      

        !script $next_version = $var{'VERSION'} + 1

      

      As shown above, SDF variables are available within Perl expressions via the var associative array.
      

      4.4. Inline HTML
      

      As HTML is constantly evolving and contains features which SDF doesn't explicitly support (e.g. frames), it is occasionally necessary to directly embed native HTML. To do this, use the inline filter. For example:
      

          !block inline
    <P>
    My name is <B>Bill</B>.
    !endblock

      

      Inlined HTML is ignored when PostScript is being generated. Likewise, if text for another format is inlined (by using the target parameter to the inline filter, say), it is ignored when HTML is generated.
      

      If you want to use embedded expressions (enclosed in [[ and ]]) and macros within the inline text, add the expand parameter like this:
      

          # If the SHOW_DATE variable is true, show the date, otherwise the time
    !block inline; expand
        !if SHOW_DATE
            <P>
            The date is [[DATE:DOC_START]].
        !else
            <P>
            The time is [[TIME:DOC_START]].
        !endif
    !endblock

      

      Likewise, you can use the INLINE phrase style within a paragraph to embed HTML within a paragraph. For example:
      

        My name is {{INLINE:<B>Bill</B>}}.

      

      

      5. Other Special Features
      

      SDF supports a number of special features which collectively make it useful for building large documentation systems like intranets and software manuals.
      

      These features are:
      

      

      

Feature


Description


      

      

Modules and Libraries


an extensible way of packaging and reusing configuration information


      

      

Reusable Topics


topics can be defined without needing to know how they are used


      

      

Conditional Text


inclusion and exclusion of certain text


      

      

Extracting Documentation


extraction of documentation embedded in source code


      

      

Programming Language Support


attractive formatting of source code


      

      

Multiple Looks


packaged document-wide presentation styles


      

      


      Further details about these are given below.
      

      5.1. Modules and Libraries
      

      A module is a normal SDF document which contains reusable information. As SDF has an open architecture, a module can provide:
      

        

      • new paragraph and phrase styles

      • new paragraph and phrase attributes

      • new macros

      • new filters

      • declarations of objects

      • formatting rules.
      

      A library is a directory containing modules with a common theme. Importantly, a library can inherit information from other libraries, making it easy to:
      

        

      1. create new libraries, and

      2. maximise the reuse of configuration information.
      

      5.2. Reusable Topics
      

      Documentation systems can be developed as a set of topics, where each topic uses H-style headings, starting at H1. A topic does not generally need to know how it will be used - each document including a given topic can:
      

        

      • "slide" the headings levels up or down as needed

      • change the heading styles as needed.
      

      For example:
      

       !include "types.sdf"

 H1: Subroutines
 !block topics
 Topic
 create
 delete
 update
 !endblock

 !include "errors.sdf"; appendix

      

      In this example, the results are:
      

        

      1. types.sdf will be included into the document unmodified

      2. the documentation for each subroutine (create.sdf, delete.sdf and delete.sdf) will be included as sub-sections in the Subroutines chapter, and the heading levels will be modified accordingly

      3. errors.sdf will be included as an appendix.
      

      
Note: Providing tabular data to a filter is a common idiom in SDF. In this case, the only column provided is the Topic column.

      

      5.3. Conditional Text
      

      Sections of text can be conditionally included or excluded using the following macros:
      

         !if condition
   !elsif condition
   !else
   !endif

      

      These macros allow you to tune the output for different audiences and different target formats.
      

      5.4. Extracting Documentation
      

      Software documentation can be embedded within comments in source code (and text-based data files) and extracted by the sdfget utility. The name, order and formatting of extracted sections can be controlled via report files.
      

      Consider the following scenarios:
      

        

      • a User Guide may need to extract sections called Purpose, Description and Examples

      • a Technical Reference may need to extract sections called Internal Architecture and Maintenance Tips.
      

      Creating the necessary reports and mapping the extraction commands to SDF macros is relatively easy.
      

      5.5. Programming Language Support
      

      Blocks of source code can be nicely formatted via the lang parameter to the example filter. For example:
      

      !block example; lang='Perl'
sub hello {
    local($planet) = @_;

    # Output a nice message
    print "hello $planet!\n";
}
!endblock

      

      If SDF encounters an unknown filter which is defined as a programming language, the example filter is implicit. Therefore, the above example can be simplified to:
      

      !block Perl
sub hello {
    local($planet) = @_;

    # Output a nice message
    print "hello $planet!\n";
}
!endblock

      

      In either case, the result is:
      

      sub hello {
    local($planet) = @_;

    # Output a nice message
    print "hello $planet!\n";
}

      

      There is built-in support for numerous languages, including Perl, C, C++, Java, Delphi and CORBA IDL. New language definitions can be easily added (vgrind definitions are used).
      

      Pretty printing of source code is directly supported by sdf's -P option. For example:
      

        sdf -2ps -Psh myscript
  sdf -2ps -P myapp.c
  sdf -2ps -P -N5 mylib.pl

      

      The language to use can be specified as a parameter. The default language is derived from the extension of the file. The -N option adds line numbers at the frequency given.
      

      5.6. Multiple Looks
      

      The overall appearance of an document can be controlled by either:
      

        

      • initialising the OPT_LOOK variable on the top line of a document

      • using sdf's -k option (which overrides the init macro).
      

      The available looks include:
      

        

      • simple - the default look, useful for general documentation

      • fancy - a look suitable for user documentation

      • infomap - a look based on Information Mapping™ 

      • overhead - a look suitable for overhead transparencies.
      

      It is relatively simple to create new looks by inheriting details from an existing one.
      

      
Note: At this time (January 98), multiple looks are currently only supported for paper documentation generated via FrameMaker. Multiple look support will hopefully be added to other SDF output drivers during 1998.

      

      

      6. Other Issues
      

      6.1. Why should I use SDF?
      

      The common reasons for using SDF are:
      

        

      1. it provides a single-source solution for high quality PostScript, HTML, Windows help, etc.

      2. it saves time

      3. it is highly portable

      4. it is free.
      

      6.1.1. High quality outputs from a single source
      

      As SDF can be used to specify a logical definition of a document, it is reasonably good at maintaining quality across the different output formats it supports.
      

      6.1.2. Saving time
      

      SDF often saves time in a number of ways:
      

        

      1. developers can focus on document content and leave the formatting to SDF, i.e. minimal effort is required for good formatting

      2. developers can use their favorite text editor, rather than switching between two different tools for source code and documents

      3. documentation can be extracted or generated from source code

      4. hypertext can be automatically generated using event processing or object management.
      

      6.1.3. High portability
      

      SDF documents are plain text files which can be created on any platform. The underlying technology is Perl, a highly portable scripting language available on all commonly used platforms.
      

      6.1.4. SDF is free
      

      SDF is freely available for commercial and non-commercial use. However, like most software packages, there are costs to be considered when using SDF. These include:
      

        

      1. training costs

      2. the cost of coverting existing documents, if you wish to do this.
      

      6.2. Converting Documents to SDF
      

      For POD documents, SDF contains a pod2sdf conversion program.
      

      For other formats, the easiest way to convert existing documents is usually to convert them to plain text and add the necessary markup. For Word users, an RTF-to-SDF converter is available.
      

      In any case, remember that:
      

        

      1. most document formats are physical markup languages, and

      2. the main benefits of SDF come from specifying logical documents.
      

      Therefore, regardless of what conversion tools you use, expect to do some manual changes.
      

      6.3. Further Information
      

      The SDF home page URL is http://www.mincom.com/mtr/sdf. From the home page, you can:
      

        

      • download the latest software, documentation and templates

      • browse the FAQ

      • report defects

      • suggest enhancements

      • visit the SDF Resource Center.
      

      SDF is also available using anonymous ftp. The URL of the base directory is ftp://ftp.mincom.com/pub/mtr/sdf. The latest release is available in a variety of formats.
      

      The following mailing lists are available:
      


      To subscribe to these lists, send email to sdf-users-request@mincom.com and/or sdf-bugs-request@mincom.com for instructions on using factotum, the majordomo variant that manages these lists. In short, send email to factotum@mincom.com with a message body of subscribe sdf-users or subscribe sdf-bugs.
      

      

      7. Summary
      

      By using a logical document approach, where content and formatting are largely separated, SDF delivers high-quality Web-based and paper documentation from a single source. Importantly, the SDF language is easier for (most!) humans to read and write than alternatives like SGML or XML.
      

      In addition, SDF lowers the cost of document production by providing a number of features for managing large documentation systems. These features include:
      

        

      1. rule-based hypertext generation, index generation and formatting

      2. centralised hypertext management

      3. an extensible way of packaging and reusing configuration information

      4. reusable topics

      5. conditional text, and

      6. extraction of documentation embedded in source code.
      

      If all else fails, Perl scripts can be directly embedded in SDF documents to generate the output required!
      

      Finally, as SDF is freely available to everyone, the costs associated with using SDF are relatively low.
      

      

      Credits
      

      Thanks to Tim Hudson (tjh@cryptsoft.com) for being SDF's biggest fan. Tim has assisted in design, fixed bugs, added features, promoted SDF to many of its current user base and generally helped with SDF whenever time permitted. Thanks also to Chris Moran (chris.moran@mincom.com) for maintaining the SDF Home Page, assisting in design, reviewing documents, etc. Many other Mincom colleagues have assisted with SDF, particularly David Cox and Craig Willis. Thanks to everyone involved.
      

      Thanks also to my former Leeds and Northrup Australia colleagues, particularly Tom Beale, Craig Gibbings and Greg Birnie, for inspiring my initial interest in literate programming.
      

      The initial version of the mif2rtf program is Copyright 1992 by Convex Computer Corporation, Richardson, Texas. (The full copyright notice and permission notice is included in the SDF distribution.)
      

      

      Trademarks
      

      FrameMaker, FrameViewer, Acrobat, PDF and PostScript are trademarks of Adobe Systems Incorporated.
      

      Delphi is a trademark of Borland International, Incorporated.
      

      Windows is a trademark of Microsoft Corporation.
      

      

      

      

      Home | Catalog
      

      

      



xtracted sections can bsdf-2.001/doc/paper/sdfintro.sdf010064400042570001753000001066750647625275000163540ustar00iancmtr00000400000236!init OPT_CONFIG="sdf"; OPT_STYLE="paper"; SDF_ROOT="../"
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 02-Jan-98 ianc    SDF2.000
# 25-Feb-97 ianc    SDF2.000beta8
# 23-May-96 ianc    SDF2.000beta6
# -----------------------------------------------------------------------
#

# Define variables
!define DOC_NAME     "The SDF Document Development System"
!define DOC_AUTHOR   "Ian Clatworthy ({{EMAIL:ianc@mincom.com}}), Research Architect, {{ORG[expand]Mincom}}"
!define DOC_URL      "$var{'SDF_WWW'}/doc/paper/sdfintro.ps"

# Build the title
!build_title

!block abstract
SDF (Simple Document Format) is a freely available document development
system which generates high quality outputs in a variety of formats
from a single source. The output formats supported include
HTML, PostScript, PDF, man pages,
POD, LaTeX, SGML, MIF, RTF, Windows help and plain text.

SDF documents are simple to create and maintain, minimising the time
spent on documentation. In particular, SDF directly supports the
creation and maintenance of large, on-line documentation systems
(including intranets) via centralised hypertext management and
rule-based hypertext generation.

SDF has been completely developed in [[Perl]], a popular and highly
portable scripting language. Like Perl, SDF is freely available for
commercial and non-commercial use.
!endblock

H1[top=0] Overview

H2: Introduction

[[SDF]] is a document publishing system which
aims to solve some common problems that many software organisations
encounter with documentation:

^ How do we support multiple formats (and produce high quality
  output for each)?
+ How do we reduce the time it takes to create documents?
+ How do we maintain a large on-line documentation system?
+ How can we generate and easily maintain hypertext links?
+ How do we keep the documentation up to date with the code?
+ How can we centrally manage corporate formatting standards?

The basic design principles are:

^ Documents should be specified in a {{logical}} manner.
+ Make common things easy.
+ Give power users full control when they need it.
+ The architecture should be open and easy to extend.

The key feature of SDF is the division of responsibility:

* {{content}} is supplied as text files or generated where feasible
* {{formatting}} is generally implied by the semantics of the content
  or supplied by rules or external templates.

SDF consists of the following key components:

* {{SDF}} - {{Simple Document Format}}, a text format for defining documents
* {{CMD:sdf}} - a utility for converting SDF files to other formats.

Unlike SGML, XML, HTML and many other markup languages, the SDF
language has been designed to be {{author-friendly}}, rather than
{{parser-friendly}}. As a result, most SDF documents look quite
similar to plain text email, making them easy-to-write and
easy-to-read.

H2: A Sample SDF Document

A sample SDF document is shown below:

#!block box
!include "mydoc.sdf"; verbatim; listitem
#!endblock

H2: A Brief Explanation

Comments begin with a # character as the first non-whitespace
character on a line.

Macros are embedded commands which begin with a ! as the
first non-whitespace character on a line.
The {{MAC:define}} macro is used to set variables.
The value of a variable can be embedded in paragraph
text  by using the E<2[>...E<2]> syntax.

The DOC_NAME and DOC_TYPE variables are used by
the {{MAC:build_title}} macro which creates:

* a cover page (or two) for paper-based outputs
* a title header for online outputs.

Paragraphs can be tagged in different ways. For the vast majority of
SDF documents, the only tags used are:

!block table
Tag     Meaning
H1:     level 1 heading
H2:     level 2 heading
*       item in level 1 bulleted list
-       item in level 2 bulleted list
^       first item in level 1 ordered list
+       next item in level 1 ordered list
>       fixed-width, verbatim text
Note:   note
!endblock

Phrases can also be tagged in several ways. Any phrase can be tagged
using the syntax:

>  {{XYZ:...}}

where XYZ is the tag. For single, uppercase character tags like
I (Italics) and B (Bold), POD-style syntax is also supported:

>  X<...>

where X is the tag.

Tables can be specified using the {{FILT:table}} filter, typically
in combination with the {{MAC:block}} and {{MAC:endblock}} macros.
The first row is the headings. Remaining rows are data.

H2: Generating Output Formats

The {{CMD:sdf}} command is used to convert SDF to other formats.
The general syntax is:

E:   sdf [options] file ...

If an extension is not given (and a file is not found with that name),
an extension of {{sdf}} is assumed.

The most commonly used option is the -2 option. For example,
to convert {{FILE:mydoc.sdf}} to HTML and PostScript, the respective
commands are:

E:   sdf -2html mydoc
E:   sdf -2ps mydoc

These commands create files called {{FILE:mydoc.html}} and
{{FILE:mydoc.ps}} respectively.

To convert {{FILE:mydoc.sdf}} to a set of HTML topics, the command is:

E:   sdf -2topics mydoc

This creates the following files:

* {{mydoc.html}} - the table of contents
* {{mydoc_1.html}} - the first topic
* {{mydoc_2.html}} - the second topic.

By default, topics are created whenever a level 1 heading is encountered
or a file is explicitly included. The -n option can be used to specify
a different level for splitting into topics, e.g.

E:  sdf -2topics -n2 mydoc

H2: Requirements

SDF requires the following:

* [[Perl]] 5.003 or later

* for generating PostScript, the freely available {{PRD:pod2ps}} program or
  {{PRD:SGML-Tools}} and {{LaTeX}} packages. Alternatively, you need
  a word processor which can import MIF or RTF
  ([[Adobe]]'s [[FrameMaker]] 5.x is preferred)

* for generating PDF, [[Adobe]]'s {{PRD:Acrobat}}

* for generating [[Windows]] Help files, a help compiler (e.g. hcp.exe).

H2: Architecture

The architecture of SDF is given in the diagram below.

!import "sdfarch"


H1: Alternative Systems

H2: WYSIWYG Tools

WYSIWYG ({{What-You-See-Is-What-You-Get}}) tools are great
for creating small to medium-sized:

* World Wide Web documents (i.e. [[HTML]]), {{or}}
* paper-based documents (i.e. [[PostScript]]), {{or}}
* [[Windows]] help files.

However, the WYSIWYG approach is inefficient when it comes
to creating and maintaining large documentation systems, particularly
if you want high quality paper-based {{and}} on-line outputs.

The reasons are:

^ WYSIWYG is meaningless when it comes to supporting multiple
  formats. For example:
  - paper documents are formatted on fixed-size pages;
    on-line documents are formatted as topics displayed in user-sized windows
  - different browsers may display a given HTML document differently.

+ For good-looking results, the {{formatting rules}} need to be
  tuned for each format. For example, a certain phrase may be:
  - a hypertext jump within HTML
  - emphasised using italics for paper-based formats
  - a pop-up window within Windows help.

+ The {{content}} often needs to be tuned for each format.
  For example, you may wish to describe a given procedure in different ways:
  - in detail for a paper-based document
  - terse for on-line help.

+ Centralised management of formatting rules and hypertext generation
  is essential for minimising the cost and maximising the quality of
  a large documentation system. By making it too easy for individual
  authors to customise formatting, WYSIWYG tools often make it harder for
  workgroups to centrally manage formatting!

Nevertheless, WYSIWYG tools are often used in combination with SDF
when they save time. For example, diagrams can be created in most
packages and imported into SDF documents.

H2: SGML/XML

The SGML/XML approach of specifying documents semantically is an
extremely powerful one and SDF uses the same approach whenever possible.
However, as SDF does not use document {{structure}} rules and DTDs, it is
much simpler than SGML. SDF is also more readable than SGML, so high-cost
authoring tools are not needed on every desktop, making SDF much
cheaper to implement than SGML.

Like SDF, XML has built on SGML's good ideas but minimised the
overall complexity. However, XML has retained SGML's unfriendly appearance.

H2: POD

In many ways, the system closest to SDF is POD
(Plain Old Documentation) which is widely used in
the [[Perl]] community. Like SDF, POD:

* is simple, readable and free
* supports a large number of output formats
* supports {{literate programming}} (i.e. POD documentation
  can be directly embedded in Perl scripts and libraries)
* is built on Perl.

Currently, SDF has several advantages over POD:

^ SDF supports more features, e.g.:
  - tables
  - figures
  - formatting within example text
  - filters, macros and variables (see {{SECT:Language Overview}} below).

+ SDF is more extensible as sites can add their own:
  - paragraph and phrase styles
  - paragraph and phrase attributes
  - filters, macros, etc.

Furthermore, versions 2.000beta10 and later of SDF are POD friendly:

* POD can be {{converted}} to SDF and vice versa
* SDF can be {{nested}} inside POD and vice versa
* SDF is largely upwardly compatible with POD in
  terms of syntax and functionality.

As a result, POD users can use SDF or migrate to SDF when
POD isn't powerful enough. Refer to {{DOC: SDF for POD Users}}
for further details.

H1: Language Overview

H2: Basic Concepts

The basic concepts within SDF documents are:

!block table
Concept     Description
paragraph   one or more lines of text
phrase      a section of text within a paragraph
style       the type of a document, paragraph, phrase or table (e.g. H1)
macro       a command embedded in a document (e.g. !define)
variable    a named value (e.g. DOC_NAME)
filter      a rule to use when processing certain sections of text (e.g. table)
attribute   a named parameter of a paragraph, phrase or filter (e.g. jump)
expression  a literal or expression to evaluate (e.g. "Ian Clatworthy").
!endblock

Further details about these are given below.

H2: Paragraphs

Paragraphs have the following format:

E:   line1
E:   ...
E:   lineN

Leading and trailing whitespace on lines is generally ignored.
Paragraphs are separated by:

* blank lines
* {{comment lines}} - first non-whitespace character is "#"
* {{macros}} - first non-whitespace character is "!" or "=".

For normal paragraphs, simply specify the text on one or more lines.
For example:

E:   I like products which are simple to use and
E:   do what I expect. We should encourage engineers
E:   to design more products with these qualities.

A paragraph can be given a style using the following syntax:

E:   style":"line1
E:   ...
E:   lineN

[keep_next] Some commonly-used paragraph styles are:

!block table; narrow; align=Center
Style           Description
N               normal paragraph (the default)
H1 .. H6        chapter heading at level 1-6
A1 .. A6        appendix heading at level 1-6
P1 .. P6        plain heading at level 1-6
Note            a single paragraph note
E               fixed-width (example) text
!endblock

For example:

E:   Note: Life is too short to drink bad wine.

The result is:

Note: Life is too short to drink bad wine.

H2: Special styles

For certain styles, the following syntax is also supported:

E:   special_style line1
E:   ...
E:   lineN

The special styles available are:

!block table; narrow; align=Center
Style           Description
>               fixed-width, verbatim paragraph
. .. ......     paragraph or plain list item at level 1-6
* .. ******     unordered list at level 1-6
- .. -----      unordered list at level 2-6
& .. &&&&&&     enumerated list at level 1-6
^ .. ^^^^^^     first entry in an ordered list at level 1-6
+ .. ++++++     next entry in an ordered list at level 1-6
!endblock

For example:

E:^ fruits:
E:  - peach
E:  - banana
E:+ vegetables:
E:  - potato
E:  - carrots.

The result is:

^ fruits:
  - peach
  - banana
+ vegetables:
  - potato
  - carrots.

H2: Phrases

A {{phrase}} is a section of text within a paragraph
enclosed in the symbols E<2{> and E<2}>. Like paragraphs,
phrases are optionally tagged with a style.

The commonly-used phrase styles are:

!block table; groups
Tag         Description                     Sample_Output
Emphasis:
1           1st level emphasis (default)    {{1:emphasis 1}}
2           2nd level emphasis              {{2:emphasis 2}}
3           3rd level emphasis              {{3:emphasis 3}}
Formatting:
N           normal                          {{N:some normal text}}
I           italic                          {{I:some italic text}}
B           bold                            {{B:some bold text}}
U           underline                       {{U:some underline text}}
EX          example                         {{EX:some example text}}
Types:
EMAIL       email address                   {{EMAIL:ianc@mincom.com}}
F (or FILE) Filename                        {{FILE:myfile.sdf}}
SECT        Section                         {{SECT:Paragraphs}}
URL         Uniform Resource Locator        {{URL:http://www.mincom.com}}
Classes:
DOC         document title                  {{DOC:SDF User Guide}}
REF         reference (document code)       {{REF:MTR-SDF-0002}}
ORG         organisation                    {{ORG:Mincom}}
PRD         product                         {{PRD:MIMS}}
Specials:
E (or CHAR) escape (i.e. special character) E
S           spaces are non-breaking         {{S:section 2.1}}
IMPORT      name of a figure to import      {{IMPORT:key}}
!endblock

For single character, uppercase phrase styles, POD's [A-Z]<..>
syntax can be used. For example:

!block example; pure
E:  I reply to {{EMAIL:customer@xyz.com}} quickly.
!endblock

The result is:

I reply to {{EMAIL:customer@xyz.com}} quickly.

This example also illustrates the advantage of specifying documents
in a {{logical}} manner:

* when generating PostScript, the EMAIL style is mapped to italics
* when generating HTML, the EMAIL style is mapped to a 'mailto'
  Uniform Resource Locator (URL).

H2: Types vs Classes

A {{type}} (e.g. EMAIL) simply marks a phrase as a logical entity.
Rules may be defined for processing (e.g. generating hypertext) for
these types. Refer to {{SECT:Rule-based Hypertext Generation}}, later.

A {{class}} (e.g. DOC) is a special kind of type where the entity
must be a member of a predefined set. As a result, SDF can validate
the entry name, lookup a hypertext jump and do other clever things
(like replace the text with a longer name).

Rules can also be defined
for processing classes, although hypertext jumps are often defined
for each entity in the tables which define the known entities.
Refer to {{SECT:Centralised Hypertext Management}}, later.

H2: Special Phrases

Special phrases are used for entering things like:

* special symbols (like E<2{>)
* special characters (like E)
* images within paragraph text
* the current page number in the header or footer.


H2: Macros

A {{macro}} is a command which can be embedded within SDF.
Macros begin with an exclamation mark (!) or equals sign (=)
as the first non-whitespace character on a line. !-style
macros terminate at the end of the line, unless explicitly
continued using a backslash character at the end of the line.
\=-style macros terminate at the next blank line (ala POD).

Some examples are:

E:  !define DOC_NAME   "The SDF Document Development System"
E:  !define DOC_AUTHOR "Ian Clatworthy"
E:  !build_title

Some commonly-used macros are:

!block table; narrow; align=Center
Macro                                   Description
init {{variables}}                      initialise variables
define {{variable}} [{{expression}}]    set a variable's value
build_title                             build a title page
block {{filter}}                        begin a block of text
endblock                                end a block of text
include {{file}}[; {{filter}}]          include another file
import {{file}}[; {{parameters}}]       import a figure
!endblock

H2: Variables

A {{variable}} is a named value. Document-wide settings are
controlled in SDF using variables. Likewise, authors can
define and access their own variables. In either case,
the value of a variable can be referenced in a paragraph
by delimiting it with the special symbols E<2[> and E<2]>.

For example:

V:  !define MY_EMAIL 'abc@xyz.com'
V:  My electronic mail address is [[MY_EMAIL]].

The result is:

!define MY_EMAIL 'abc@xyz.com'
My electronic mail address is [[MY_EMAIL]].

Some commonly used system variables are:

!block table
Variable            Description
DOC_NAME            the title, excluding the type (e.g. SDF)
DOC_TYPE            the title type (e.g. User Guide)
DOC_AUTHOR          the author
DOC_TOC             the number of heading levels in the table of contents
DOC_START           the time processing of the document started
!endblock

The {{MAC:define}} macro is usually used to set variables.
However, variables beginning with OPT_ need to be set
before processing of the document begins.
The {{MAC:init}} macro is used on the top line of a document to
set these variables. For example:

E:   !init OPT_STYLE="manual"

H2: Formats

As the value of date-time variables is the number of seconds
since January 1, 1970, a {{format}} is typically applied to
them when they are embedded in text. For example:

>  The date is [[DATE:DOC_START]].

The predefined formats available include:

!block table
Format  Description
FULL    complete date-time format
TIME    time only
DATE    date only
CONCISE concise date only
YEAR    4-digit year
!endblock

New formats can be created and the definitions of existing formats
can be changed. Furthermore, a format can be applied to any variable
(or embedded Perl expression), although the date-time formats
are obviously only useful when applied to date-time values.

H2: Document styles

The general type of an document can be controlled by either:

* initialising the OPT_STYLE variable on the top line of a document
* using {{CMD:sdf}}'s -s option (which overrides the {{MAC:init}} macro).

The available document styles include:

!block table; groups; narrow; align=Center
Style           Purpose
General:
document        a normal document
manual          a manual
paper           a technical paper
Administration:
fax             a facsimile
memo            a memorandum
minutes         minutes of a meeting
!endblock

It is relatively simple to create new document styles
by inheriting details from an existing one.

H2: Filters

A {{filter}} controls how a block of text is interpreted.
The text is usually delimited by {{MAC:block}} and {{MAC:endblock}}
macros.

For example, tables are usually defined via the {{FILT:table}} filter:

E:!block table
E:Option  Description
E:-h      display help
E:-o      specify the output extension
E:!endblock

The result is:

!block table
Option  Description
-h      display help
-o      specify the output extension
!endblock

Other macros also support filters. These include:

* {{MAC:include}} - include text from another file
* {{MAC:execute}} - include the output of a system command.

Some of the commonly-used filters are:

!block table; coltags='FILT'; narrow; align=Center
Filter      Description
table       the lines are a table in SDF's {{FMT:TBL}} format
example     the lines are example paragraphs
title       used to build a title block for memos, faxes, etc.
topics      include files as sub-topics
appendix    replace H1 styles with A1, etc.
plain       replace H1 styles with P1, etc.
!endblock

For example, the following macro includes another SDF file
and formats it as an appendix:

E:   !include "tips.sdf"; appendix

Note: The {{FILT:appendix}} and {{FILT:plain}} filters enable
authors to construct topics without needing to worry about how
those topics will be used, e.g. a topic may be a chapter in
one document and an appendix in another!

H2: Attributes

Paragraphs and phrases can be given attributes via the syntax:

E:  style"["attributes"]" text

where the syntax of {{attributes}} is:

E:  name1["="expression1]";" name2["="expression2] ...

Attributes are used for specifying custom formatting, hypertext
targets and jumps, indexing information, etc.

Some commonly used attributes are:

!block table; groups
Name            Purpose
Paragraphs:
align           Left, Right, Center, or Full (i.e. justified)
notoc           take this heading out of the table of contents
Phrases:
family          font family
size            font size
id              hypertext target tag
jump            URL (Uniform Resource Locator) to jump to
!endblock

For convenience, phrase attributes can be applied to paragraphs.

For example:

E:  N[align=Center;size='12pt']
E:  Life is too short to drink bad wine.

The result is:

N[align=Center;size='12pt']
Life is too short to drink bad wine.

H1: Web Publishing Features

H2: Centralised Hypertext Management

SDF has a generic object management feature which enables:

^ the definition of objects in configuration files
+ the use of those objects in documents.

For example, a configuration file may have
the following declaration of {{CLASS:products}}:

E:  !block products; data
E:  Name     Jump
E:  SDF      http://www.mincom.com/mtr/sdf/
E:  MIMS     http://www.mincom.com/mims/
E:  !endblock

If an object with a {{Jump}} attribute is specified in a
document, SDF will automatically include a hypertext jump
to the appropriate place. For example, the objects above
could be specified in a document like this (PRD is the
style used to specify a product object):

V:  The user documentation for {{PRD:MIMS}} is now
V:  produced using {{PRD:SDF}}.

SDF has built-in support for the following classes of objects:

^ references/documents
+ terms/definitions
+ organisations
+ products.

Additional classes of objects can be easily added, so
workgroups can centrally manage all sorts of URLs: mail addresses,
FTP sites and so on.

H2: Rule-based Hypertext Generation

SDF provides a generic, rule-based feature called {{event processing}}
for automating tasks like hypertext generation, index generation and custom
formatting.

The {{MAC:on}} macro allows you to execute an arbitrary piece of
Perl code when an event occurs during document conversion. Its syntax is:

E: !on {{type}} {{pattern}}; [{{id}}]; {{action}}

:where:

* {{type}} specifies the event type
* {{pattern}} is a Perl regular expression string, anchored at both ends,
  which specifies which styles (or names) the action is to be executed for
* {{id}} is optionally used to name an event for later disabling via
  the {{MAC:off}} macro
* {{action}} is the block of Perl code to execute.

The types supported and the Perl symbols available in the
respective actions include:

!block table; narrow; align=Center
Type        Symbols
paragraph   $style, $text, %attr, &ParaPrepend, &ParaAppend
phrase      $style, $text, %attr
macro       $name, $args
filter      $name, $params
table       $style, %param
!endblock

Some examples are:

!block example; lang='SDF'
  # Make every heading a hypertext target named itself
  !on paragraph 'H\d';; $attr{'id'} = $text

  # If the target is HTML, add a line above level 1 headings
  !if $var{'OPT_TARGET'} eq 'html'
  !on paragraph 'H1';; &PrependText("Line:")
  !endif
!endblock

H2: Embedded Perl Scripting

As systems built by embedding scripts within HTML are typically easier
to customise than systems build by generating HTML from scripts,
embedded scripting is now a well established web-publishing solution.

Likewise, Perl embedded in SDF can be a powerful combination
providing this same flexibility with some additional benefits:

* SDF is arguably easier to read than HTML
* the information can be published in several formats.

To embed a block of Perl code, the {{FILT:script}} filter
is used. For example:

!block verbatim; listitem
!block script
for $i ('a' .. 'z') {
    print "$i";
}
!endblock
!endblock

To embed an expression within paragraph text, the E<2[>..E<2]> syntax
is used. For example:

>  Hello [["wor" . "ld"]]

Note: If the expression is a single word, it is assumed to be a
variable name, otherwise the expression is treated as a Perl expression.

For single line scripts, the {{MAC:script}} macro can be used.
For example:

>  !script $next_version = $var{'VERSION'} + 1

As shown above, SDF variables are available within Perl expressions
via the {{var}} associative array.

H2: Inline HTML

As HTML is constantly evolving and contains features which SDF
doesn't explicitly support (e.g. frames), it is occasionally necessary
to directly embed native HTML. To do this, use the {{FILT:inline}} filter.
For example:

!block verbatim
    !block inline
    
      
    My name is Bill.
    !endblock
!endblock

Inlined HTML is ignored when PostScript is being generated. Likewise,
if text for another format is inlined (by using the {{target}} parameter
to the {{inline}} filter, say), it is ignored when HTML is generated.

If you want to use embedded expressions (enclosed in E<2[> and E<2]>)
and macros within the inline text, add the {{expand}} parameter like this:

!block verbatim
    # If the SHOW_DATE variable is true, show the date, otherwise the time
    !block inline; expand
        !if SHOW_DATE
            
      
            The date is [[DATE:DOC_START]].
        !else
            
      
            The time is [[TIME:DOC_START]].
        !endif
    !endblock
!endblock

Likewise, you can use the INLINE phrase style within a paragraph
to embed HTML within a paragraph. For example:

>  My name is {{INLINE:Bill}}.


H1: Other Special Features

SDF supports a number of special features which collectively
make it useful for building large documentation systems like
intranets and software manuals.

These features are:

!block table; coltags='SECT'
Feature                         Description
Modules and Libraries           an extensible way of packaging and reusing configuration information
Reusable Topics                 topics can be defined without needing to know how they are used
Conditional Text                inclusion and exclusion of certain text
Extracting Documentation        extraction of documentation embedded in source code
Programming Language Support    attractive formatting of source code
Multiple Looks                  packaged document-wide presentation styles
!endblock

Further details about these are given below.

H2: Modules and Libraries

A {{module}} is a normal SDF document which contains reusable information.
As SDF has an open architecture, a module can provide:

* new paragraph and phrase styles
* new paragraph and phrase attributes
* new macros
* new filters
* declarations of objects
* formatting rules.

A {{library}} is a directory containing modules with a common theme.
Importantly, a library can {{inherit}} information from other libraries,
making it easy to:

^ create new libraries, and
+ maximise the reuse of configuration information.

H2: Reusable Topics

Documentation systems can be developed as a set of topics,
where each topic uses H-style headings, starting at H1.
A topic does not generally need to know how it will be used - each
document including a given topic can:

* "slide" the headings levels up or down as needed
* change the heading styles as needed.

For example:

E: !include "types.sdf"
E:
E: H1: Subroutines
E: !block topics
E: Topic
E: create
E: delete
E: update
E: !endblock
E:
E: !include "errors.sdf"; appendix

In this example, the results are:

^ {{types.sdf}} will be included into the document unmodified

+ the documentation for each subroutine ({{create.sdf}},
  {{delete.sdf}} and {{delete.sdf}}) will be included as
  sub-sections in the {{Subroutines}} chapter, and the heading
  levels will be modified accordingly

+ {{errors.sdf}} will be included as an appendix.

Note: Providing tabular data to a filter is a common idiom in SDF.
In this case, the only column provided is the {{Topic}} column.

H2: Conditional Text

Sections of text can be conditionally included or excluded using
the following macros:

E:   !if condition
E:   !elsif condition
E:   !else
E:   !endif

These macros allow you to tune the output for different audiences and
different target formats.

H2: Extracting Documentation

Software documentation can be embedded within comments in source code
(and text-based data files) and extracted by the {{CMD:sdfget}} utility.
The name, order and formatting of extracted sections can be
controlled via {{report}} files.

Consider the following scenarios:

* a {{User Guide}} may need to extract sections called {{Purpose}},
  {{Description}} and {{Examples}}
* a {{Technical Reference}} may need to extract sections called
  {{Internal Architecture}} and {{Maintenance Tips}}.

Creating the necessary reports and mapping the extraction commands
to SDF macros is relatively easy.

H2: Programming Language Support

Blocks of source code can be nicely formatted via the {{lang}}
parameter to the {{FILT:example}} filter. For example:

!block example
!block example; lang='Perl'
sub hello {
    local($planet) = @_;

    # Output a nice message
    print "hello $planet!\n";
}
!endblock
!endblock

If SDF encounters an unknown filter which is defined as a programming
language, the example filter is implicit. Therefore, the above example
can be simplified to:

!block example
!block Perl
sub hello {
    local($planet) = @_;

    # Output a nice message
    print "hello $planet!\n";
}
!endblock
!endblock

In either case, the result is:

!block Perl
sub hello {
    local($planet) = @_;

    # Output a nice message
    print "hello $planet!\n";
}
!endblock

There is built-in support for numerous languages, including
Perl, C, C++, Java, Delphi and CORBA IDL. New language definitions
can be easily added ({{CMD:vgrind}} definitions are used).

Pretty printing of source code is directly supported by
{{CMD:sdf}}'s -P option.
For example:

E:  sdf -2ps -Psh myscript
E:  sdf -2ps -P myapp.c
E:  sdf -2ps -P -N5 mylib.pl

The language to use can be specified as a parameter.
The default language is derived from the extension of the file.
The -N option adds line numbers at the frequency given.

H2: Multiple Looks

The overall appearance of an document can be controlled by either:

* initialising the OPT_LOOK variable on the top line of a document
* using {{CMD:sdf}}'s -k option (which overrides the {{MAC:init}} macro).

The available looks include:

* {{simple}} - the default look, useful for general documentation

* {{fancy}} - a look suitable for user documentation

* {{infomap}} - a look based on Information Mapping[[tm]]

* {{overhead}} - a look suitable for overhead transparencies.

It is relatively simple to create new looks
by inheriting details from an existing one.

Note: At this time (January 98), multiple looks are currently only
supported for paper documentation generated via FrameMaker.
Multiple look support will hopefully be added to other SDF output
drivers during 1998.

H1: Other Issues

H2: Why should I use SDF?

The common reasons for using [[SDF]] are:

^ it provides a single-source solution for high quality [[PostScript]],
  [[HTML]], [[Windows]] help, etc.
+ it saves time
+ it is highly portable
+ it is free.

H3: High quality outputs from a single source

As [[SDF]] can be used to specify a {{logical}} definition of
a document, it is reasonably good at maintaining quality
across the different output formats it supports.

H3: Saving time

SDF often saves time in a number of ways:

^ developers can focus on document content and leave the formatting to
  SDF, i.e. minimal effort is required for good formatting

+ developers can use their favorite text editor, rather than switching
  between two different tools for source code and documents

+ documentation can be extracted or generated from source code

+ hypertext can be automatically generated using {{event processing}}
  or {{object management}}.

H3: High portability

SDF documents are plain text files which can be created on any platform.
The underlying technology is {{Perl}}, a highly portable scripting language
available on all commonly used platforms.

H3: SDF is free

SDF is freely available for commercial and non-commercial use.
However, like most software packages, there are costs to be considered
when using SDF. These include:

^ training costs
+ the cost of coverting existing documents, if you wish to do this.

H2: Converting Documents to SDF

For POD documents, SDF contains a {{CMD:pod2sdf}} conversion program.

For other formats, the easiest way to convert existing documents
is usually to convert them to plain text and add the necessary markup.
For [[Word]] users, an RTF-to-SDF converter is available.

In any case, remember that:

^ most document formats are {{physical}} markup languages, and
+ the main benefits of SDF come from specifying {{logical}} documents.

Therefore, regardless of what conversion tools you use,
expect to do some manual changes.

H2: Further Information

The [[SDF]] home page URL is {{URL:[[SDF_WWW]]}}.
From the home page, you can:

* download the latest software, documentation and templates
* browse the {{[jump=&Var('SDF_WWW')."/faq/faq.html"] FAQ}}
* report defects
* suggest enhancements
* visit the {{DOC:SDF Resource Center}}.

SDF is also available using anonymous ftp. The URL of the base directory is
{{URL:ftp://ftp.mincom.com/pub/mtr/sdf}}. The latest release is available
in a variety of formats.

The following mailing lists are available:

* {{EMAIL:sdf-users@mincom.com}} - for general questions
* {{EMAIL:sdf-bugs@mincom.com}} - for reporting bugs and fixes.

To subscribe to these lists, send email to
{{EMAIL:sdf-users-request@mincom.com}} and/or
{{EMAIL:sdf-bugs-request@mincom.com}} for instructions on
using {{factotum}}, the majordomo variant that manages these lists.
In short, send email to {{EMAIL:factotum@mincom.com}} with a
message body of {{subscribe sdf-users}} or {{subscribe sdf-bugs}}.


H1[top=0] Summary

By using a logical document approach, where content and formatting
are largely separated, SDF delivers high-quality Web-based and
paper documentation from a single source. Importantly, the SDF
language is easier for (most!) humans to read and write than
alternatives like SGML or XML.

In addition, SDF lowers the cost of
document production by providing a number of features for managing
large documentation systems. These features include:

^ rule-based hypertext generation, index generation and formatting
+ centralised hypertext management
+ an extensible way of packaging and reusing configuration information
+ reusable topics
+ conditional text, and
+ extraction of documentation embedded in source code.

If all else fails, Perl scripts can be directly embedded in SDF
documents to generate the output required!

Finally, as SDF is freely available to everyone,
the costs associated with using SDF are relatively low.

P1[top=0] Credits

Thanks to Tim Hudson ({{EMAIL:tjh@cryptsoft.com}}) for
being SDF's biggest fan. Tim has assisted in design, fixed bugs, added
features, promoted SDF to many of its current user base and generally
helped with SDF whenever time permitted.
Thanks also to Chris Moran ({{EMAIL:chris.moran@mincom.com}})
for maintaining the {{[jump=SDF_WWW]SDF Home Page}}, assisting
in design, reviewing documents, etc.
Many other [[Mincom]] colleagues have assisted with SDF,
particularly David Cox and Craig Willis.
Thanks to everyone involved.

Thanks also to my former {{Leeds and Northrup Australia}}
colleagues, particularly Tom Beale, Craig Gibbings and Greg Birnie,
for inspiring my initial interest in {{literate programming}}.

The initial version of the {{mif2rtf}} program is
Copyright 1992 by Convex Computer Corporation, Richardson, Texas.
(The full copyright notice and permission notice is included in
the SDF distribution.)

P1[top=0] Trademarks

[[FrameMaker]], [[FrameViewer]], {{PRD:Acrobat}},
[[PDF]] and [[PostScript]] are trademarks of {{ORG[expand]Adobe}}.

[[Delphi]] is a trademark of {{ORG[expand]Borland}}.

[[Windows]] is a trademark of {{ORG[expand]Microsoft}}.
n
Modules and Libraries           an extensible way of packaging ansdf-2.001/doc/genhtml/004075500042570001753000000000000672243773400143425ustar00iancmtr00000400000236sdf-2.001/doc/genhtml/index.html010064400042570001753000000507650672242112500163340ustar00iancmtr00000400000236






SDF 2.001: Generating HTML Using SDF




      

      

      Home | Catalog
      

      

      

      

      

      Generating HTML Using SDF
      

      MTR-SDF-0011.001 (Final)
      

      Ian Clatworthy (ianc@mincom.com), Research Architect, Mincom Pty Ltd
      

      25 May 1999
      

      

      

      

      

      Table of Contents
      


      

      

      

      1. Introduction
      

      SDF is a useful tool for generating HTML documents for several reasons:
      

        

      1. SDF provides a high-level language for documentation including macros, filters, variables, conditional text and event processing

      2. SDF is more readable than HTML, making it much easier to maintain

      3. Unlike HTML, SDF documents can contain user defined style names allowing authors to specify a document in a logical manner

      4. SDF provides the features required to create any HTML document.
      

      For a general overview of SDF, see The SDF Document Development System. For a general introduction to the core features in SDF, see the SDF User Guide.
      

      This tutorial supplements these documents by providing:
      

        

      • an overview of how SDF documents are converted to HTML documents

      • details on how to customise the generated HTML.
      

      

      2. Generating HTML
      

      2.1. Generating a Single Document
      

      To generate HTML for myfile.sdf, the command is:
      

         sdf -2html myfile

      

      This will create a single html file called myfile.html.
      

      2.2. Changing the Output Extension
      

      By default, SDF creates HTML files with an output extension of html. To specify a different extension, use the -o option like this:
      

         sdf -2html -ohtm myfile

      

      2.3. Sending Output to Standard Output
      

      To send output to standard output, use the -o option like this:
      

         sdf -2html -o- myfile

      

      2.4. Changing the Default Extension
      

      If you are generating HTML for a system which only supports 8.3 filenames, you may wish to set the default extension to be htm like this:
      

         sdf -2html -DHTML_EXT=htm myfile

      

      If you are working on a system which only supports 8.3 filenames, you may wish to permanently set the HTML_EXT variable within the sdf.ini configuration file, so that you don't need to specify it every time.
      

      Unlike using the -o option, this approach changes the output extension on all HTML files generated, including sub-topics.
      

      2.5. Generating a Set of Topics
      

      For large documents, it is often much better to generate a set of topics rather than a large HTML file. To do this, the command is:
      

         sdf -2topics myfile

      

      This will create:
      

        

      • a HTML file called myfile.html which contains a table of contents

      • a HTML file for each topic.
      

      2.6. Controlling Topic Breaks
      

      If you want to manually control how a document is split into topics, simply include other sdf files which contain headings. These manual topics, if any, can be supplemented with automatically generated topics. By default, level 1 headings are used as topic breaks, in addition to the manual ones. The -n (or --split_level) option can be used to change this:
      

        

      • -n0 disables autosplitting

      • -n2 uses level 1-2 headings to autosplit

      • -n3 uses level 1-3 headings to autosplit

      • etc.
      

      

      3. Customising the Generated HTML
      

      The following files are used to convert SDF to HTML:
      

      

      

File


Directory


Purpose


      

      

html.sdn


stdlib


tuning file for HTML generation


      

      

tohtml.pl


perllib/sdf


output driver for HTML generation


      

      


      The tuning file contains:
      

        

      • the mapping tables used to convert SDF paragraph and phrase styles to HTML entities

      • the default definitions of macros, variables, etc.
      

      3.1. Paragraph and Phrase Style Mappings
      

      If you want to create new paragraph and phrase styles and/or override the default mapping, you can edit the tuning file. Alternatively, create a site-specific tuning file and use it at the top of each document.
      

      3.2. Output Driver Enhancements
      

      On some occasions, the conversion rules are too complicated for mapping tables and need to be coded into the output driver as Perl logic. If you need to edit the output driver, please forward the patches to me so that everyone can benefit from your enhancements.
      

      3.3. General Customisations
      

      On most occasions, the generated HTML can be easily customised by overriding the default values of variables and macros. In particular, you can customise:
      


      Furthermore, if you really need it, Inline HTML can be used to generate any HTML you like.
      

      
Note: If you override a macro, it is probably a good idea to start with the default definition in the HTML tuning file, stdlib/html.sdn.

      

      3.4. Topics Mode Variables
      

      When customising the generated HTML, it is occasionally necessary to know whether a single document or set of topics is being generated. The following variables can be tested to determine this.
      

      

      

Variable


Description


      

      

HTML_TOPICS_MODE


the table of contents for a set of topics is being generated


      

      

HTML_SUBTOPICS_MODE


the actual sub-topics are being generated


      

      


      These variables represent the two passes of the topic generation process.
      

      

      4. Colours, Logos, Backgrounds and Separators
      

      4.1. Colours
      

      The following variables can be used to customise the colours used:
      

      

      

Variable


Description


      

      

HTML_BG_COLOR


the background colour


      

      

HTML_TEXT_COLOR


the colour of normal text


      

      

HTML_LINK_COLOR


the colour of links


      

      

HTML_VLINK_COLOR


the colour of visited links


      

      


      For example:
      

        !define HTML_BG_COLOR   COLOR_WHITE
  !define HTML_LINK_COLOR '00ff00'

      

      The value of each variable is the hexidecimal number representing the required RGB (Red Green Blue) combination. For convenience, the following set of color variables are provided:
      

      

      

Variable


Value


      

      

COLOR_WHITE


'ffffff'


      

      

COLOR_BLACK


'000000'


      

      

COLOR_RED


'ff0000'


      

      

COLOR_GREEN


'00ff00'


      

      

COLOR_BLUE


'0000ff'


      

      

COLOR_YELLOW


'ffff00'


      

      

COLOR_MAGENTA


'ff00ff'


      

      

COLOR_CYAN


'00ffff'


      

      

COLOR_GREY


'c0c0c0'


      

      


      4.2. Logos
      

      The following variables can be used to add a logo:
      

      

      

Variable


Description


      

      

DOC_LOGO


the default logo to use


      

      

DOC_HTML_LOGO


the logo to use at the top of each document


      

      

DOC_TOPIC_LOGO


the logo to use at the top of each topic


      

      


      To add a logo to the main document and all its topics, simply set the DOC_LOGO variable. Alternatively, different logos can be specified by using the DOC_HTML_LOGO and/or the DOC_TOPIC_LOGO variables.
      

      4.3. Background Images
      

      The following variables can be used to customise the background image, if any:
      

      

      

Variable


Description


      

      

HTML_BG_IMAGE


the URL of the file to use as the background image


      

      

HTML_BG_FIXED


if set, scrolling of the background image is disabled


      

      


      
Note: These HTML features may not be supported by all browsers.

      

      4.4. Section Separators
      

      By default, SDF places a line above each section within a document. If you want to use an alternative separator, override the HTML_PRE_SECTION macro like this:
      

          !macro HTML_PRE_SECTION
         !import "fancy_line.gif"
    !endmacro

      

      Section boundaries are determined using the heading level specified by the HTML_SECTION_LEVEL variable. To put a section separator above level 2 (and 1) headings, you can define this variable in your document or specify it on the command line like this:
      

         sdf -2html -DHTML_SECTION_LEVEL=2 myfile

      

      When a single document is being generated, the default level is 1. When sub-topics are being generated, the default level is 2.
      

      
Note: A value of 0 turns off section boundaries.

      

      

      5. Titles and Table of Contents
      

      5.1. HTML Title String
      

      To customise the title string generated by the build_title macro, set the HTML_TITLE variable after calling build_title.
      

      Alternatively, you can override the definition of the HTML_BUILD_TITLE macro before build_title is called. The default definition is:
      

      !macro HTML_BUILD_TITLE
  !if HTML_SUBTOPICS_MODE
    !if DOC_PROJECT
      !define HTML_TITLE \
        "$var{'DOC_PROJECT'}: $var{'HTML_MAIN_TITLE'}: $var{'DOC_TITLE'}"
    !else
      !define HTML_TITLE "$var{'HTML_MAIN_TITLE'}: $var{'DOC_TITLE'}"
    !endif
  !elsif DOC_PROJECT
    !define HTML_TITLE "$var{'DOC_PROJECT'}: $var{'DOC_TITLE'}"
  !else
    !define HTML_TITLE DOC_TITLE
  !endif
!endmacro

      

      5.2. Title Section
      

      To customise the title section generated by the build_title macro, override the definition of the build_html_cover macro. For example:
      

          !macro build_html_cover
        [align=Center]DOC_TITLE
    !endmacro

      

      5.3. Table of Contents Section
      

      To customise the title of the table of contents, override the DOC_TOC_TITLE variable like this:
      

        !define DOC_TOC_TITLE 'Contents'

      

      Alternatively, you can completely control the presentation of the table of contents by overriding the toc_html filter. For example:
      

      !block script
sub toc_html_Filter {
    local(*text, %param) = @_;
#   local();

    # Make top level section titles bigger
    @text = grep(s/^L1/P2/ || $_, @text);

    # Prepend a section separator and a title
    unshift(@text, "!HTML_PRE_SECTION", "P1[notoc;align=Center]Contents");
}
!endblock

      

      See the SDF Guru Guide for further information on writing your own filters.
      

      

      6. Headers and Footers
      

      You can override the default headers and footers by defining the following macros:
      

        

      • HTML_HEADER - header on a HTML document (or main topic)

      • HTML_FOOTER - footer on a HTML document (or main topic)

      • HTML_TOPIC_HEADER - header on a HTML topic

      • HTML_TOPIC_FOOTER - footer on a HTML topic.
      

      For example:
      

          !macro HTML_FOOTER
        Line:
        [align='Right']
        {{This page was last updated on [[DATE:DOC_MODIFIED]]}}
    !endmacro

      

      6.1. The Default Header/Footer Macros
      

      The default HTML_HEADER and HTML_FOOTER definitions are shown below.
      

          !macro HTML_HEADER
        !HTML_NAVIGATE
    !endmacro
    !macro HTML_FOOTER
        !HTML_PRE_SECTION
        !HTML_NAVIGATE
    !endmacro

      

      Likewise, the default header and footer on sub-topics share a macro called HTML_TOPIC_NAVIGATE. Therefore, it is usually sufficient to override HTML_NAVIGATE and/or HTML_TOPIC_NAVIGATE instead of overriding the HTML_HEADER/HTML_FOOTER and HTML_TOPIC_HEADER/HTML_TOPIC_FOOTER macros respectively.
      

      6.2. The Default Navigation Macros
      

      The default implementation of the HTML_NAVIGATE macro provides the following jumps when topics are being generated:
      

        
Previous Topic

        
Next Topic
      

      The default implementation of the HTML_TOPIC_NAVIGATE macro provides the following jumps:
      

        
Contents

        
Parent Topic

        
Previous Topic

        
Next Topic
      

      In addition, the navigation macros can optionally provide the following jumps:
      

        
Home

        
Catalog

        
Search
      

      6.3. Customising the Navigation Macros
      

      Instead of simply overriding the HTML_NAVIGATE and HTML_TOPIC_NAVIGATE macros, it is also possible to customise their output by defining the variables below:
      

      

      

Variable


Description


      

      

HTML_URL_HOME


URL of the home page


      

      

HTML_URL_CATALOG


URL of the catalog page


      

      

HTML_URL_SEARCH


URL of the search page


      

      


      For example:
      

        !define HTML_URL_HOME   "../index.html"
  !define HTML_URL_SEARCH "../search.html"

      

      If one or more of these variables are set, the default navigate macros will output a second line containing jumps to the respective pages.
      

      6.4. Customising Navigation Text
      

      If you are generally happy with the default headers and footers but want to change the text to another language, say, you can set the following variables:
      

      

      

Variable


Default Value


      

      

HTML_TEXT_CONTENTS


Contents


      

      

HTML_TEXT_PARENT


Parent


      

      

HTML_TEXT_PREVIOUS


Previous Topic


      

      

HTML_TEXT_NEXT


Next Topic


      

      

HTML_TEXT_HOME


Home


      

      

HTML_TEXT_CATALOG


Catalog


      

      

HTML_TEXT_SEARCH


Search


      

      


      The HOME, CATALOG and SEARCH variables only apply if the corresponding URL variables are set.
      

      6.5. Pre-header and Post-footer Tuning
      

      The generated HTML can be tuned by using the HTML_PRE_HEADER and HTML_POST_FOOTER variables. These variables contain HTML to be added immediately after the <BODY> and immediately before the </BODY> tags respectively. For example, a page-like border can be added to the generated HTML like this:
      

        !define HTML_PRE_HEADER  '<blockquote>'
  !define HTML_POST_HEADER '</blockquote>'

      

      

      7. Inline HTML
      

      As HTML is constantly evolving and contains features which SDF doesn't explicitly support (e.g. frames), it is occasionally necessary to directly embed native HTML. To do this, use the inline filter. For example:
      

          !block inline
    <P>
    My name is <B>Bill</B>.
    !endblock

      

      If you want to use embedded expressions (enclosed in [[ and ]]) and macros within the inline text, add the expand parameter like this:
      

          !block inline; expand
        !if DATE
            <P>
            The date is [[DATE:DOC_START]].
        !else
            <P>
            The time is [[TIME:DOC_START]].
        !endif
    !endblock

      

      Likewise, you can use the INLINE phrase style within a paragraph to embed HTML within a paragraph. For example:
      

        My name is {{INLINE:<B>Bill</B>}}.

      

      

      8. Feedback
      

      If you have any feedback on SDF or this tutorial, please let me know.
      

      

      

      

      Home | Catalog
      

      

      



TR>

>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 25-Feb-97 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

# Define variables
!define DOC_NAME     "Generating HTML Using SDF"
!define DOC_AUTHOR   "Ian Clatworthy ({{EMAIL:ianc@mincom.com}}), Research Architect, {{ORG[expand]Mincom}}"

# Build the title
!build_title

H1: Introduction

SDF is a useful tool for generating HTML documents for several reasons:

^ SDF provides a high-level language for documentation including macros,
  filters, variables, conditional text and event processing

+ SDF is more readable than HTML, making it much easier to maintain

+ Unlike HTML, SDF documents can contain user defined style names
  allowing authors to specify a document in a logical manner

+ SDF provides the features required to create any HTML document.

For a general overview of SDF, see
{{DOC: The SDF Document Development System}}.
For a general introduction to the core features in SDF,
see the {{DOC: SDF User Guide}}.

This tutorial supplements these documents by providing:

* an overview of how SDF documents are converted to HTML documents
* details on how to customise the generated HTML.


H1: Generating HTML

H2: Generating a Single Document

To generate HTML for F, the command is:

>   sdf -2html myfile

This will create a single html file called F.

H2: Changing the Output Extension

By default, SDF creates HTML files with an output extension of {{html}}.
To specify a different extension, use the -o option like this:

>   sdf -2html -ohtm myfile

H2: Sending Output to Standard Output

To send output to standard output, use the -o option like this:

>   sdf -2html -o- myfile

H2: Changing the Default Extension

If you are generating HTML for a system which only supports 8.3 filenames,
you may wish to set the default extension to be {{htm}} like this:

>   sdf -2html -DHTML_EXT=htm myfile

If you are working on a system which only supports 8.3 filenames,
you may wish to permanently set the {{HTML_EXT}} variable within
the F configuration file, so that you don't need to specify
it every time.

Unlike using the -o option, this approach changes the output extension
on all HTML files generated, including sub-topics.

H2: Generating a Set of Topics

For large documents, it is often much better to generate a set of
topics rather than a large HTML file.
To do this, the command is:

>   sdf -2topics myfile

This will create:

* a HTML file called F which contains a table of contents
* a HTML file for each topic.

H2: Controlling Topic Breaks

If you want to manually control how a document is split into
topics, simply include other sdf files which contain headings.
These manual topics, if any, can be supplemented with automatically
generated topics. By default, level 1 headings are used as topic
breaks, in addition to the manual ones. The -n (or --split_level)
option can be used to change this:

* -n0 disables autosplitting
* -n2 uses level 1-2 headings to autosplit
* -n3 uses level 1-3 headings to autosplit
* etc.


H1: Customising the Generated HTML

The following files are used to convert SDF to HTML:

!block table
File            Directory       Purpose
html.sdn        stdlib          tuning file for HTML generation
tohtml.pl       perllib/sdf     output driver for HTML generation
!endblock

The tuning file contains:

* the mapping tables used to convert SDF
  paragraph and phrase styles to HTML entities

* the default definitions of macros, variables, etc.

H2: Paragraph and Phrase Style Mappings

If you want to create new paragraph and phrase styles and/or
override the default mapping, you can edit the tuning file.
Alternatively, create a site-specific tuning file and {{MAC:use}}
it at the top of each document.

H2: Output Driver Enhancements

On some occasions, the conversion rules are too complicated
for mapping tables and need to be coded into the output driver
as Perl logic. If you need to edit the output driver, please
forward the patches to me so that everyone can benefit from
your enhancements.

H2: General Customisations

On most occasions, the generated HTML can be easily customised by
overriding the default values of variables and macros.
In particular, you can customise:

!block sections
. Colours, Logos, Backgrounds and Separators
. Titles and Table of Contents
. Headers and Footers
!endblock

Furthermore, if you really need it, {{SECT:Inline HTML}} can be
used to generate any HTML you like.

Note: If you override a macro, it is probably a good idea to start with
the default definition in the HTML tuning file, F.

H2: Topics Mode Variables

When customising the generated HTML, it is occasionally necessary
to know whether a single document or set of topics is being
generated. The following variables can be tested to determine this.

!block table
Variable                Description
HTML_TOPICS_MODE        the table of contents for a set of topics is being \
                        generated
HTML_SUBTOPICS_MODE     the actual sub-topics are being generated
!endblock
                        
These variables represent the two passes of the topic generation process.


H1: Colours, Logos, Backgrounds and Separators

H2: Colours

The following variables can be used to customise the colours used:

!block table
Variable                Description
HTML_BG_COLOR           the background colour
HTML_TEXT_COLOR         the colour of normal text
HTML_LINK_COLOR         the colour of links
HTML_VLINK_COLOR        the colour of visited links
!endblock

For example:

>  !define HTML_BG_COLOR   COLOR_WHITE
>  !define HTML_LINK_COLOR '00ff00'

The value of each variable is the hexidecimal number representing
the required RGB (Red Green Blue) combination. For convenience,
the following set of color variables are provided:

!block table
Variable      Value
COLOR_WHITE   'ffffff'
COLOR_BLACK   '000000'
COLOR_RED     'ff0000'
COLOR_GREEN   '00ff00'
COLOR_BLUE    '0000ff'
COLOR_YELLOW  'ffff00'
COLOR_MAGENTA 'ff00ff'
COLOR_CYAN    '00ffff'
COLOR_GREY    'c0c0c0'
!endblock

H2: Logos

The following variables can be used to add a logo:

!block table
Variable        Description
DOC_LOGO        the default logo to use
DOC_HTML_LOGO   the logo to use at the top of each document
DOC_TOPIC_LOGO  the logo to use at the top of each topic
!endblock

To add a logo to the main document and all its topics, simply
set the DOC_LOGO variable. Alternatively, different logos can
be specified by using the DOC_HTML_LOGO and/or the DOC_TOPIC_LOGO
variables.

H2: Background Images

The following variables can be used to customise the background image, if any:

!block table
Variable                Description
HTML_BG_IMAGE           the URL of the file to use as the background image
HTML_BG_FIXED           if set, scrolling of the background image is disabled
!endblock

Note: These HTML features may not be supported by all browsers.

H2: Section Separators

By default, SDF places a line above each section within a document.
If you want to use an alternative separator, override the
{{HTML_PRE_SECTION}} macro like this:

!block example
    !macro HTML_PRE_SECTION
         !import "fancy_line.gif"
    !endmacro
!endblock

Section boundaries are determined using the heading level specified
by the HTML_SECTION_LEVEL variable. To put a section separator above level
2 (and 1) headings, you can {{MAC:define}} this variable
in your document or specify it on the command line like this:

>   sdf -2html -DHTML_SECTION_LEVEL=2 myfile

When a single document is being generated, the default level is 1.
When sub-topics are being generated, the default level is 2.

Note: A value of 0 turns off section boundaries.


H1: Titles and Table of Contents

H2: HTML Title String

To customise the title string generated by the {{MAC:build_title}} macro,
set the HTML_TITLE variable {{after}} calling {{MAC:build_title}}.

Alternatively, you can override the definition of the
{{HTML_BUILD_TITLE}} macro before {{MAC:build_title}} is called.
The default definition is:

!block example
!macro HTML_BUILD_TITLE
  !if HTML_SUBTOPICS_MODE
    !if DOC_PROJECT
      !define HTML_TITLE \
        "$var{'DOC_PROJECT'}: $var{'HTML_MAIN_TITLE'}: $var{'DOC_TITLE'}"
    !else
      !define HTML_TITLE "$var{'HTML_MAIN_TITLE'}: $var{'DOC_TITLE'}"
    !endif
  !elsif DOC_PROJECT
    !define HTML_TITLE "$var{'DOC_PROJECT'}: $var{'DOC_TITLE'}"
  !else
    !define HTML_TITLE DOC_TITLE
  !endif
!endmacro
!endblock

H2: Title Section

To customise the title section generated by the {{MAC:build_title}} macro,
override the definition of the {{build_html_cover}} macro.
For example:

!block example
    !macro build_html_cover
        [align=Center]DOC_TITLE
    !endmacro
!endblock

H2: Table of Contents Section

To customise the title of the table of contents, override the
DOC_TOC_TITLE variable like this:

>  !define DOC_TOC_TITLE 'Contents'

Alternatively, you can completely control the presentation of
the table of contents by overriding the {{toc_html}} filter.
For example:

!block example
!block script
sub toc_html_Filter {
    local(*text, %param) = @_;
#   local();

    # Make top level section titles bigger
    @text = grep(s/^L1/P2/ || $_, @text);

    # Prepend a section separator and a title
    unshift(@text, "!HTML_PRE_SECTION", "P1[notoc;align=Center]Contents");
}
!endblock
!endblock

See the {{DOC: SDF Guru Guide}} for further information on
writing your own filters.


H1: Headers and Footers

You can override the default headers and footers by defining
the following macros:

* HTML_HEADER - header on a HTML document (or main topic)
* HTML_FOOTER - footer on a HTML document (or main topic)
* HTML_TOPIC_HEADER - header on a HTML topic
* HTML_TOPIC_FOOTER - footer on a HTML topic.

For example:

!block verbatim
    !macro HTML_FOOTER
        Line:
        [align='Right']
        {{This page was last updated on [[DATE:DOC_MODIFIED]]}}
    !endmacro
!endblock

H2: The Default Header/Footer Macros

The default HTML_HEADER and HTML_FOOTER definitions are shown below.

!block verbatim
    !macro HTML_HEADER
        !HTML_NAVIGATE
    !endmacro
    !macro HTML_FOOTER
        !HTML_PRE_SECTION
        !HTML_NAVIGATE
    !endmacro
!endblock

Likewise, the default header and footer on sub-topics share a
macro called HTML_TOPIC_NAVIGATE. Therefore, it is usually
sufficient to override HTML_NAVIGATE and/or HTML_TOPIC_NAVIGATE
instead of overriding the HTML_HEADER/HTML_FOOTER and
HTML_TOPIC_HEADER/HTML_TOPIC_FOOTER macros respectively.

H2: The Default Navigation Macros

The default implementation of the HTML_NAVIGATE macro provides
the following jumps when topics are being generated:

. Previous Topic
. Next Topic

The default implementation of the HTML_TOPIC_NAVIGATE macro provides
the following jumps:

. Contents
. Parent Topic
. Previous Topic
. Next Topic

In addition, the navigation macros can optionally provide
the following jumps:

. Home
. Catalog
. Search

H2: Customising the Navigation Macros

Instead of simply overriding the HTML_NAVIGATE and HTML_TOPIC_NAVIGATE
macros, it is also possible to customise their output by defining the
variables below:

!block table
Variable                Description
HTML_URL_HOME           URL of the home page
HTML_URL_CATALOG        URL of the catalog page
HTML_URL_SEARCH         URL of the search page
!endblock

For example:

>  !define HTML_URL_HOME   "../index.html"
>  !define HTML_URL_SEARCH "../search.html"

If one or more of these variables are set, the default navigate macros
will output a second line containing jumps to the respective pages.

H2: Customising Navigation Text

If you are generally happy with the default headers and footers
but want to change the text to another language, say, you can set
the following variables:

!block table
Variable                Default_Value
HTML_TEXT_CONTENTS      Contents
HTML_TEXT_PARENT        Parent
HTML_TEXT_PREVIOUS      Previous Topic
HTML_TEXT_NEXT          Next Topic
HTML_TEXT_HOME          Home
HTML_TEXT_CATALOG       Catalog
HTML_TEXT_SEARCH        Search
!endblock

The HOME, CATALOG and SEARCH variables only apply if the corresponding
URL variables are set.

H2: Pre-header and Post-footer Tuning

The generated HTML can be tuned by using the HTML_PRE_HEADER
and HTML_POST_FOOTER variables. These variables contain HTML
to be added immediately after the  and immediately before
the  tags respectively. For example, a page-like border can be
added to the generated HTML like this:

>  !define HTML_PRE_HEADER  '
      '
>  !define HTML_POST_HEADER '
      '


H1: Inline HTML

As HTML is constantly evolving and contains features which SDF
doesn't explicitly support (e.g. frames), it is occasionally necessary
to directly embed native HTML. To do this, use the {{FILT:inline}} filter.
For example:

!block verbatim
    !block inline
    
      
    My name is Bill.
    !endblock
!endblock

If you want to use embedded expressions (enclosed in E<2[> and E<2]>)
and macros within the inline text, add the {{expand}} parameter like this:

!block verbatim
    !block inline; expand
        !if DATE
            
      
            The date is [[DATE:DOC_START]].
        !else
            
      
            The time is [[TIME:DOC_START]].
        !endif
    !endblock
!endblock

Likewise, you can use the INLINE phrase style within a paragraph
to embed HTML within a paragraph. For example:

>  My name is {{INLINE:Bill}}.


H1: Feedback

If you have any feedback on SDF or this tutorial, please let me know.
he tuning file contains:

* the mapping tables used to convert SDF
  paragraph and phrase styles to HTML entities

* the default definitions of macros, variables, etc.

H2: Paragraph and Phrase Style Mappings

If you want to create new paragraph and phrase styles and/or
override the default mapping, you can edit the tuning file.
Alternatively, create a site-specific tuning file and {{MAC:use}}
it at the top of each document.

H2: Output Driver Enhasdf-2.001/doc/faq/004075500042570001753000000000000672243775100134525ustar00iancmtr00000400000236sdf-2.001/doc/faq/faq.sdf010064400042570001753000000015710636235560200147120ustar00iancmtr00000400000236!init OPT_CONFIG='sdf'; SDF_ROOT="../"
# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 14-Jul-97 ianc    2.000beta11 release
# 23-Apr-96 ianc    2.000beta4c release
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

# Define variables
!define DOC_NAME    "SDF"
!define DOC_TYPE    "Frequently Asked Questions"
!define DOC_AUTHOR  "Ian Clatworthy"

# Build the title page
!build_title

# Set up the HTML footer
!macro HTML_CONTENTS_FOOTER
    Line:
    [align='Center']
    {{A[jump="home.html"] Home}}
!endmacro

!include "faq_gen.sdf"
!include "faq_real.sdf"
!include "faq_fmts.sdf"
!include "faq_lang.sdf"
sdf-2.001/doc/faq/faq_fmts.sdf010064400042570001753000000077660647021546000157540ustar00iancmtr00000400000236H1: Output Formats

H2: What output formats does SDF directly support?

HTML, plain text, POD, MIF (Maker Interchange Format), SGML,
MIMS F6 help and MIMS HTX.

When generating HTML, either a single document or a set of
topics can be created.

When generating MIF, either a single document or a FrameMaker
book and set of chapters can be created.


H2: What output formats does SDF indirectly support?

By using the pod2* programs provided with Perl 5, SDF
can generate man pages, LaTeX files, PostScript and a few other
formats.

By using FrameMaker, SDF can indirectly generate PostScript,
FrameViewer, RTF and other formats which FrameMaker can export.
On Unix, most of these can be generated using FrameMaker's
batch utility (fmbatch). On other platforms, it is necessary to
generate a MIF file, open it in FrameMaker and print, save or
export to the required format.

By using {{SGML-Tools}} 1.02 or later, SDF can indirectly
generate LaTeX, RTF, GNU Info and LyX formats. If LaTeX is
also installed, SDF can indirectly generate PostScript and DVI.


H2: Why should I use SDF when my word processor can generate HTML?

Unlike WYSIWYG tools, SDF encourages authors to specify documents in
a {{logical}} manner. As a result, SDF has the {{semantics}} it needs
to generate high quality paper-based and online documents.

SDF also includes a number of features which greatly simplify the effort
required to produce online documents. These include:

* centralised hypertext management
* rule-based hypertext generation.

It could be a long time before word processors provide these features.
As a result, it takes a lot less effort (and cost) to create and
maintain a large online documentation system in SDF when compared to
existing WYSIWYG tools (that I know about, at least).


H2: Can SDF generate Word documents?

Not directly. However, SDF can generate RTF (Rich Text Format) files
which can be opened in Word and many other word processors.
The commands to convert a file called F to RTF are:

E:   sdf -2rtf_mif  mydoc.sdf
E:   sdf -2rtf_fm   mydoc.sdf
E:   sdf -2rtf_sgml mydoc.sdf
E:   sdf -2rtf      mydoc.sdf

The first of these works by generating a MIF (Maker Interchange Format)
file and then converting it to RTF via a Perl script supplied with
SDF called {{mif2rtf}}. The main problems with mif2rtf are:

^ it is slow
+ the output is not as great as one would hope for
+ it occasionally crashes. :-(

The second command works by generating a MIF file and then converting
it to RTF via FrameMaker's RTF export filter. This approach is more
reliable than using mif2rtf, although it has it own set of problems
and limitations.

The third command works by generating a SGML file and then uses
{{SGML-Tools}} to generate RTF. I haven't tested {{SGML-Tools}}'s
RTF generation, so I have no idea how well this will work.

The forth command is an alias for one of the commands above.
See the {{FormatMapping}} section of the F file to
view and/or edit the mapping.

Oneday, SDF will support RTF directly.


H2: Can SDF generate Windows help?

SDF can generate RTF files and HPJ files which are the
inputs to a Windows 3.x help compiler (e.g. hcp.exe).

I haven't tried building help for Windows 95 or NT,
so I'm not sure how well that works or otherwise.
In any case, Microsoft is moving to HTML for online
help, so I'm not overly motivated to improve the
existing support for Windows help.


H2: Is FrameMaker needed for generating PostScript?

No. [[SDF]] can generate PostScript via the freely available
{{pod2ps}} program or the freely available {{SGML-Tools}}/{{LaTeX}}
packages.

However, if you have [[FrameMaker]], using it currently
has the following advantages:

* the [[PostScript]] it generates looks better than that generated by
  most other packages (at the moment)

* SDF currently supports [[FrameMaker]] better than other packages
  in some areas (e.g. indexes)

* SDF has been tested with [[FrameMaker]] much more than other packages.

Alternatively, SDF can be used to generate RTF which can then be imported
into most word processors.
sdf-2.001/doc/faq/index.html010044400042570001753000000517350672242076000154450ustar00iancmtr00000400000236






SDF 2.001: SDF Frequently Asked Questions




      

      

      Home | Catalog
      

      

      

      

      

      SDF Frequently Asked Questions
      

      SDF-FAQ.001 (Final)
      

      Ian Clatworthy
      

      25 May 1999
      

      

      

      

      

      Table of Contents
      


      

      

      

      1. General Questions
      

      1.1. Where can I get this document?
      

      The latest version of this FAQ is available from http://www.mincom.com/mtr/sdf/faq/.
      

      1.2. What is SDF?
      

      SDF (Simple Document Format) is a freely available documentation system designed and developed by Ian Clatworthy, with help from many others. Based on a simple, readable markup language, SDF generates high quality output in multiple formats, all derived from a single document source. Supported output formats include HTML, PostScript, PDF, man pages, SGML, POD, LaTeX, GNU Info, MIF, RTF, Windows help and plain text. If you want to:
      

        

      • publish documents or reports on the Web or in multiple formats

      • maintain a large documentation suite using rule-based formatting and hypertext generation

      • embed documentation in source code or pretty print source code
      

      then SDF may be for you.
      

      1.3. What platforms are supported?
      

      SDF documents are plain text files which can be created on any platform.
      

      The SDF software has been completely developed in Perl, so it can be executed on all commonly used platforms including most variants of Unix, most variants of Windows, OS/2, the Macintosh and VMS. Perl 5.003 or later is required.
      

      1.4. How do I get it?
      

      SDF is available in a number of formats from http://www.mincom.com/mtr/sdf/download.html. It should also be available from CPAN, the Comprehensive Perl Archive Network.
      

      1.5. What else is required?
      

      To generate PostScript, SDF requires one of the following:
      


      Earlier versions of FrameMaker will generally work, but I don't explicitly support them.
      

      To generate PDF, Adobe Acrobat is required.
      

      To generate Windows help, a help compiler (e.g. hcp.exe) is required.
      

      1.6. How can I learn SDF?
      

      Generally, the best way to learn SDF is to read the overview paper called The SDF Document Development System - it should contain enough details to get you started. If you need further information on the commonly used features, read the first few chapters of the SDF User Guide.
      

      If you already know Perl's POD format, you might want to read the SDF for POD Users tutorial before these.
      

      In practice, 99% of SDF documents are created by copying an existing one and making the necessary changes. So, once you're created templates for the types of documents you commonly produce, things are pretty simple ...
      

      1.7. How is SDF supported?
      

      The following mailing lists are available:
      


      To subscribe to these lists, send email to sdf-users-request@mincom.com and/or sdf-bugs-request@mincom.com for instructions on using factotum, the majordomo variant that manages these lists. In short, send email to factotum@mincom.com with a message body of subscribe sdf-users or subscribe sdf-bugs.
      

      An on-line bug database is also available providing information on some of the known bugs and requested enhancements.
      

      1.8. Why is SDF free?
      

      I have always wanted to contribute a useful tool back to the worldwide software community which has given me so many useful tools (e.g. Perl). As there appears to be very few documentation tools which:
      

        

      1. generate high quality output in multiple formats, and

      2. reduce the time it takes to produce software documentation
      

      SDF will hopefully be useful to a large number of software developers.
      

      Also, by being freely available, SDF should benefit in several ways. These include more testers, more add-on tools and more design ideas.
      

      1.9. Is SDF still simple?
      

      Arguably not. But SDF has remained simple in spirit, so the name hasn't been changed. Maybe Software Document Format would be a better choice, given that SDF is part mark-up language, part programming language. Feel free to make SDF stand for whatever you like.
      

      1.10. Why the grapes logo?
      

      After considering a few logos with a paper/writing theme, it was decided to follow that great software package tradition - a meaningless logo! As an on-line documentation system is essentially a cluster of topics linked together, I looked for something which reflected that idea. After 10 minutes, the best I could do was grapes, a fern or a wattle flower. After 5 seconds of agonising decision making, the prize went to the grapes.
      

      Fortunately, there seems to be some useful parallels:
      

        

      • from a single input (type of grape), several high quality outputs (grape juice/wines/spirits) can be generated (likewise SDF)

      • grapes are quite palatable on their own (as is SDF).
      

      Ok - it's not as sexy as a cup of coffee, but grapes, grape juice and red wine (at least) are probably better for you. :-)
      

      1.11. How can I help?
      

      In lots of ways:
      

      Tell your friends about SDF.
      

        
The more users SDF has, the sooner bugs are found and fixed.
      

      Tell the world about SDF.
      

        
If SDF has made your job more enjoyable, consider writing an article for a magazine explaining why.
      

      Report bugs.
      


      Make SDF more useful.
      

        
If SDF doesn't generate an output format you need, consider developing an output driver for that format. Depending on your Perl programming skills, this can take as little as a few days.
      

      Make it easier for people to migrate to SDF.
      

        
Consider developing a converter from an existing format to SDF. For example, a high quality RTF to SDF converter would be extremely useful.
      

      

      2. SDF in the real world
      

      2.1. How stable is SDF?
      

      Other than some syntax changes introduced in 2.000beta10 to make SDF more palatable for users of Perl's POD format, the core SDF code hasn't changed much since early 1996. Within Mincom, people have been using SDF on a daily basis for at least 4 or 5 years now.
      

      2.2. How many people are using SDF?
      

      At the moment (February 98), my guess is that SDF has 50-100 users within Mincom and a few hundred within other organisations. Excluding Mincom, SDF has active users within a large number of countries including Australia, Belgium, Canada, Denmark, England, Germany, France, Italy, New Zealand, Norway, Russia and the USA.
      

      2.3. What is SDF being used for?
      

      Within Mincom, SDF is used for a large number of purposes including:
      

        

      • The user documentation for Mincom's flagship product, MIMS Open Enterprise. This is a large documentation suite containing over 11,000 A4 pages and over 10,000 HTML topics with over 144,000 hypertext jumps. All of the hypertext is automatically generated, greatly reducing the maintenance cost of the online documentation.

      • All of the documents produced by the MIMS Technology Research (MTR) group within the last 3 years, i.e. a few hundred documents, and a Web-based project information system for all MTR projects. (The MTR group is the home of SDF.)

      • Embedded documentation within C and C++ code.

      • Documentation for Delphi components developed in-house.

      • Documentation for Perl modules developed in-house.

      • The documentation for SDF itself.
      

      Outside of Mincom, SDF is also used for many things including:
      


      
Note: If you are using SDF and would like to be mentioned above, send me some email.

      

      SDF can also be used to convert documentation in Perl's POD format to any output format supported by SDF. For example, the HTML produced by SDF for Perl's documentation is available at http://www.mincom.com/mtr/perl/catalog.html.
      

      2.4. What new developments are expected for SDF in the future?
      

      My current priorites are:
      

        

      1. Supporting existing SDF users (by email and bug fixes).

      2. Developing the next generation of SDF called SimpleDoc.
      

      The key objectives of SimpleDoc are:
      

        

      • upwards compatibility with SDF

      • a new architecture which supports:
          

        • multiple input parsers (SDF, XML and POD)

        • output formatters which are decoupled from the input format
        

      • Perl 5 modules

      • better performance

      • support for XML output (in addition to XML input)

      • support for HTML-Help output

      • support for Java-Help output

      • better LaTeX output.
      

      As always, my time is limited, so if one or more of the above features interests you, let me know so I can prioritise things accordingly.
      

      Further information on SimpleDoc is available on the web. The URL is http://www.mincom.com/mtr/simpledoc/.
      

      

      3. Output Formats
      

      3.1. What output formats does SDF directly support?
      

      HTML, plain text, POD, MIF (Maker Interchange Format), SGML, MIMS F6 help and MIMS HTX.
      

      When generating HTML, either a single document or a set of topics can be created.
      

      When generating MIF, either a single document or a FrameMaker book and set of chapters can be created.
      

      3.2. What output formats does SDF indirectly support?
      

      By using the pod2* programs provided with Perl 5, SDF can generate man pages, LaTeX files, PostScript and a few other formats.
      

      By using FrameMaker, SDF can indirectly generate PostScript, FrameViewer, RTF and other formats which FrameMaker can export. On Unix, most of these can be generated using FrameMaker's batch utility (fmbatch). On other platforms, it is necessary to generate a MIF file, open it in FrameMaker and print, save or export to the required format.
      

      By using SGML-Tools 1.02 or later, SDF can indirectly generate LaTeX, RTF, GNU Info and LyX formats. If LaTeX is also installed, SDF can indirectly generate PostScript and DVI.
      

      3.3. Why should I use SDF when my word processor can generate HTML?
      

      Unlike WYSIWYG tools, SDF encourages authors to specify documents in a logical manner. As a result, SDF has the semantics it needs to generate high quality paper-based and online documents.
      

      SDF also includes a number of features which greatly simplify the effort required to produce online documents. These include:
      

        

      • centralised hypertext management

      • rule-based hypertext generation.
      

      It could be a long time before word processors provide these features. As a result, it takes a lot less effort (and cost) to create and maintain a large online documentation system in SDF when compared to existing WYSIWYG tools (that I know about, at least).
      

      3.4. Can SDF generate Word documents?
      

      Not directly. However, SDF can generate RTF (Rich Text Format) files which can be opened in Word and many other word processors. The commands to convert a file called mydoc.sdf to RTF are:
      

         sdf -2rtf_mif  mydoc.sdf
   sdf -2rtf_fm   mydoc.sdf
   sdf -2rtf_sgml mydoc.sdf
   sdf -2rtf      mydoc.sdf

      

      The first of these works by generating a MIF (Maker Interchange Format) file and then converting it to RTF via a Perl script supplied with SDF called mif2rtf. The main problems with mif2rtf are:
      

        

      1. it is slow

      2. the output is not as great as one would hope for

      3. it occasionally crashes. :-(
      

      The second command works by generating a MIF file and then converting it to RTF via FrameMaker's RTF export filter. This approach is more reliable than using mif2rtf, although it has it own set of problems and limitations.
      

      The third command works by generating a SGML file and then uses SGML-Tools to generate RTF. I haven't tested SGML-Tools's RTF generation, so I have no idea how well this will work.
      

      The forth command is an alias for one of the commands above. See the FormatMapping section of the sdf.ini file to view and/or edit the mapping.
      

      Oneday, SDF will support RTF directly.
      

      3.5. Can SDF generate Windows help?
      

      SDF can generate RTF files and HPJ files which are the inputs to a Windows 3.x help compiler (e.g. hcp.exe).
      

      I haven't tried building help for Windows 95 or NT, so I'm not sure how well that works or otherwise. In any case, Microsoft is moving to HTML for online help, so I'm not overly motivated to improve the existing support for Windows help.
      

      3.6. Is FrameMaker needed for generating PostScript?
      

      No. SDF can generate PostScript via the freely available pod2ps program or the freely available SGML-Tools/LaTeX packages.
      

      However, if you have FrameMaker, using it currently has the following advantages:
      

        

      • the PostScript it generates looks better than that generated by most other packages (at the moment)

      • SDF currently supports FrameMaker better than other packages in some areas (e.g. indexes)

      • SDF has been tested with FrameMaker much more than other packages.
      

      Alternatively, SDF can be used to generate RTF which can then be imported into most word processors.
      

      

      4. Language Issues
      

      4.1. How do I enter an empty row in a table?
      

      TBL format ignores blanks lines, so to enter an empty line, you need to enter an empty cell like this:
      

      !block table
Big     Small
A       a
{{}}
B       b
!endblock

      

      The result is:
      

      

      

Big


Small


      

      

A


a


      

      

 


 


      

      

B


b


      

      


      4.2. How do I enter a multi-line cell in a table?
      

      By beginning a cell with a << symbol like this:
      

      !block table
Option  Description
-g      <<
        This option produces the following:

        !import "g_code"
>>
-v      verbose mode
!endblock

      

      
Note: 
      

        

      1. The cell is terminated by a >> symbol at the beginning of a line.

      2. You can place any SDF you like within the cell.

      3. Whitespace is generally ignored at the beginning of lines, so you can put the cell contents under its column heading if you want to.

      4. If the multi-line cell is not the last one within the row, you currently need to format the table using delimited format rather than fixed width format.
      

      

      

      

      

      Home | Catalog
      

      

      



dred within other organisations. Exsdf-2.001/doc/faq/faq_real.sdf010064400042570001753000000064150647530164400157210ustar00iancmtr00000400000236H1: SDF in the real world

H2: How stable is SDF?

Other than some syntax changes introduced in 2.000beta10
to make SDF more palatable for users of Perl's POD format,
the core SDF code hasn't changed much since early 1996.
Within Mincom, people have been using SDF on a daily
basis for at least 4 or 5 years now.


H2: How many people are using SDF?

At the moment (February 98), my guess is that SDF has 50-100
users within [[Mincom]] and a few hundred within other organisations.
Excluding Mincom, SDF has active users within a large number of countries
including Australia, Belgium, Canada, Denmark, England, Germany, France, Italy,
New Zealand, Norway, Russia and the USA.


H2: What is SDF being used for?

Within [[Mincom]], SDF is used for a large number of purposes including:

* The user documentation for Mincom's flagship product, MIMS Open Enterprise.
  This is a large documentation suite containing over 11,000
  A4 pages and over 10,000 HTML topics with over 144,000
  hypertext jumps. All of the hypertext is automatically
  generated, greatly reducing the maintenance cost of
  the online documentation.

* All of the documents produced by the MIMS Technology Research (MTR)
  group within the last 3 years, i.e. a few hundred documents, and
  a Web-based project information system for all MTR projects.
  (The MTR group is the home of SDF.)

* Embedded documentation within C and C++ code.

* Documentation for Delphi components developed in-house.

* Documentation for Perl modules developed in-house.

* The documentation for SDF itself.

Outside of Mincom, SDF is also used for many things including:

* The SSLeay FAQ ({{http://www.psy.uq.edu.au/~ftp/Crypto/}})

* All of the documentation produced by Cryptsoft Pty Ltd
  ({{http://www.cryptsoft.com}})

* Documentation for the Ultimate editor
  ({{http://http://www.ufs.com.au/}})

* The Fulcrum Consulting Group ({{http://www.fulcrum.com.au}}) are using SDF
  for automatically generating periodic customer reports for
  publishing in a variety of formats, and also for internal procedures.

* Lots of other interesting things I'm unable to mention
  until I get permission to do so.

Note: If you are using SDF and would like to be mentioned above,
send me some email.

SDF can also be used to convert documentation in Perl's POD
format to any output format supported by SDF. For example,
the HTML produced by SDF for Perl's documentation is available
at {{http://www.mincom.com/mtr/perl/catalog.html}}.


H2: What new developments are expected for SDF in the future?

My current priorites are:

^ Supporting existing SDF users (by email and bug fixes).
+ Developing the next generation of SDF called {{PRD:SimpleDoc}}.

The key objectives of SimpleDoc are:

* upwards compatibility with SDF
* a new architecture which supports:
  - multiple input parsers (SDF, XML and POD)
  - output formatters which are decoupled from the input format
* Perl 5 modules
* better performance
* support for XML output (in addition to XML input)
* support for HTML-Help output
* support for Java-Help output
* better LaTeX output.

As always, my time is limited, so if one or more of the above features
interests you, let me know so I can prioritise things accordingly.

Further information on SimpleDoc is available on the web. The URL is
{{http://www.mincom.com/mtr/simpledoc/}}.
sdf-2.001/doc/faq/faq_gen.sdf010064400042570001753000000132720647625273400155540ustar00iancmtr00000400000236H1: General Questions

H2: Where can I get this document?

The latest version of this FAQ is available from
{{http://www.mincom.com/mtr/sdf/faq/}}.

H2: What is SDF?

SDF (Simple Document Format) is a freely available
documentation system designed and developed by
{{A[jump="mailto:ianc@mincom.com"] Ian Clatworthy}}, with help from
many others. Based on a simple, readable markup language,
SDF generates high quality output in multiple formats, all 
derived from a single document source.
Supported output formats include HTML, PostScript, PDF, man pages,
SGML, POD, LaTeX, GNU Info, MIF, RTF, Windows help and plain text.
If you want to:

* publish documents or reports on the Web or in multiple formats
* maintain a large documentation suite using rule-based formatting and
  hypertext generation
* embed documentation in source code or pretty print source code

then SDF may be for you.


H2: What platforms are supported?

SDF documents are plain text files which can be created on any platform.

The SDF software has been completely developed in Perl, so it
can be executed on all commonly used platforms including most variants
of Unix, most variants of Windows, OS/2, the Macintosh and VMS.
Perl 5.003 or later is required.


H2: How do I get it?

SDF is available in a number of formats from {{URL:[[SDF_DOWNLOAD]]}}.
It should also be available from CPAN, the Comprehensive Perl Archive
Network.

H2: What else is required?

To generate PostScript, SDF requires one of the following:

* the freely available {{pod2ps}} program, available from
  {{http://www.oasis.leo.org/perl/scripts/textproc/pod2ps.dsc.html}}
* the freely available {{SGML-Tools}} and {{LaTeX}} packages
* FrameMaker 5.x or later
* another word processor which can import RTF.

Earlier versions of FrameMaker will generally work, but I don't
explicitly support them.

To generate PDF, [[Adobe]] {{PRD:Acrobat}} is required.

To generate Windows help, a help compiler (e.g. hcp.exe) is required.


H2: How can I learn SDF?

Generally, the best way to learn SDF is to read the overview paper
called {{DOC:The SDF Document Development System}} - it should
contain enough details to get you started. If you need further
information on the commonly used features,
read the first few chapters of the {{DOC: SDF User Guide}}.

If you already know Perl's POD format, you might want to read
the {{DOC: SDF for POD Users}} tutorial before these.

In practice, 99% of SDF documents are created by copying
an existing one and making the necessary changes. So,
once you're created templates for the types of documents
you commonly produce, things are pretty simple ...


H2: How is SDF supported?

The following mailing lists are available:

* {{EMAIL:sdf-users@mincom.com}} - for general questions
* {{EMAIL:sdf-bugs@mincom.com}} - for reporting bugs and fixes.

To subscribe to these lists, send email to
{{EMAIL:sdf-users-request@mincom.com}} and/or
{{EMAIL:sdf-bugs-request@mincom.com}} for instructions on
using {{factotum}}, the majordomo variant that manages these lists.
In short, send email to {{EMAIL:factotum@mincom.com}} with a
message body of {{subscribe sdf-users}} or {{subscribe sdf-bugs}}.

An on-line {{A[jump="http://www.mincom.com/mtr/sdf/bugs/"] bug database}}
is also available providing information on some of the known bugs and requested
enhancements.


H2: Why is SDF free?

I have always wanted to contribute a useful tool {{back}}
to the worldwide software community which has given me so many
useful tools (e.g. [[Perl]]). As there appears to be very few
documentation tools which:

^ generate high quality output in multiple formats, and
+ reduce the time it takes to produce software documentation

[[SDF]] will hopefully be useful to a large number of software developers.

Also, by being freely available, SDF should benefit in several ways.
These include more testers, more add-on tools and more design ideas.


H2: Is SDF still simple?

Arguably not. But SDF has remained simple in spirit, so the name
hasn't been changed. Maybe {{Software Document Format}} would
be a better choice, given that SDF is part mark-up language,
part programming language. Feel free to make SDF stand for
whatever you like.


H2: Why the grapes logo?

After considering a few logos with a paper/writing theme, it was
decided to follow that great software package tradition - a
meaningless logo! As an on-line documentation system is essentially
a cluster of topics linked together, I looked for something which
reflected that idea. After 10 minutes, the best I could do was
grapes, a fern or a wattle flower. After 5 seconds of
agonising decision making, the prize went to the grapes.

Fortunately, there seems to be some useful parallels:

* from a single input (type of grape), several high quality
  outputs (grape juice/wines/spirits) can be generated (likewise SDF)
* grapes are quite palatable on their own (as is SDF).

Ok - it's not as sexy as a cup of coffee, but grapes, grape juice
and red wine (at least) are probably better for you. :-)


H2: How can I help?

In lots of ways:

& Tell your friends about SDF.
. The more users SDF has, the sooner bugs are found and fixed.

& Tell the world about SDF.
. If SDF has made your job more enjoyable, consider writing an
  article for a magazine explaining why.

& Report bugs.
. If you find a bug, report it to {{EMAIL:sdf-bugs@mincom.com}}.
  Patches are very welcome.

& Make SDF more useful.
. If SDF doesn't generate an output format you need, consider
  developing an output driver for that format. Depending on your
  Perl programming skills, this can take as little as a few days.

& Make it easier for people to migrate to SDF.
. Consider developing a converter from an existing format to SDF.
  For example, a high quality RTF to SDF converter would be
  extremely useful.
sdf-2.001/doc/faq/faq_lang.sdf010064400042570001753000000022430647022342200157020ustar00iancmtr00000400000236H1: Language Issues

H2: How do I enter an empty row in a table?

TBL format ignores blanks lines, so to enter an empty
line, you need to enter an empty cell like this:

!block verbatim
!block table
Big     Small
A       a
{{}}
B       b
!endblock
!endblock

The result is:

!block table
Big     Small
A       a
{{}}
B       b
!endblock


H2: How do I enter a multi-line cell in a table?

By beginning a cell with a << symbol like this:

!block example
!block table
Option  Description
-g      <<
        This option produces the following:

        !import "g_code"
>>
-v      verbose mode
!endblock
!endblock

!block note
^ The cell is terminated by a >> symbol at the beginning of a line.
+ You can place any SDF you like within the cell.
+ Whitespace is generally ignored at the beginning of lines, so you can
  put the cell contents under its column heading if you want to.
+ If the multi-line cell is not the last one within the row,
  you currently need to format the table using delimited format rather
  than fixed width format.
!endblock

#H2: How Does SDF Generate Hypertext Targets for Headings?
#
#By default, SDF uses the heading text to generate a hypertext
#target name.
sdf-2.001/doc/faq/faq.html010064400042570001753000000517350672242076000151070ustar00iancmtr00000400000236






SDF 2.001: SDF Frequently Asked Questions




      

      

      Home | Catalog
      

      

      

      

      

      SDF Frequently Asked Questions
      

      SDF-FAQ.001 (Final)
      

      Ian Clatworthy
      

      25 May 1999
      

      

      

      

      

      Table of Contents
      


      

      

      

      1. General Questions
      

      1.1. Where can I get this document?
      

      The latest version of this FAQ is available from http://www.mincom.com/mtr/sdf/faq/.
      

      1.2. What is SDF?
      

      SDF (Simple Document Format) is a freely available documentation system designed and developed by Ian Clatworthy, with help from many others. Based on a simple, readable markup language, SDF generates high quality output in multiple formats, all derived from a single document source. Supported output formats include HTML, PostScript, PDF, man pages, SGML, POD, LaTeX, GNU Info, MIF, RTF, Windows help and plain text. If you want to:
      

        

      • publish documents or reports on the Web or in multiple formats

      • maintain a large documentation suite using rule-based formatting and hypertext generation

      • embed documentation in source code or pretty print source code
      

      then SDF may be for you.
      

      1.3. What platforms are supported?
      

      SDF documents are plain text files which can be created on any platform.
      

      The SDF software has been completely developed in Perl, so it can be executed on all commonly used platforms including most variants of Unix, most variants of Windows, OS/2, the Macintosh and VMS. Perl 5.003 or later is required.
      

      1.4. How do I get it?
      

      SDF is available in a number of formats from http://www.mincom.com/mtr/sdf/download.html. It should also be available from CPAN, the Comprehensive Perl Archive Network.
      

      1.5. What else is required?
      

      To generate PostScript, SDF requires one of the following:
      


      Earlier versions of FrameMaker will generally work, but I don't explicitly support them.
      

      To generate PDF, Adobe Acrobat is required.
      

      To generate Windows help, a help compiler (e.g. hcp.exe) is required.
      

      1.6. How can I learn SDF?
      

      Generally, the best way to learn SDF is to read the overview paper called The SDF Document Development System - it should contain enough details to get you started. If you need further information on the commonly used features, read the first few chapters of the SDF User Guide.
      

      If you already know Perl's POD format, you might want to read the SDF for POD Users tutorial before these.
      

      In practice, 99% of SDF documents are created by copying an existing one and making the necessary changes. So, once you're created templates for the types of documents you commonly produce, things are pretty simple ...
      

      1.7. How is SDF supported?
      

      The following mailing lists are available:
      


      To subscribe to these lists, send email to sdf-users-request@mincom.com and/or sdf-bugs-request@mincom.com for instructions on using factotum, the majordomo variant that manages these lists. In short, send email to factotum@mincom.com with a message body of subscribe sdf-users or subscribe sdf-bugs.
      

      An on-line bug database is also available providing information on some of the known bugs and requested enhancements.
      

      1.8. Why is SDF free?
      

      I have always wanted to contribute a useful tool back to the worldwide software community which has given me so many useful tools (e.g. Perl). As there appears to be very few documentation tools which:
      

        

      1. generate high quality output in multiple formats, and

      2. reduce the time it takes to produce software documentation
      

      SDF will hopefully be useful to a large number of software developers.
      

      Also, by being freely available, SDF should benefit in several ways. These include more testers, more add-on tools and more design ideas.
      

      1.9. Is SDF still simple?
      

      Arguably not. But SDF has remained simple in spirit, so the name hasn't been changed. Maybe Software Document Format would be a better choice, given that SDF is part mark-up language, part programming language. Feel free to make SDF stand for whatever you like.
      

      1.10. Why the grapes logo?
      

      After considering a few logos with a paper/writing theme, it was decided to follow that great software package tradition - a meaningless logo! As an on-line documentation system is essentially a cluster of topics linked together, I looked for something which reflected that idea. After 10 minutes, the best I could do was grapes, a fern or a wattle flower. After 5 seconds of agonising decision making, the prize went to the grapes.
      

      Fortunately, there seems to be some useful parallels:
      

        

      • from a single input (type of grape), several high quality outputs (grape juice/wines/spirits) can be generated (likewise SDF)

      • grapes are quite palatable on their own (as is SDF).
      

      Ok - it's not as sexy as a cup of coffee, but grapes, grape juice and red wine (at least) are probably better for you. :-)
      

      1.11. How can I help?
      

      In lots of ways:
      

      Tell your friends about SDF.
      

        
The more users SDF has, the sooner bugs are found and fixed.
      

      Tell the world about SDF.
      

        
If SDF has made your job more enjoyable, consider writing an article for a magazine explaining why.
      

      Report bugs.
      


      Make SDF more useful.
      

        
If SDF doesn't generate an output format you need, consider developing an output driver for that format. Depending on your Perl programming skills, this can take as little as a few days.
      

      Make it easier for people to migrate to SDF.
      

        
Consider developing a converter from an existing format to SDF. For example, a high quality RTF to SDF converter would be extremely useful.
      

      

      2. SDF in the real world
      

      2.1. How stable is SDF?
      

      Other than some syntax changes introduced in 2.000beta10 to make SDF more palatable for users of Perl's POD format, the core SDF code hasn't changed much since early 1996. Within Mincom, people have been using SDF on a daily basis for at least 4 or 5 years now.
      

      2.2. How many people are using SDF?
      

      At the moment (February 98), my guess is that SDF has 50-100 users within Mincom and a few hundred within other organisations. Excluding Mincom, SDF has active users within a large number of countries including Australia, Belgium, Canada, Denmark, England, Germany, France, Italy, New Zealand, Norway, Russia and the USA.
      

      2.3. What is SDF being used for?
      

      Within Mincom, SDF is used for a large number of purposes including:
      

        

      • The user documentation for Mincom's flagship product, MIMS Open Enterprise. This is a large documentation suite containing over 11,000 A4 pages and over 10,000 HTML topics with over 144,000 hypertext jumps. All of the hypertext is automatically generated, greatly reducing the maintenance cost of the online documentation.

      • All of the documents produced by the MIMS Technology Research (MTR) group within the last 3 years, i.e. a few hundred documents, and a Web-based project information system for all MTR projects. (The MTR group is the home of SDF.)

      • Embedded documentation within C and C++ code.

      • Documentation for Delphi components developed in-house.

      • Documentation for Perl modules developed in-house.

      • The documentation for SDF itself.
      

      Outside of Mincom, SDF is also used for many things including:
      


      
Note: If you are using SDF and would like to be mentioned above, send me some email.

      

      SDF can also be used to convert documentation in Perl's POD format to any output format supported by SDF. For example, the HTML produced by SDF for Perl's documentation is available at http://www.mincom.com/mtr/perl/catalog.html.
      

      2.4. What new developments are expected for SDF in the future?
      

      My current priorites are:
      

        

      1. Supporting existing SDF users (by email and bug fixes).

      2. Developing the next generation of SDF called SimpleDoc.
      

      The key objectives of SimpleDoc are:
      

        

      • upwards compatibility with SDF

      • a new architecture which supports:
          

        • multiple input parsers (SDF, XML and POD)

        • output formatters which are decoupled from the input format
        

      • Perl 5 modules

      • better performance

      • support for XML output (in addition to XML input)

      • support for HTML-Help output

      • support for Java-Help output

      • better LaTeX output.
      

      As always, my time is limited, so if one or more of the above features interests you, let me know so I can prioritise things accordingly.
      

      Further information on SimpleDoc is available on the web. The URL is http://www.mincom.com/mtr/simpledoc/.
      

      

      3. Output Formats
      

      3.1. What output formats does SDF directly support?
      

      HTML, plain text, POD, MIF (Maker Interchange Format), SGML, MIMS F6 help and MIMS HTX.
      

      When generating HTML, either a single document or a set of topics can be created.
      

      When generating MIF, either a single document or a FrameMaker book and set of chapters can be created.
      

      3.2. What output formats does SDF indirectly support?
      

      By using the pod2* programs provided with Perl 5, SDF can generate man pages, LaTeX files, PostScript and a few other formats.
      

      By using FrameMaker, SDF can indirectly generate PostScript, FrameViewer, RTF and other formats which FrameMaker can export. On Unix, most of these can be generated using FrameMaker's batch utility (fmbatch). On other platforms, it is necessary to generate a MIF file, open it in FrameMaker and print, save or export to the required format.
      

      By using SGML-Tools 1.02 or later, SDF can indirectly generate LaTeX, RTF, GNU Info and LyX formats. If LaTeX is also installed, SDF can indirectly generate PostScript and DVI.
      

      3.3. Why should I use SDF when my word processor can generate HTML?
      

      Unlike WYSIWYG tools, SDF encourages authors to specify documents in a logical manner. As a result, SDF has the semantics it needs to generate high quality paper-based and online documents.
      

      SDF also includes a number of features which greatly simplify the effort required to produce online documents. These include:
      

        

      • centralised hypertext management

      • rule-based hypertext generation.
      

      It could be a long time before word processors provide these features. As a result, it takes a lot less effort (and cost) to create and maintain a large online documentation system in SDF when compared to existing WYSIWYG tools (that I know about, at least).
      

      3.4. Can SDF generate Word documents?
      

      Not directly. However, SDF can generate RTF (Rich Text Format) files which can be opened in Word and many other word processors. The commands to convert a file called mydoc.sdf to RTF are:
      

         sdf -2rtf_mif  mydoc.sdf
   sdf -2rtf_fm   mydoc.sdf
   sdf -2rtf_sgml mydoc.sdf
   sdf -2rtf      mydoc.sdf

      

      The first of these works by generating a MIF (Maker Interchange Format) file and then converting it to RTF via a Perl script supplied with SDF called mif2rtf. The main problems with mif2rtf are:
      

        

      1. it is slow

      2. the output is not as great as one would hope for

      3. it occasionally crashes. :-(
      

      The second command works by generating a MIF file and then converting it to RTF via FrameMaker's RTF export filter. This approach is more reliable than using mif2rtf, although it has it own set of problems and limitations.
      

      The third command works by generating a SGML file and then uses SGML-Tools to generate RTF. I haven't tested SGML-Tools's RTF generation, so I have no idea how well this will work.
      

      The forth command is an alias for one of the commands above. See the FormatMapping section of the sdf.ini file to view and/or edit the mapping.
      

      Oneday, SDF will support RTF directly.
      

      3.5. Can SDF generate Windows help?
      

      SDF can generate RTF files and HPJ files which are the inputs to a Windows 3.x help compiler (e.g. hcp.exe).
      

      I haven't tried building help for Windows 95 or NT, so I'm not sure how well that works or otherwise. In any case, Microsoft is moving to HTML for online help, so I'm not overly motivated to improve the existing support for Windows help.
      

      3.6. Is FrameMaker needed for generating PostScript?
      

      No. SDF can generate PostScript via the freely available pod2ps program or the freely available SGML-Tools/LaTeX packages.
      

      However, if you have FrameMaker, using it currently has the following advantages:
      

        

      • the PostScript it generates looks better than that generated by most other packages (at the moment)

      • SDF currently supports FrameMaker better than other packages in some areas (e.g. indexes)

      • SDF has been tested with FrameMaker much more than other packages.
      

      Alternatively, SDF can be used to generate RTF which can then be imported into most word processors.
      

      

      4. Language Issues
      

      4.1. How do I enter an empty row in a table?
      

      TBL format ignores blanks lines, so to enter an empty line, you need to enter an empty cell like this:
      

      !block table
Big     Small
A       a
{{}}
B       b
!endblock

      

      The result is:
      

      

      

Big


Small


      

      

A


a


      

      

 


 


      

      

B


b


      

      


      4.2. How do I enter a multi-line cell in a table?
      

      By beginning a cell with a << symbol like this:
      

      !block table
Option  Description
-g      <<
        This option produces the following:

        !import "g_code"
>>
-v      verbose mode
!endblock

      

      
Note: 
      

        

      1. The cell is terminated by a >> symbol at the beginning of a line.

      2. You can place any SDF you like within the cell.

      3. Whitespace is generally ignored at the beginning of lines, so you can put the cell contents under its column heading if you want to.

      4. If the multi-line cell is not the last one within the row, you currently need to format the table using delimited format rather than fixed width format.
      

      

      

      

      

      Home | Catalog
      

      

      



dred within other organisations. Exsdf-2.001/doc/build010075500042570001753000000047010661610371200137140ustar00iancmtr00000400000236#!/usr/local/bin/perl5
#
# >>Title::     Build Documentation
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 30-Oct-98 ianc    Added local mode
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

use Cwd;
!require "sdf/name.pl";

# The root directory for documents
$DOC_ROOT = cwd();

# The formats to build for each document
%FMTS = (
    "paper/sdfintro",   ['pdf', 'html'],
    "quickref/qr_sdf",  ['pdf', 'html'],
    "user/ug_sdf",      ['book -zpdf', 'topics'],
    "guru/gg_sdf",      ['book -zpdf', 'topics'],
    "ref/re_sdf",       ['book -zpdf', 'topics'],
    "genhtml/index",    ['pdf', 'html'],
    "podusers/index",   ['pdf', 'html'],
    "release/rn_sdf",   ['pdf', 'topics'],
    "faq/faq",          ['pdf', 'html'],
);

# Symbolic names for sets of documents
%TAGS = (
    "all",      [sort keys %FMTS],
);

# Check the usage
unless (@ARGV) {
    print "usage: build all          - all the documents\n";
    print "       build list_of_docs - some documents\n";
    print "       build local        - just home & catalog for local use\n";
    exit 1;
}

# Check for local mode
if ($ARGV[0] eq 'local') {
    print "EXECUTING: sdf -2html -DLOCAL_DOCS home catalog\n";
    system("sdf -2html -DLOCAL_DOCS home catalog");
    exit();
}

# Generate the documents
while (defined($doc = shift(@ARGV))) {

    # Expand symbolic names
    if ($TAGS{$doc}) {
        unshift(@ARGV, @{$TAGS{$doc}});
        next;
    }

    # Get the formats to generate for this document
    @fmts = @{$FMTS{$doc}};
    unless (@fmts) {
        print "error: unknown document '$doc'\n";
        next;
    }

    # Change to the directory holding the document
    ($dir, $file) = &NameSplit($doc);
    chdir "$DOC_ROOT/$dir";
    print "CHANGED TO: ", `pwd`;

    # Generate the required outputs
    for $fmt (@fmts) {
        print "EXECUTING: sdf -2$fmt $file\n";
        system("sdf -2$fmt $file");
    }
}

# Update the home page, document catalog and INSTALL notes
chdir $DOC_ROOT;
print "CHANGED TO: ", `pwd`;
print "EXECUTING: sdf -2html home catalog\n";
system("sdf -2html home catalog");
print "EXECUTING: sdf -2txt -o- -csdf user/in_insta.sdf > ../INSTALL\n";
system("sdf -2txt -o- -csdf user/in_insta.sdf > ../INSTALL");
sdf-2.001/doc/sdflogo.bmp010064400042570001753000000015460622022217000150170ustar00iancmtr00000400000236BMfv( /ð„„ŒŒŒŒ” ”(º(©]®¥Ê¨çÁçáÖæïçï÷ç÷÷ï÷ç÷çÿ÷ÿÿÿÿîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîåîîîîîîîîîîîîîî {îîîîîîîîîîîîîîîîîîîîîîîîéà>îîîîîîîîîîîààîîîîîîîîîîîîîîîîîîîîîîîîîîãîîîîîîîîîîîàîîîîîîîîîîîîîàîîîîîîîîîîîà°îîîîîîîîîîî»îîîîîîîîîîîîîîîîîîîîîîîî]îîîîîîîîà¾îîîîîîîîîÞî~îîîîîîîîîâîîîîîîîîîàîîîîîîîîîàãîîîîîî¾î]àîîîîîî.îîàîîîîîîîàãîîîîîîâîàîÞîîîîîîîîîî.àîàîîîîîîîîîë^îîîîîîâ¾Wî^îîîîîîàîîîîîîîîîPà ã]îîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîpîîîîîîîîîîîîîîîîîîîîîîîîîîîîîæîîîîîîîîîîîîîîîƒÎîîîîîîîîîîîîîîä¾îîîîîîîîîîîîîîãÎîîîîîDDNäDDNìFÎîîîîîîLîLäLæLîDÎîîîîîîîìLäLîDÎDîîîîîîîìdLäLîä¼DÌîîîîîîÄD¾ÄLîäÎDDÎîîîîîDÌîäLîäÎDÎîîîîîîLîÎäLìDÎDîîîîîîæLäLäNäLîDÎNîîîîîDDNäDDîîDDNîîîîîîîîîîîîîîîîîîîîsdf-2.001/doc/podusers/004075500042570001753000000000000672243774100145465ustar00iancmtr00000400000236sdf-2.001/doc/podusers/index.html010064400042570001753000000500350672242271000165310ustar00iancmtr00000400000236






SDF 2.001: SDF for POD Users




      

      

      Home | Catalog
      

      

      

      

      

      SDF for POD Users
      

      Ian Clatworthy (ianc@mincom.com), Research Architect, Mincom Pty Ltd
      

      25 May 1999
      

      

      

      

      

      Table of Contents
      


      

      

      

      1. Overview
      

      Over the last few years, Perl's POD format has proven itself as a useful tool for documenting Perl's functionality and its library modules. POD is easy to learn, easy to read and easy to embed.
      

      In 1992, I wanted to embed documentation in source code in order to make it easier to keep the documentation up to date. POD didn't exist, so I invented a similar system called SDF (Simple Document Format) and implemented it in Perl, the world's greatest programming language. SDF has grown rapidly over the years and is now a powerful general purpose documentation system. But like POD, SDF has remained simple in spirit: easy to learn, easy to read and easy to embed.
      

      In June 1997, most of POD's syntax and functionality were merged into SDF, making it easier for people to migrate from POD to SDF. This document aims to answer the following questions for POD users:
      

        

      1. How do I convert from POD to SDF?

      2. How do I convert from SDF to POD?

      3. How do I nest SDF inside a POD document?

      4. How do I nest POD inside an SDF document?

      5. Is it hard to learn SDF?

      6. Is SDF more readable than POD?

      7. What does SDF offer me?

      8. What's wrong with SDF?
      

      If you have other questions, check out the documentation provided with SDF. If that doesn't help, you can always email your question to sdf-users@mincom.com.
      

      

      2. How do I convert from POD to SDF?
      

      By using the pod2sdf program. Typical usage is:
      

        pod2sdf perlrun.pod > perlrun.sdf

      

      As SDF is essentially a superset of POD, the SDF output is almost the same as the POD input, except that verbatim lines are marked with a leading >. For example, the following POD:
      

          =head1 NAME
    
    abc - output the alphabet
    
    =head1 DESCRIPTION
    
    This program displays the alphabet like this:
    
      ABCDEFGHIJ
      KLMNOPQRST
      UVWXYZ
    
    Pretty simple, eh?

      

      gets converted to:
      

          =head1 NAME
    
    abc - output the alphabet
    
    =head1 DESCRIPTION
    
    This program displays the alphabet like this:
    
    >  ABCDEFGHIJ
    >  KLMNOPQRST
    >  UVWXYZ
    
    Pretty simple, eh?

      

      Note that it isn't actually necessary to use pod2sdf unless you intend migrating to SDF format - the sdf program can be used on a POD file directly like this:
      

        sdf -2html perlrun.pod

      

      How does this work? Well, the sdf program can be configured to automatically prefilter files with certain extensions. The default configuration is to prefilter .pod, .pm and .PL files with the pod filter (which converts POD to SDF).
      

      If you want to use the sdf program on POD files without one of these extensions, you can either edit the sdf.ini configuration file, or explicitly specify the prefiltering like this:
      

        sdf -2html -ppod xyz.pd

      

      

      3. How do I convert from SDF to POD?
      

      By using the sdf program. Typical usage is:
      

        sdf -2pod mydoc.sdf

      

      This will create a file called mydoc.pod in the current directory.
      

      The general usage of the sdf program is:
      

        sdf [options] filename ...

      

      A .sdf extension is assumed on each filename (unless a filename without the extension is found).
      

      

      4. How do I nest SDF inside a POD document?
      

      If you're generally happy with POD and only need SDF occasionally, SDF can be embedded in POD using POD's =for command or =begin/=end command pair. Some examples are:
      

          Here's our new logo:

    =for sdf !import "mylogo.gif"

    And these are the documentation systems we use:

    =begin sdf

    !block table
    Name    Meaning
    POD     Plain Old Documentation
    SDF     Simple Document Format
    !endblock

    =end sdf

      

      If you want the rest of a POD file to be in SDF, simply put in an "=begin sdf" - the closing "=end sdf" isn't necessary.
      

      

      5. How do I nest POD inside an SDF document?
      

      By using the pod filter. Filters can be applied to blocks of text in a file, complete files or the output of programs. Some examples are:
      

          # Insert some pod
    !block pod
    =head2 My B<heading>

    A normal POD paragraph.

        And some verbatim text.
    !endblock

    # Get pod from a file
    !include "perlre.pod"; pod

    # Get pod from standard output
    !execute "getpod 'hello.c'"; pod

      

      So reusing existing POD documentation within an SDF document is easy.
      

      

      6. Is it hard to learn SDF?
      

      No. 90% of SDF documents use a set of core features which can be summarised in a few pages. For POD users, the main things to know are these:
      

        

      • Leading whitespace is generally ignored in SDF. So, verbatim lines need to be explicitly marked using a > tag, or enclosed within "!block verbatim" and "!endblock".

      • Commands in POD are called macros in SDF. Macros can be called using the same syntax as POD, i.e. an = at the start of a line starts a macro call which terminates at the next blank line. All of POD's commands are available as macros in SDF.

      • Interior sequences in POD are called phrases in SDF. Phrases can be called using the same [A-Z]<..> syntax as POD. All of POD's interior sequences are available as POD phrases.

      • Normal paragraphs in SDF are the same as normal paragraphs in POD, except that paragraphs can be optionally tagged with a paragraph style and/or paragraph attributes. The general syntax is:
      

            style":" text

      

        
or
      

            style"["attributes"]" text

      

        
Some examples are:
      

          A normal paragraph with
    a few lines.

    Note: This is a paragraph tagged with
    the Note style.

    Note[label='Important'] This is an important note!

      

        

      • Except for lines within a multi-line macro call or a block/endblock macro pair, each line may begin a new paragraph or macro. So, if you have a special character or pattern at the start of a line, you will need to escape it by placing a backslash character (\) before it.

      • To maximise convenience and readability, list items can be tagged using the special characters below:

        

        

Tag


Meaning


        

        

*


bulleted list item


        

        

-


2nd-level bulleted list item


        

        

.


plain list item/paragraph


        

        

^


first item in an ordered list


        

        

+


next item in an ordered list


        

        

&


enumerated list item


        

        


        
For example, a simple bulleted list is shown below.
      

           * item 1
       - item 1a
       - item 1b
     * item 2
     * item3

      

        
Of course, you can always use the over/item/back macros if you prefer them.
      

      

      7. Is SDF more readable than POD?
      

      To its fans, SDF is more readable than POD for the following reasons:
      

        

      • simple lists look like lists (which is quite important for embedded documentation masquerading as comments)

      • a single line macro syntax is available (!-style), making SDF documents less whitespace intensive

      • leading whitespace doesn't imply verbatim, so nested things can look nested

      • multi-character phrase styles can be used, e.g. {{DOC: SDF for POD Users}}, making the document source more readable

      • within {{ style phrases, > doesn't need to be escaped unless a [A-Z]<> phrase is nested, so certain code examples are more readable, e.g. {{C:$arrayref->[0]}}.
      

      Of course, POD's fans argue that POD is more readable for equally valid reasons. Beauty is in the eye of the beholder - even Lisp has it's fans. :-)
      

      

      8. What does SDF offer me?
      

      The main reasons for using SDF over POD are:
      

        

      1. Tables

      2. Figures

      3. Variables

      4. Better Extensibility

      5. Configurable Expansion of Links
      

      These are briefly considered below.
      

      
Note: Not every output format supported by SDF supports every table/figure feature. In some cases, the SDF -> xxx format driver isn't yet clever enough. In other cases, the target format isn't clever enough! So, your milage may vary with some of these features, particularly in the short term as the SDF format drivers are maturing. Of course, the Perl source code for each format driver is provided with the SDF package, so feel free to improve them.

      

      8.1. Tables
      

      SDF support tables via the table filter. Typically, tables are defined using the block and endblock macros like this:
      

      !block table
Name    Meaning
POD     Plain Old Documentation
SDF     Simple Document Format
!endblock

      

      The result is:
      

      

      

Name


Meaning


      

      

POD


Plain Old Documentation


      

      

SDF


Simple Document Format


      

      


      The first line specifies the headings and the input format of the data:
      

        

      • if the first two field names are separated by whitespace, the input format is assumed to be fixed-width

      • otherwise, the input format is assumed to be "delimited" and the special character separating the first two fields is the delimiter.
      

      For readability reasons, fixed-width format is preferred. Delimited format is useful for tables already in that format and for data exported by spreadsheets.
      

      SDF supports a large number of features for tables including:
      

        

      • column widths can be dynamically sized or explicitly set

      • heading, footing and group rows can be specified

      • table alignment and positioning can be controlled

      • cells support custom alignment, shading, ruling and colours.
      

      See the SDF User Guide for further details.
      

      8.2. Figures
      

      Figures are supported in SDF via the import macro. The usage is:
      

        !import "filename" [parameters]

      

      For example:
      

        !import "mylogo"; align=Right

      

      It is generally best not to specify an extension for the filename containing the figure, as SDF will then use the best format it can find. The search rules are:
      

      

      

When generating


The search order is


      

      

PostScript


epsi, eps, wmf, mif, gif


      

      

HTML


jpeg, jpg, png, gif


      

      

Windows Help


bmp


      

      


      See the SDF User Guide for further details.
      

      8.3. Variables
      

      Variables can be defined using the define macro like this:
      

        !define VERSION 1.34

      

      The first argument is the variable name and the second argument is the value. You can use a Perl expression for the value if you wish. For example:
      

        !define LOGO $ENV{'LOGO'} || "mylogo"

      

      Having defined a variable, it can be used in paragraph text by enclosing it within [[ and ]]. For example:
      

        WorldPeace [[VERSION]] is just what you need and
  is available for free download from ...

      

      In fact, a Perl expression can be embedded in paragraph text the same way, e.g.
      

        !define STARS 5
  ...
  This movie gets [['*' x $var{'STARS'}]].

      

      Within Perl expressions, SDF variables are available via the %var associative array.
      

      8.4. Better Extensibility
      

      From its beginning, one of SDF's primary goals has been to support the authoring of documents in a logical manner. Therefore, it is possible to define your own:
      

        

      • paragraph styles

      • paragraph attributes

      • phrase styles

      • phrase attributes
      

      and to either alias these to existing styles/attributes or map them to target format entities.
      

      Likewise, you can define your own macros and filters to do almost anything you want. See the SDF Guru Guide for further details.
      

      Typically, a workgroup or project team will put their extensions in an SDF library, which is essentially a normal SDF file which is included at the start of each document. Alternatively, you can specify a configuration library on the sdf command line. This is useful if you want an SDF configuration library for a POD document, say.
      

      8.5. Configurable Expansion of Links
      

      For L (Link) phrases, SDF lets you customise:
      

        

      • the rules for expanding the text

      • the HTML URL searching/generation rule
      

      This flexibility is important for non-English documentation and non-Perl documentation.
      

      To change the text expansion rules, define one of more of the variables below:
      

      

      

Variable


Default Value


      

      

FORMAT_LINK_PAGE


the $page manpage


      

      

FORMAT_LINK_PAGE_ENTRY


the $entry entry in the $page manpage


      

      

FORMAT_LINK_PAGE_SECTION


the section on "$sect" in the $page manpage


      

      

FORMAT_LINK_SECTION


the section on "$sect"


      

      


      For example:
      

        !define FORMAT_LINK_SECTION 'the "$sect" section'

      

      To change the URL generation rule, override the BuildLinkUrl subroutine like this:
      

      !block script
sub BuildLinkUrl  {
    my ($page, $sect, $entry) = @_;
    my $url = ...
    return $url;
}
!endblock

      

      The default implementation of BuildLinkUrl is simplistic by design. This is considered a feature. If you want intelligent URL generation ala pod2html, use the perl configuration library and set the PERL_HTML_ROOT variable like this:
      

        sdf -2html -cperl -DPERL_HTML_ROOT=/nmanual/perl perlrun.pod

      

      The default value of PERL_HTML_ROOT is /perl.
      

      

      9. What's wrong with SDF?
      

      The most common complaints about SDF are:
      

        

      1. It isn't WYSIWYG.

      2. It doesn't support the output format I need.

      3. It doesn't have the features I need.

      4. It has too much functionality.
      

      On the WYSIWYG issue, SDF is a tool for people who would rather use a text editor. It tries hard to be readable and an emacs mode is available. If that isn't good enough, then SDF isn't for you.
      

      On the output format issue, I'm working on it. For developers with a good knowledge of Perl and the output format they need, writing an "SDF output driver" isn't hard, it just takes time. Like all of us, I only have so much free time, so any assistance anyone can offer in this regard is very welcome.
      

      On the functionality issue, SDF is growing and will continue growing. If it doesn't have a feature you need, the Perl source code is provided, so you might be able to add it yourself.
      

      If SDF is already too complex, then stick with POD. You can always mix in some SDF or migrate to SDF if you need to at a later date. Personally, I find the "I'm sticking with POD because SDF is too complex" argument a little short-sighted:
      

        

      • SDF's basic ideas (styles, attributes, macros, filters and variables) and commonly used tags are easy to learn

      • I'd rather use the same markup language for embedded documentation, memos, design documents and user documentation.
      

      I prefer SDF to POD for the same reason that I prefer Perl to awk: the latter may be sufficent for a given task, but choosing it will cause me grief the moment the task grows. On the other hand, as the designer of SDF, I'm probably just a little biased. :-)
      

      

      10. Credits
      

      Thanks to the many people who have used and contributed to SDF over the years, particularly David Cox, Tim Hudson and Chris Moran. Likewise, thanks to Larry Wall for inventing Perl and to everyone who has contributed to Perl over the years. Without it, SDF wouldn't exist.
      

      Finally, I'd like to thank the people who encouraged me to merge POD and SDF, including Kenneth Albanowski, Brad Appleton, Achim Bohnet, Jim Esten, Chaim Frenkel, Gerd Knops, Hugues Lafarge, Tuomas J. Lukka, Andy Wardley and Peter Wolfe. I hope the result is useful.
      

      

      

      

      Home | Catalog
      

      

      




    • simple lists look like lists (which is quite important for embedded documentation masquerading as comments)

    • a single line macro syntax is available (!-style), making SDF documents less whitespace intensive

    • leading whitespace doesn't imply verbatim, so nested things can look nested

    • multi-character phrase styles can be used, e.g. {{DOC: SDF for POD Users}}, making the document source more readable

    • within {{ style phrases, > doesn't need to be escaped unless sdf-2.001/doc/podusers/index.sdf010064400042570001753000000363400672242001600163410ustar00iancmtr00000400000236!init OPT_CONFIG="sdf"; OPT_STYLE="paper"; SDF_ROOT="../"
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 20-Jun-97 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

# Build the title
!define DOC_NAME     "SDF for POD Users"
!define DOC_AUTHOR   "Ian Clatworthy ({{EMAIL:ianc@mincom.com}}), Research Architect, {{ORG[expand]Mincom}}"
!build_title

H1: Overview

Over the last few years, Perl's POD format has proven itself as
a useful tool for documenting Perl's functionality and its
library modules. POD is easy to learn, easy to read and easy
to embed.

In 1992, I wanted to embed documentation in source code in order
to make it easier to keep the documentation up to date.
POD didn't exist, so I invented a similar system called
SDF (Simple Document Format) and implemented it in Perl,
the world's greatest programming language.
SDF has grown rapidly over the years and is
now a powerful general purpose documentation system.
But like POD, SDF has remained simple in spirit: easy to learn,
easy to read and easy to embed.

In June 1997, most of POD's syntax and functionality were merged into
SDF, making it easier for people to migrate from POD to SDF.
This document aims to answer the following questions for POD users:

!block sections
^ How do I convert from POD to SDF?
+ How do I convert from SDF to POD?
+ How do I nest SDF inside a POD document?
+ How do I nest POD inside an SDF document?
+ Is it hard to learn SDF?
+ Is SDF more readable than POD?
+ What does SDF offer me?
+ What's wrong with SDF?
!endblock

If you have other questions, check out the documentation provided
with SDF. If that doesn't help, you can always email your question
to {{EMAIL:sdf-users@mincom.com}}.

H1: How do I convert from POD to SDF?

By using the {{CMD:pod2sdf}} program. Typical usage is:

>  pod2sdf perlrun.pod > perlrun.sdf

As SDF is essentially a superset of POD, the SDF output
is almost the same as the POD input, except that verbatim lines
are marked with a leading >. For example, the following POD:

#!block box
!block example; listitem
=head1 NAME

abc - output the alphabet

=head1 DESCRIPTION

This program displays the alphabet like this:

  ABCDEFGHIJ
  KLMNOPQRST
  UVWXYZ

Pretty simple, eh?
!endblock
#!endblock

gets converted to:

#!block box
!block example; listitem
=head1 NAME

abc - output the alphabet

=head1 DESCRIPTION

This program displays the alphabet like this:

>  ABCDEFGHIJ
>  KLMNOPQRST
>  UVWXYZ

Pretty simple, eh?
!endblock
#!endblock

Note that it isn't actually necessary to use {{CMD:pod2sdf}}
unless you intend migrating to SDF format - the {{CMD:sdf}}
program can be used on a POD file directly like this:

>  sdf -2html perlrun.pod

How does this work? Well, the {{CMD:sdf}} program can be
configured to automatically {{prefilter}} files with
certain extensions. The default configuration is to
prefilter {{.pod}}, {{.pm}} and {{.PL}} files with the
{{FILT:pod}} filter (which converts POD to SDF).

If you want to use the {{CMD:sdf}} program on POD files
without one of these extensions, you can either edit the
F configuration file, or explicitly specify
the prefiltering like this:

>  sdf -2html -ppod xyz.pd


H1: How do I convert from SDF to POD?

By using the {{CMD:sdf}} program. Typical usage is:

>  sdf -2pod mydoc.sdf

This will create a file called F in the current directory.

The general usage of the sdf program is:

>  sdf [options] filename ...

A {{.sdf}} extension is assumed on each filename (unless a filename
without the extension is found).


H1: How do I nest SDF inside a POD document?

If you're generally happy with POD and only need SDF occasionally,
SDF can be embedded in POD using POD's =for command or =begin/=end
command pair. Some examples are:

!block example
    Here's our new logo:
  
    =for sdf !import "mylogo.gif"
  
    And these are the documentation systems we use:
  
    =begin sdf
  
    !block table
    Name    Meaning
    POD     Plain Old Documentation
    SDF     Simple Document Format
    !endblock
  
    =end sdf
!endblock

If you want the rest of a POD file to be in SDF, simply put
in an "=begin sdf" - the closing "=end sdf" isn't necessary.


H1: How do I nest POD inside an SDF document?

By using the {{FILT:pod}} filter. Filters can be applied to
blocks of text in a file, complete files or the output
of programs. Some examples are:

!block example; lang='sdf'
    # Insert some pod
    !block pod
    =head2 My B

    A normal POD paragraph.

        And some verbatim text.
    !endblock

    # Get pod from a file
    !include "perlre.pod"; pod

    # Get pod from standard output
    !execute "getpod 'hello.c'"; pod
!endblock

So reusing existing POD documentation within an SDF document
is easy.


H1: Is it hard to learn SDF?

No. 90% of SDF documents use a set of core features which can
be summarised in a few pages. For POD users, the main things
to know are these:

* Leading whitespace is generally ignored in SDF. So, verbatim
  lines need to be explicitly marked using a > tag, or
  enclosed within "!block verbatim" and "!endblock".

* Commands in POD are called {{macros}} in SDF.
  Macros can be called using the same syntax as POD, i.e.
  an = at the start of a line starts a macro call which
  terminates at the next blank line. All of POD's commands
  are available as macros in SDF.

* Interior sequences in POD are called {{phrases}} in SDF.
  Phrases can be called using the same [A-Z]<..> syntax as POD.
  All of POD's interior sequences are available as POD phrases.

* Normal paragraphs in SDF are the same as normal paragraphs
  in POD, except that paragraphs can be optionally tagged with
  a {{paragraph style}} and/or {{paragraph attributes}}.
  The general syntax is:

>      style":" text

. or

>      style"["attributes"]" text

. Some examples are:

!block example
    A normal paragraph with
    a few lines.

    Note: This is a paragraph tagged with
    the Note style.

    Note[label='Important'] This is an important note!
!endblock

* Except for lines within a multi-line macro call or
  a {{MAC:block}}/{{MAC:endblock}} macro pair, each line may
  begin a new paragraph or macro.
  So, if you have a special character or pattern at the start
  of a line, you will need to escape it by placing a
  backslash character (\) before it.

* To maximise convenience and readability, list items can be
  tagged using the special characters below:

!block table; listitem; narrow
Tag     Meaning
*       bulleted list item
-       2nd-level bulleted list item
.       plain list item/paragraph
^       first item in an ordered list
+       next item in an ordered list
&       enumerated list item
!endblock

. For example, a simple bulleted list is shown below.

!block example
     * item 1
       - item 1a
       - item 1b
     * item 2
     * item3
!endblock

. Of course, you can always use the over/item/back macros
  if you prefer them.


H1: Is SDF more readable than POD?

To its fans, SDF is more readable than POD
for the following reasons:

* simple lists look like lists (which is quite important for
  embedded documentation masquerading as comments)

* a single line macro syntax is available (!-style), making
  SDF documents less whitespace intensive

* leading whitespace doesn't imply verbatim,
  so nested things can look nested

* multi-character phrase styles can be used,
  e.g. E<2{>DOC: SDF for POD UsersE<2}>,
  making the document source more readable

* within E<2{> style phrases, > doesn't need to be escaped
  unless a [A-Z]<> phrase is nested, so certain code examples
  are more readable, e.g. E<2{>C:$arrayref->[0]E<2}>.

Of course, POD's fans argue that
POD is more readable for equally valid reasons.
Beauty is in the eye of the beholder - even
Lisp has it's fans. :-)


H1: What does SDF offer me?

The main reasons for using SDF over POD are:

!block sections
^ Tables
+ Figures
+ Variables
+ Better Extensibility
+ Configurable Expansion of Links
!endblock

These are briefly considered below.

Note: Not every output format supported by SDF
supports every table/figure feature. In some cases, the SDF -> xxx
format driver isn't yet clever enough. In other cases,
the target format isn't clever enough! So, your milage
may vary with some of these features, particularly in the short
term as the SDF format drivers are maturing. Of course,
the Perl source code for each format driver is provided
with the SDF package, so feel free to improve them.


H2: Tables

SDF support tables via the {{table}} filter. Typically,
tables are defined using the {{MAC:block}}
and {{MAC:endblock}} macros like this:

!block example
!block table
Name    Meaning
POD     Plain Old Documentation
SDF     Simple Document Format
!endblock
!endblock

The result is:

!block table
Name    Meaning
POD     Plain Old Documentation
SDF     Simple Document Format
!endblock

The first line specifies the headings and the input
format of the data:

* if the first two field names are separated by whitespace,
  the input format is assumed to be fixed-width
* otherwise, the input format is assumed to be "delimited"
  and the special character separating the first two fields
  is the delimiter.

For readability reasons, fixed-width format is preferred.
Delimited format is useful for tables already in that
format and for data exported by spreadsheets.

SDF supports a large number of features for tables including:

* column widths can be dynamically sized or explicitly set
* heading, footing and group rows can be specified
* table alignment and positioning can be controlled
* cells support custom alignment, shading, ruling and colours.

See the {{DOC: SDF User Guide}} for further details.


H2: Figures

Figures are supported in SDF via the {{MAC:import}} macro.
The usage is:

>  !import "filename" [parameters]

For example:

>  !import "mylogo"; align=Right

It is generally best {{not}} to specify an extension for the filename
containing the figure, as SDF will then use the best format it can find.
The search rules are:

!block table; narrow
When_generating     The_search_order_is
PostScript          epsi, eps, wmf, mif, gif
HTML                jpeg, jpg, png, gif
Windows Help        bmp
!endblock

See the {{DOC: SDF User Guide}} for further details.


H2: Variables

Variables can be defined using the {{MAC:define}} macro
like this:

>  !define VERSION 1.34

The first argument is the variable name and the second argument
is the value. You can use a Perl expression for the value if
you wish. For example:

>  !define LOGO $ENV{'LOGO'} || "mylogo"

Having defined a variable, it can be used in paragraph text by
enclosing it within E<2[> and E<2]>. For example:

>  WorldPeace [[VERSION]] is just what you need and
>  is available for free download from ...

In fact, a Perl expression can be embedded in paragraph text the
same way, e.g.

>  !define STARS 5
>  ...
>  This movie gets [['*' x $var{'STARS'}]].

Within Perl expressions, SDF variables are available via
the %var associative array.


H2: Better Extensibility

From its beginning, one of SDF's primary goals has been
to support the authoring of documents in a logical manner.
Therefore, it is possible to define your own:

* paragraph styles
* paragraph attributes
* phrase styles
* phrase attributes

and to either alias these to existing styles/attributes
or map them to target format entities.

Likewise, you can define your own macros and filters
to do almost anything you want. See the
{{DOC:SDF Guru Guide}} for further details.

Typically, a workgroup or project team will
put their extensions in an SDF library, which is
essentially a normal SDF file which is included at
the start of each document. Alternatively, you can specify
a configuration library on the {{CMD:sdf}} command line.
This is useful if you want an SDF configuration library
for a POD document, say.

H2: Configurable Expansion of Links

For L (Link) phrases, SDF lets you customise:

* the rules for expanding the text
* the HTML URL searching/generation rule

This flexibility is important for non-English documentation
and non-Perl documentation.

To change the text expansion rules, define one of
more of the variables below:

!block table
Variable                  Default_Value
FORMAT_LINK_PAGE          the $page manpage
FORMAT_LINK_PAGE_ENTRY    the $entry entry in the $page manpage
FORMAT_LINK_PAGE_SECTION  the section on "$sect" in the $page manpage
FORMAT_LINK_SECTION       the section on "$sect"
!endblock

For example:

>  !define FORMAT_LINK_SECTION 'the "$sect" section'

To change the URL generation rule, override the {{BuildLinkUrl}}
subroutine like this:

!block example
!block script
sub BuildLinkUrl  {
    my ($page, $sect, $entry) = @_;
    my $url = ...
    return $url;
}
!endblock
!endblock

The default implementation of {{BuildLinkUrl}} is simplistic by design.
This is considered a feature.
If you want intelligent URL generation ala {{B:pod2html}}, use the
{{perl}} configuration library and set the PERL_HTML_ROOT variable
like this:

>  sdf -2html -cperl -DPERL_HTML_ROOT=/nmanual/perl perlrun.pod

The default value of PERL_HTML_ROOT is /perl.


H1: What's wrong with SDF?

The most common complaints about SDF are:

^ It isn't WYSIWYG.
+ It doesn't support the output format I need.
+ It doesn't have the features I need.
+ It has too much functionality.

On the WYSIWYG issue, SDF is a tool for people who would rather
use a text editor. It tries hard to be readable and an emacs
mode is available. If that isn't good enough, then SDF isn't
for you.

On the output format issue, I'm working on it.
For developers with a good knowledge of Perl and
the output format they need, writing an "SDF output driver"
isn't hard, it just takes time. Like all of us,
I only have so much free time, so any assistance
anyone can offer in this regard is very welcome.

On the functionality issue, SDF is growing and will
continue growing. If it doesn't have a feature you need,
the Perl source code is provided, so you might be able
to add it yourself.

If SDF is already too complex, then stick with POD.
You can always mix in some SDF or migrate to SDF
if you need to at a later date. Personally, I find
the "I'm sticking with POD because SDF is too complex"
argument a little short-sighted:

* SDF's basic ideas (styles, attributes, macros, filters and variables)
  and commonly used tags are easy to learn
* I'd rather use the same markup language for embedded documentation,
  memos, design documents and user documentation.

I prefer SDF to POD for the same reason that I prefer [[Perl]] to awk:
the latter may be sufficent for a given task, but choosing it will
cause me grief the moment the task grows. On the other hand,
as the designer of SDF, I'm probably just a little biased. :-)


H1: Credits

Thanks to the many people who have used and
contributed to SDF over the years, particularly
David Cox, Tim Hudson and Chris Moran.
Likewise, thanks to Larry Wall for inventing Perl
and to everyone who has contributed to Perl over the years.
Without it, SDF wouldn't exist.

Finally, I'd like to thank the people who encouraged
me to merge POD and SDF, including Kenneth Albanowski,
Brad Appleton, Achim Bohnet, Jim Esten, Chaim Frenkel,
Gerd Knops, Hugues Lafarge, Tuomas J. Lukka, Andy Wardley
and Peter Wolfe. I hope the result is useful.
block".

* Commands in POD are called {{macros}} in SDF.
  Macros can be called using the same syntax as POD, i.e.
  an = at the start of a line starts a macro call which
  terminates at the next blank line. All of POD's commands
  are available as macros in SDF.

* Interior sequences insdf-2.001/doc/sdflogo.gif010064400042570001753000000025360632066177200150260ustar00iancmtr00000400000236GIF89a(=÷3f™Ìÿ3333f3™3Ì3ÿff3fff™fÌfÿ™™3™f™™™Ì™ÿÌÌ3ÌfÌ™ÌÌÌÿÿÿ3ÿfÿ™ÿÌÿÿ3333f3™3Ì3ÿ3333333f33™33Ì33ÿf3f33f3ff3™f3Ìf3ÿ™3™33™3f™3™™3Ì™3ÿÌ3Ì33Ì3fÌ3™Ì3ÌÌ3ÿÿ3ÿ33ÿ3fÿ3™ÿ3Ìÿ3ÿff3fff™fÌfÿ3f3f33ff3f™3fÌ3fÿffff3fffff™ffÌffÿ™f™f3™ff™f™™fÌ™fÿÌfÌf3ÌffÌf™ÌfÌÌfÿÿfÿf3ÿffÿf™ÿfÌÿfÿ™™3™f™™™Ì™ÿ3™3™33™f3™™3™Ì3™ÿf™f™3f™ff™™f™Ìf™ÿ™™™™3™™f™™™™™Ì™™ÿ̙̙3Ì™fÌ™™Ì™ÌÌ™ÿÿ™ÿ™3ÿ™fÿ™™ÿ™Ìÿ™ÿÌÌ3ÌfÌ™ÌÌÌÿ3Ì3Ì33Ìf3Ì™3ÌÌ3ÌÿfÌfÌ3fÌffÌ™fÌÌfÌÿ™Ì™Ì3™Ìf™Ì™™ÌÌ™ÌÿÌÌÌÌ3ÌÌfÌÌ™ÌÌÌÌÌÿÿÌÿÌ3ÿÌfÿÌ™ÿÌÌÿÌÿÿÿ3ÿfÿ™ÿÌÿÿ3ÿ3ÿ33ÿf3ÿ™3ÿÌ3ÿÿfÿfÿ3fÿffÿ™fÿÌfÿÿ™ÿ™ÿ3™ÿf™ÿ™™ÿÌ™ÿÿÌÿÌÿ3ÌÿfÌÿ™ÌÿÌÌÿÿÿÿÿÿ3ÿÿfÿÿ™ÿÿÌÿÿÿ,(=ÿ¯]SE¥ ª\XP C…#^D…•ÀU9depcÁ„ÿttHŠH!=éðŠŠ)6|xÍ H‡€V­œ¹ófɃ4Z|¨Ò!K£=jü²ìw
~èž@ê57Fï!ˆ‡Ø_ƒÃÉà5¦M"7!zõÉ’¡~׈7T‡ÃÝçÞ!¢¹WŸŠè‘8܃¨‰'Ðîá€Z‡8Ò+6èŠñá¸"Šzˆ^ð!‚_}îéG£pF¦'+^ƒÈ(#pBy Tn,^#i’ˆ%âGžo4ÒWšœZ.ù¥pè¥ùà‡ÔŸ…î͇‹²lé b9&u0öiŸzUúw݃k
šç”’aчªá~H>º‘¬°) †+²òCŸ¬Cé5¦) ,A_?X¤ë©£Vº§wŠã°Úýºªƒ1:h¦€*æÐ¥©Ë
9jµÌ¦‡ì~‘R ¶ü-i«C];sdf-2.001/doc/notes/004075500042570001753000000000000672243772700140365ustar00iancmtr00000400000236sdf-2.001/doc/notes/latex.notes010064400042570001753000000066160671767426300162350ustar00iancmtr00000400000236
From valerio@publinet.it Mon May 17 12:02:27 1999
Date: Fri, 30 Oct 1998 16:43:22 +0100 (MET)
From: Valerio Aimale 
To: sdf-users@mincom.com
Subject: Latex driver for SDF 2.0


Hi, everyone!

In the past months I have developed a LaTeX  output driver for SDF
2.0; it isn't yet finished, but I would greatly appreciate if some of
you would take the time to beta-test it.

The general idea is to add another level of "metaness" to the SDF
system: ie the LaTeX driver does not output a LaTeX document, but actually a 
family of documents.

The driver,in fact, outputs only the body of a document, leaving 
to the user the chance to decide the "look and feel" of the final
typeset 

The file

--------------------------------
!define DOC_NAME           "GalaxyBuilder"
!define DOC_TYPE           "Discussion Paper"
!define DOC_AUTHOR         "Joe Bloggs"
!build_title
 
H1: Introduction

After extensive market research, I believe there is
an excellent opportunity for us to develop software
for the I. Potential
customers include:

* NASA
* European Community
* China
* Japan.
--------------------------

get translated to:

--------------------------
\author{Joe Bloggs}
\title{GalaxyBuilder}


\begin{document}

\maketitle

\chapter{Introduction}


After extensive market research, I believe there is an excellent
opportunity for us to develop software for the {\textit{galaxy
construction industry}}. Potential customers include:

\begin{itemize} % Level 1
\item NASA

\item European Community

\item China

\item Japan.


\end{itemize}


\end{document}
--------------------------

As you can see, the file actually cannot be used with LaTeX, you have
to add the preamble. Now if you want that ugly looking default article 
style, you should prepare a wrapper file like this (assuming that the
original file was called test.sdf, and test.tex the LaTeX driver
translated file):

-----------
\documentclass{article}

\input test.tex
-----------

and typeset it with LaTeX 2e (sorry no support for LaTeX 2.09).

Should you prefer a more interesting look, you could prepare a wrapper 
like this:

-----------
\documentclass[a4paper,12pt]{article}
\usepackage{times,geometry,titlesec}
\geometry{headheight=1.5in, bottom=.5in, footskip=0in}
\usepackage[american]{babel}
\usepackage{fancyhdr}
\pagestyle{fancy}
\rhead{\textit{Page: \thepage}}
\lhead{A much beautiful document}
\cfoot{}
\newcommand{\secformat}[1]{#1\titleline{\hrulefill}}
\titleformat{\section}[block]{\normalfont\sffamily\slshape\large}{\thesection.}
{0in}{\secformat}
\input test.tex
----------

The output will be dramatically different........

BTW, I think that in the future the SDF language should care only about
markup, leaving to the drivers the management of page layout: but it's only 
my $0.02

The LaTeX driver handles Tables (Column dimension decided by the
driver itself, no way to have a fixed width column}; it cannot
currently handle figures.

It is probably full of bugs, use it at your own risk!

It's available in my home page http://svpop.com.dist.unige.it/~valerio/

The drivers consists of the files that you have to copy over the
original one: latex.sdn, sdf.ini  and tolatex.pl

When the driver will be enough stable, will become part of the
official SDF distribution.

I would ask anyone who use this driver, to send me bug reports, in
order to speed up its evolution and insertion in the official
distribution.

Bye,

Valreio



sdf-2.001/doc/quickref/004075500042570001753000000000000672243773500145165ustar00iancmtr00000400000236sdf-2.001/doc/quickref/qr_sdf.sdf010075500042570001753000001435540672212627300164760ustar00iancmtr00000400000236# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1998, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 24-May-99 ianc    Minor updates for 2.001
# 16-Oct-98 ianc    Improve feature coverage
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# To do:
# * indexing rules
# * expressions & spreadsheet functions
# * parameters for command-line options?
# * syntax information?
# * macro parameters?
#


# Load the configuration
!define SDF_ROOT "../"
!inherit "sdf"

# Define variables
!define DOC_NAME    "SDF"
!define DOC_TYPE    "Quick Reference"
!define DOC_TOC     2
!define DOC_AUTHOR  "Ian Clatworthy"

# Build the title page
!build_title

# Make everything wide
!on paragraph '';; $attr{'wide'} = 1
!on table '';; $param{'wide'} = 1

# Change the default look of tables for paper
!if $var{'OPT_TARGET'} eq 'ps'
!define DEFAULT_TABLE_STYLE 'plain'
!endif

H1: SDF - The Package

H2: Programs

!block table
Name      Purpose
sdf       convert [[SDF]] files to other formats
sdfapi    extract the {{Application Programming Interface}} from source code
sdfbatch  generate [[FrameMaker]] batch files
sdfcli    extract the {{Command Line Interface}} from a utility
sdfget    extract documentation embedded in source code
sdftest   execute SDF regression tests
sdngen    build an SDF tuning module from a FrameMaker template
fm2ps     convert FrameMaker files to PostScript (a wrapper for {{CMD:sdfbatch}})
pod2sdf   convert POD to SDF
poddiff   compare POD files and report differences
prn2ps    convert Windows PostScript to Unix PostScript
!endblock

Environment variables used are:

!block table
Name            Description
SDFBIN          on MS-DOS/Windows systems, the directory containing SDF's scripts, \
                (e.g. c:\sdf\bin\)
SDFOPTS         options always used by {{CMD:sdf}} (e.g. -Yc:\mysdflib)
!endblock

H2: File Extension Conventions

!block table; headings; wrap=2; format='10,12,28,10,12,28'
A       B       C
Ext.    Format  Usage
ini     INI     configuration file
sde     SDF     SDF end module
sdf     SDF     normal SDF file
sdg     SDG     {{CMD:sdfget}} report
sdl     SDF     SDF locale
sdm     SDF     SDF module
sdn     SDF     SDF tuning module
sdo     TBL     SDF object register
sdp     Perl    SDF plug-in
sdr     Perl    SDF report
sds     SDF     SDF style module
sdt     HTML    SDF template
!endblock

H1[nopb] sdf - The Program

H2: Command-line Options

!block table
Option          Long_name       Description
-2              --format        the output format you want
-a              --parameters    parameters for the pre-filter
-c              --config        configuration library
-d              --driver        format driver - default is expand
-f              --flag          define flags (flag xxx maps to variable DOC_XXX)
-g              --get_report    prefilter using sdfget with the report specified
-h              --help          display help on options or a single option
-k              --look          look library
-l              --log_ext       log file extension (default is log)
-n              --split_level   heading level to autosplit into topics
-o              --out_ext       output file extension (default is out)
-p              --prefilter     pre-filter input file from each argument
-r              --report        report to pre-filter the input with
-s              --style         style of document
-t              --target        logical target format
-u              --uses          modules to use
-v              --verbose       verbose mode
-w              --width         width for text-based outputs
-y              --post_filter   filter to post-filter the output with
-z              --post_process  list of post processing actions to do
-D              --variable      define variables
-H              --head_level    initial heading level
-I              --include_path  search path for include files, templates, etc.
-K              --head_look     heading look (H, A or P)
-L              --locale        locale
-N              --line_numbers  number lines in pretty-printed source code
-O              --out_dir       output to input file's (or explicit) directory
-P              --plang         pre-filter as a programming language
-S              --page_size     page size for paper documents
-T              --trace_levels  debugging trace levels
-Y              --library_path  path to search for libraries and modules
!endblock

H2: Useful Command Lines

[keep_next]Generate format xxx for mydoc.sdf:

>       sdf -2xxx mydoc

[keep_next]Generate PDF via a FrameMaker book (on Unix):

>       sdf -2book -zpdf mydoc

[keep_next]Generate a man page:

>       sdf -2man mydoc | nroff -man > mydoc.1

[keep_next]Spell check a document:

>       sdf mydoc | spell

[keep_next]Pretty-print lang source code in format xxx:

>       sdf -2xxx -Plang mysource
>       sdf -2xxx -P mysource.lang
>       sdf -2xxx -P -N5 mysource.lang   (with line numbering)

[keep_next]Generate reference documentation in format xxx for mymod.sdm:

>       sdf -2xxx mymod.sdm

[keep_next]Generate format xxx for a table:

>       sdf -2xxx mydata.tbl
>       sdf -2xxx -aformat='15,75,10' mydata.tbl

[keep_next]Generate format xxx for a MIMS topic, chapter or specification:

>       sdf -2xxx +mt mydoc
>       sdf -2xxx +mc mydoc
>       sdf -2xxx +ms mydoc

H2: Target Formats

The format naming conventions are:

* {{xxx}} - generate (logical) format xxx
* {{xxx_yyy}} - generate format xxx via yyy
* {{xxx_}} - generate format xxx directly.

{{CMD:sdf}}'s -2 option is used to specify the target format.

H3: Logical Formats

!block table; wrap=3; format='13,20,13,20,13,20'
Format          Maps_to
_dir            html_dir
book            ps_fmbook
doc             doc_fm
dvi             dvi_sgml
expand          sdf_expand
fvo             fvo_fm
hlp             hlp_mif
html            html_
htx             htx_
info            info_sgml
latex           latex_sgml
lyx             lyx_sgml
man             man_pod
mf6             mf6_
mif             mif_
pdf             pdf_mif
pod             pod_
ps              ps_fm
raw             sdf_raw
rtf             rtf_fm
sgml            sgml_
topics          html_topics
txt             txt_
!endblock

H3: Explicit Formats

!block table
Format          Generates
doc_fm          Frame binary format via FrameMaker
dvi_sgml        DVI format via SGML
fvo_fm          FrameViewer format via FrameMaker
hlp_mif         Windows Help input files via MIF
html_           a HTML document
html_dir        an SDF directory in HTML
html_fm         a HTML document via FrameMaker
html_topics     HTML topics
htx_            MIMS HTX format
info_sgml       GNU info format via SGML
latex_          LaTeX format
latex_pod       LaTeX format via POD
latex_sgml      LaTeX format via SGML
lyx_sgml        a LyX file via SGML
man_pod         Man page format via POD
mf6_            MIMS F6 help format
mif_            Frame MIF format
pdf_html        PDF via HTMLDOC
pdf_mif         PostScript and PDF via FrameMaker
pod_            POD format
ps_fm           PostScript via FrameMaker
ps_fmbook       PostScript via a FrameMaker book
ps_html         PostScript via HTMLDOC
ps_pod          PostScript via POD
ps_sgml         PostScript via SGML
rtf_fm          RTF format via FrameMaker
rtf_mif         RTF format via MIF
rtf_sgml        RTF format via SGML format
sdf_expand      expanded SDF
sdf_raw         raw SDF
sgml_           SGML format
txt_            plain text format
txt_fm          plain text format via FrameMaker
txt_pod         plain text format via POD
!endblock

H2: Document Styles

!block table; wrap=2; format='15,35,15,35'
Style       Description
document    normal document (default)
fax         fascimile
listing     program listing
manual      user manual
memo        memorandum
minutes     minutes of a meeting
newslettr   newsletter
paper       technical paper
!endblock

H2: Looks

!block table
Style           Description
fancy           look useful for manuals
infomap         Information Mapping[[tm]]
overhead        look useful for overhead transparencies
plain           alias for {{simple}}
simple          look useful for normal documents
!endblock

H2: Page Sizes

!block table; wrap=2; format='15,15,20,15,15,20'
Name    Width   Height
global  21.0cm  11.0in
A3      29.7cm  42.0cm 
A4      21.0cm  29.7cm
A5      14.8cm  21.0cm
B4      25.7cm  36.4cm
B5      17.6cm  25.0cm
letter  8.5in   11.0in
legal   8.5in   14.0in
tabloid 11.0in  17.0in
!endblock

Rotated sizes are named with an appended R (e.g. A4R).

H2: Reports

!block table
Name            Description
sdf_dir         generate a directory tree of nested SDF documents
!endblock

H2: Pre-filters

Files with extensions matching a pre-filter name or alias have the name filter applied.

!block table; wrap=2; format='15,35,15,35'
Name            Aliases
table           tbl
template        sdt
module          sdm
pod             pm,PL
!endblock

H1[nopb] SDF - The Language

H2: Concepts and Conventions

!block table
Term        Description
paragraph   the basic building block of documents
phrase      a section of text delimited by E<2{> and E<2}> within a paragraph
style       the type of a document, paragraph, phrase or table (e.g. H1)
attribute   a property of a paragraph or phrase (e.g. jump)
macro       a command embedded in a document (e.g. !define)
variable    a named value (e.g. DOC_NAME)
block       a section of text enclosed by {{MAC:block}} and {{MAC:endblock}} macros
filter      a rule to use when processing blocks or files (e.g. table)
module      a file containing reusable information
library     a directory containing modules
!endblock

For variables, the general conventions are:

* lower-case for special symbols (e.g. tm)
* edit-case for commonly used objects (e.g. Mincom)
* upper-case for other variables (e.g. DOC_NAME).

The general conventions for other symbols are:

* upper-case for paragraph and phrase styles
* lower-case for other names.

H2: Paragraph Styles

!block table; groups
Tag             Description
A0 .. A6        appendix heading at level 0..6
Addr            line in an address
E               example
E80             example at least 80 characters per line
FA              figure anchor
FOOTER          page footer (in header/footer only)
FT              figure title
GL              glossary entry (term and definition are tab separated)
GLD             definition in a glossary
GLT             term in a glossary
H0 .. H6        normal heading at level 0..6
HEADER          page header (in header/footer only)
KN              normal paragraph - keep with next
KP              normal paragraph - keep with previous
L1 .. L6        paragraph (or plain list item) at level 1..6
Line            horizontal line
LF1 .. LF6      first entry in an ordered list at level 1..6
LI1 .. LI6      enumerated list item at level 1..6
LN1 .. LN6      next entry in an ordered list at level 1..6
LU1 .. LU6      unordered list at level 1..6
N               normal paragraph
NB              note begin
NE              note end
NV              name value
Note            a single paragraph note
P0 .. P6        plain heading at level 0..6
PB              page break
Sign            signature
V               verbatim (example with no embedded symbols)
!endblock

Special styles (implicitly terminated) are:

!block table
Tag             Description
>               verbatim paragraph
. .. ......     paragraph (or plain list item) at level 1..6
* .. ******     unordered list at level 1..6
- .. -----      unordered list at level 2..6
^ .. ^^^^^^     first entry in an ordered list at level 1..6
+ .. ++++++     next entry in an ordered list at level 1..6
& .. &&&&&&     labelled list item at level 1..6
!endblock

H2: Paragraph Attributes

!block table
Name        Type        Description
align       string      alignment of paragraph within text column \
                        (1, Full, Left, Right, Center)
#continued   boolean     ???
component   string      start a component within a book \
                        (see {{SECT:Book Components}})
first       string      indent of first line (in points)
in          integer     list indent level (for examples only)
keep_next   boolean     keep this paragraph with the next one
keep_prev   boolean     keep this paragraph with the previous one
label       string      label for this paragraph (e.g. "Tip:")
left        string      left indent (in points)
noevents    boolean     do not do event processing on this paragraph
nopb        boolean     do not force this paragraph onto a new page
notoc       boolean     do not put this in the table of contents
noid        boolean     do not auto-generate an id for this paragraph
obj         string      format as the nominated phrase
orig_style  string      original style (useful in event processing)
out_style   string      output style to use
right       string      right indent (in points)
sp_after    string      space after this paragraph (in points)
sp_before   string      space before this paragraph (in points)
tabs        string      comma-separated list of tabstops
text        string      display the value instead of the existing text
top         string      place paragraph on a new page (1, 0, Page, Column, Left, Right)
wide        boolean     span the side-head
!endblock

H2: Phrase Styles

Leading whitespace is not removed for styles marked with (*).

!block table
Tag             Description
1               1st level emphasis
2               2nd level emphasis
3               3rd level emphasis
A               as-is
B               bold
C               source code (*)
CHAR            escape/special character
CMD             command
E               escape/special character
EMAIL           email address
EX              example text (*)
F               filename
FILE            filename
I               italic
IMPORT          figure
INLINE          embedded target format
JUMP            same as URL
L               POD link
N               normal
#P               ???
S               text with non-breaking spaces (*)
SECT            (jump to) document section
ST              strong emphasis
SUB             subscript
SUP             superscript
#T               ???
U               underline
URL             Uniform Resource Locator
X               POD index entry
Y               symbol (e.g. subroutine)
Z               zero width character (ala POD)
!endblock

The following styles are only supported in headers/footers:

!block table
Tag             Description
PAGECOUNT       highest page number
PAGENUM         current page number
PARALAST        text of last paragraph on page with the nominated style
PARANUM         paragraph number (e.g. Appendix A)
PARANUMONLY     paragraph number only (e.g. A)
PARASHORT       value of {{short}} attribute of paragraph
PARATEXT        paragraph text (e.g. Hardware requirements)
!endblock

The {{PARA*}} tags require a comma separated list of paragraph styles
to be nominated as the text of the phrase, e.g. E<2{>PARATEXT:H1,A1,P1E<2}>.

H2: Phrase Attributes

!block table
Name        Type        Description
bgcolor     string      background colour
bold        boolean     enable bold
changed     boolean     enable change bars
class       string      CSS class (for HTML documents)
color       string      text colour
doc         string      for SECT, the name of the document containing the section
expand      boolean     expand object from short to long name
family      string      font family
id          string      identifier for this phrase (used by jumps)
index       string      indexing specification string (MIF only)
index_type  string      index type (MIF only)
italics     boolean     enable italics
jump        string      URL to jump to
short       string      text to display in header/footer when PARASHORT used
shrink      boolean     shrink object from long to short name
size        string      font size
style       string      custom CSS style information (for HTML documents)
text        string      display the value instead of the existing text
underline   boolean     enable underline
verbatim    boolean     ignore embedded symbols within this paragraph
xref        string      cross-referencing information (future)
!endblock

H2: Escapes

!block table; wrap=3; format='16,17,16,17,16,17'
Name            Output
2[              E<2[>
2]              E<2]>
2{              E<2{>
2}              E<2}>
Aacute          E
aacute          E
Acirc           E
acirc           E
AElig           E
aelig           E
Agrave          E
agrave          E
amp             E
Aring           E
aring           E
Atilde          E
atilde          E
Auml            E
auml            E
bullet          E
c               E
Ccedil          E
ccedil          E
cent            E
dagger          E
doubledagger    E
Eacute          E
eacute          E
Ecirc           E
ecirc           E
Egrave          E
egrave          E
emdash          E
emspace         E
endash          E
enspace         E
Euml            E
euml            E
gt              E
Iacute          E
iacute          E
Icirc           E
icirc           E
Igrave          E
igrave          E
Iuml            E
iuml            E
lbrace          E
lbracket        E
lt              E
nbdash          E
nbspace         {{non-breaking space}}
nl              {{newline}}
Ntilde          E
ntilde          E
Oacute          E
oacute          E
Ocirc           E
ocirc           E
Ograve          E
ograve          E
Oslash          E
oslash          E
Otilde          E
otilde          E
Ouml            E
ouml            E
pound           E
quot            E
r               E
rbrace          E
rbracket        E
tab             {{tab}}
tm              E
Uacute          E
uacute          E
Ucirc           E
ucirc           E
Ugrave          E
ugrave          E
Uuml            E
uuml            E
yen             E
yuml            E
!endblock

For convenience, variables are provided for:
amp, bullet, c, cent, dagger, doubledagger, emdash, endash, emspace, enspace,
nbdash, nbspace, nbsp, nl, pound, r, reg, tab, tm, yen.

H2: Macros

!block table
Name                Description
back                ends a list (from POD)
begin               begin target-specific output (from POD)
block               begin a block of text
build_title         build a title page
catalog             build a catalog from objects already loaded
class               define a class of objects
clear               reset text wrapping around a figure
continued           continue a heading from a previous page
cut                 ignore text until an = is found at the start of a line (from POD)
default             set a variable (if not already set)
define              set a variable
div                 begin a division
else                begin alternative section
elseif              same as elsif
elsif               begin a conditional section
end                 end target-specific output (from POD)
end_topic           mark the end of a topic
endblock            end a block of text
enddiv              end a division
endif               end conditional text
endmacro            end a macro definition
execute             include output from a command
export              export a variable to the format driver (and/or mark it for later exporting)
for                 insert target-specific output (from POD)
getcli              extract command-line interface information
getcode             extract source code (i.e. non-documentation) from a file
getdoc              extract documentation embedded in source code
head{{n}}           level {{n}} heading (n = 1 .. 6) (from POD)
if                  begin conditional text
import              import an external object (e.g. figure)
include             include another file
inherit             inherit entities from a library
init                initialise variables (before loading configuration files)
insert              call a macro
item                label an item in a list (from POD)
jumps               generate lines of jumps to headings
line                change message parameters
macro               begin a macro definition
message             output a message during execution
off                 disable processing previously specified
on                  specify processing for an event
output              dynamically change the output file used
over                begins a list (from POD)
perlapi             extract API information from a [[Perl]] library
pod                 does nothing (from POD)
restrict            declare a restricted family of variables
script              execute a line of [[Perl]]
slide_down          decrease heading levels (e.g. H2 -> H3)
slide_up            increase heading levels (e.g. H2 -> H1)
subsections         specify the subsections for a topic
undef               clear a variable
use                 load a library module
!endblock

H2: Filters

!block table
Filter          Description
about           about section of a document
abstract        the abstract for a paper
address         an address
appendix        change headings to appendix style
ascii_graphic   fixed-width text, wide enough for ASCII graphics
box             surround a region of text with a box
center          centre a region
changed         mark a block of text as changed
chapter         chapter of a document (does nothing)
comment         ignore text
datestrings     define strings used in dates
default         provide defaults for a block of variables
define          define a block of variables
end             process text at the end
example         fixed-width text (e.g. source code)
front           front section of a document
get             extract embedded documentation
glossary        glossary section of document (alias for plain)
hlp_header      table of jumps at the top of a help topic
hlp_window      contents of a help popup window
inline          embed text into target format (e.g. [[HTML]])
langdefs        define vgrind-like language definitions
links           define external links for a document (including stylesheets)
meta            define meta information for a document
namevalues      format a set of name-value pairs (e.g. as used in a title block)
nofill          a set of lines
note            a note
plain           change headings to plain style
pod             embedded POD
quote           a quotation
script          execute text as a [[Perl]] script
sdf             apply arbitrary phrase attributes to text
sections        paragraphs are sections
simple          generic filter for building others
stylesheet      define a stylesheet which should be inline in the HTML output
table           tabular data
template        alias for inline with {{expand}} set to true
title           title block for a memo, fax or minutes
topics          include a set of sub-topics
verbatim        fixed-width text, ignoring embedded symbols
!endblock

{{SECT:Classes}} and {{SECT:Programming Languages}} can also be used as filters.

H2: Figures

Extension search rules:

!block table
When_generating     The_search_order_is
PostScript          epsi, eps, wmf, mif, gif
HTML                jpeg, jpg, png, gif
Windows Help        bmp
!endblock

{{MAC:import}} macro parameters:

!block table
Name            Description
alt             alternate text to display (ala HTML)
align           alignment (Left, Center, Right, Inner, Outer)
base            the prefix to prepend to the figure pathname \
                to get the location needed for the HTML output
border          the border width in pixels
height          explicit height measurement (MIF only)
jump            the URL to jump to
listitem        the list indent level (e.g. 1)
mif_figure      the tag before the figure in the MIF source \
                (only needed if more than one figure in the MIF file)
position        vertical position (Below, Top, Bottom)
title           figure caption
wide            figure straddles the side head area of the page
width           explicit width measurement (MIF only)
wrap_text       wrap text around a figure (ignored for HTML)
!endblock

Default conversion rules (from F):

# Limit the first column
!block table; format='15%'
When_generating Create  From    Using_the_command
html            gif     eps     ps2gif -crop $source
html            gif     ps      ps2gif -crop $source
html            gif     prn     prn2ps -ops $source; ps2gif -crop $base.ps; rm $base.ps
ps              eps     ps      ps2epsi $source $dest
ps              eps     prn     prn2ps -ops $source; ps2epsi $base.ps $dest; rm $base.ps
!endblock

H2: Tables

{{FILT:table}} filter parameters:

!block table
Name          Description
align         alignment of table: one of Left, Center, Right, Inner, Outer
bgcolor       background colour for a table (HTML only)
bmargin       default bottom margin for table cells (MIF only)
cellpadding   padding size for table cells (HTML only)
cellspacing   spacing size between table cells (HTML only)
colaligns     a comma-separated list of horizontal alignments \
              values (Left, Center, Right) for columns; \
              alternatively, a single word containing the letters L, C and R
coltags       a comma-separated list of phrase styles to apply to columns
colvaligns    a comma-separated list of vertical alignments \
              values (Top, Middle, Bottom, Baseline) for columns; \
              alternatively, a single word containing the letters T, M, B and L
delete        a comma-separated list of columns to delete
footings      the number of footing rows at the end of the table
format        a comma-separated list of column width specifications; \
              alternatively, a single number where each digit represents \
              10% of the space available to the table
groups        pattern of group-style rows (default is /:$/)
headings      the number of heading rows at the top of the table
keepindents   keep leading whitespace in cells
landscape     display the table in landscape mode (MIF only)
listitem      the list indent level (e.g. 1) of this table
lmargin       default left margin for table cells (MIF only)
narrow        if set, the table will only be as wide as required; \
              otherwise the table will span the available space
niceheadings  set to 0 to disable _ to space conversion in headings
nocalcs       set to 0 to disable calculation processing within a table
noheadings    suppress headings in output
objects       alias for coltags (coltags is preferred)
oncell        Perl code to execute for each cell (internal use only!)
parseline     column headings parsing line (if not the first row in the text)
placement     vertical placement of table: one of Float, Pagetop, Columntop, \
              Lefttop, Righttop (MIF only)
rmargin       default right margin for table cells (MIF only)
select        a comma-separated list of columns to display
sort          a comma-separated list of columns to sort the data rows by
style         overall look of the table (columns, rows, grid, plain, shade)
tags          alias for coltags (coltags is preferred)
title         table caption
tmargin       default top margin for table cells (MIF only)
type          alias for style (style is preferred)
where         an expression to filter the data rows with
wide          table straddles the side head area of the page
wrap          the number of data rows to display in a physical row
!endblock

Column width specifications:

!block table
Value       Meaning
30pt        an exact size (other supported units are cm, mm, " and in)
30%         a percentage of the size available
30          a percentage of the size available (% is implicit)
10-20       dynamic size between 10% and 20% of the total width
-20         dynamic size between 0% and 20% of the total width
10-         dynamic size between 10% and 100% of the total width
-           dynamic size between 0% and 100% of the total width
3*          3 units of the remaining space
*           same as 1*
!endblock

N: = can be used in place of - to get equalised column widths.

Cell attributes:

!block table; groups
Name        Value
align       horizontal alignment (Left, Center, Right)
angle       angle of text (0, 90, 180, 270)
bgcolor     background colour of cell
bruling     ruling setting for bottom of cell
cols        the number of columns this cell spans (default is 1)
fill        background colour fill % \
            (100, 90, 70, 50, 30, 10, 3)
lruling     ruling setting for left of cell
nowrap      disable word wrap for this cell
paratag     paragraph style to apply to cell text (future)
rows        the number of rows this cell spans (default is 1)
rruling     ruling setting for right of cell
sdf         treat the cell text as SDF (rather than as phrase text)
tag         phrase tag to apply to cell text
truling     ruling setting for top of cell
valign      vertical alignment (Top, Middle, Bottom, Baseline)
!endblock

Permitted ruling values: {{Vthin}}, {{Thin}}, {{Medium}}, {{Thick}}, {{Double}}.

H2: Classes

Data fields for the predefined classes are:

!block table; groups
Field           Tag     Description
organisations:
Name            ORG     organisation name
Long            ORGN    long form of organisation name
Jump                    URL for organisation
products:
Name            PRD     product name
Jump                    URL for product
references:
Reference       REF     document code
Document        DOC     document title
Jump                    URL for document
Version                 version number
Status                  status (e.g. Draft, Review or Final)
terms:
Term            TERM    term, acronym or abbreviation
Description             explanation
Jump                    URL for term
!endblock

The REFNUMONLY tag can be used to mark a REF phrase where only the
trailing number is output.

Calculated fields for the {{CLASS:references}} class:

!block table
Name       Description
XXX        if a matching xxx file is found, an image which jumps to that file
Cite       a string of the form [n]
Date       the date of the html file
Pages      the number of pages in the PostScript document
Printdoc   an image which launches the F CGI script
Printer    alias for Printdoc
!endblock

Parameters of class filters:

!block table
Name       Type         Description
cited      boolean      number these objects as the cited ones \
                        (for [1] style references)
colaligns  string       a comma-separated list of horizontal alignments  \
                        values (Left, Center, Right) for columns; \
                        alternatively, a single word containing the \
                        letters L, C and R can be used for the value
columns    string       comma-separated list of attributes to display in table
colvaligns string       a comma-separated list of vertical alignments  \
                        values (Top, Middle, Bottom, Baseline) for columns; \
                        alternatively, a single word containing the \
                        letters T, M, B and L can be used for the value
compact    boolean      display in a compact table, (make cellpadding \
data       boolean      define objects but do not display them
delete     string       a comma-separated list of columns to delete
headings   boolean      display the column headings
root       string       string to prepend to Jump attribute, if any
select     string       a comma-separated list of columns to display
sort       string       comma-separated list of columns to sort by
style      string       table style to use (the default is {{plain}})
                        and cellspacing both equal to zero)
variables  boolean      define a variable for each object; the variable name \
                        is derived from the object name with underscores \
                        replacing non-alphanumeric characters
where      string       filter the rows using the nominated expression
wide       boolean      use sidehead when formatting on paper
wrap       integer      number of logical rows to place on a physical row
!endblock

H2: Document Variables/Macros

P3: Controls

!block table; groups
Name                        Type        Description
DOC_ADMIN_LOGO              string      logo to use in administration document styles
DOC_ADMIN_LOGO_BASE         string      base directory for DOC_ADMIN_LOGO
DOC_APPROVE                 string      person approving the document
DOC_APPROVE2                string      2nd person approving the document
DOC_APPROVE3                string      3rd person approving the document
DOC_AUTHOR                  string      author of document
DOC_AUTHOR2                 string      2nd author of document
DOC_AUTHOR3                 string      3rd author of document
DOC_CODE                    string      document code (*)
DOC_COMPONENT               string      current component type within a book
DOC_COMPONENT_LOGO          string      logo to use for components within a book
DOC_COVER                   string      logical name of the cover page to use \
                                        (e.g. original, project, manual, paper)
DOC_DISTRIBUTION            string      document distribution
DOC_HTML_LOGO               string      logo to use in HTML output
DOC_HTML_LOGO_BASE          string      base directory for HTML_LOGO
DOC_ID_SEP                  string      separator used within DOC_ID
DOC_IX                      boolean     build an index
DOC_LOF                     boolean     build a list of figures
DOC_LOF_TITLE               string      list of figures title
DOC_LOGO                    string      logo to use for document
DOC_LOGO_BASE               string      base directory for DOC_LOGO
DOC_LOT                     boolean     build a list of tables
DOC_LOT_TITLE               string      list of tables title
DOC_MANUAL_LOGO             string      logo to use when generating paper manuals
DOC_NAME                    string      document name, e.g. "SDF 2.000"
DOC_OWNER                   string      person or company owning the copyright
DOC_PRODUCT                 string      for man pages, the center string in the header
DOC_PROJECT                 string      orginating project of document
DOC_SECTION                 integer     for man pages, the section number
DOC_STATUS                  string      status of document (*)
DOC_TITLE_LOGO              string      logo used in the title of a PostScript document
#DOC_TITLE_LOGO_BASE         string      base directory for DOC_TITLE_LOGO - why is this needed?
DOC_TOC                     integer     table of contents level
DOC_TOC_GRAPHIC             string      graphic to include in TOC title
DOC_TOC_TITLE               string      table of contents title
DOC_TOPIC_LOGO              string      logo to use in HTML topics mode output
DOC_TOPIC_LOGO_BASE         string      base directory for DOC_TOPIC_LOGO
DOC_TWO_SIDES               boolean     build a two-sided document
DOC_TYPE                    string      document type, e.g. "User Guide"
DOC_URL                     string      URL of document
DOC_VERSION                 string      version number of document (*)

Macros:
DOC_COMPONENT_BEGIN         macro       hook to initialise things before book \
                                        component processing begins
DOC_COMPONENT_END           macro       hook to finalise things after book \
                                        component processing ends
DOC_OFFICES                 macro       for manuals, the text to put after the \
                                        inside front cover
DOC_RECIPIENTS              macro       table of controlled copy recipients
DOC_TRADEMARKS              macro       text specifying trademarks used in document
!endblock

If the variables marked with (*) are not defined,
{{MAC:build_title}} sets them using the references data, if possible.

P3: Information

!block table; groups
Name                        Type        Description
DOC_BASE                    string      the base (filename) of the current document
DOC_COLUMN_WIDTH            integer     width of a text column (in points)
DOC_DIR                     string      the directory of the current document
DOC_EXT                     string      the extension of the current document
DOC_FULL_WIDTH              integer     width of text area including the side-head (in points)
DOC_ID                      string      combination of DOC_CODE and DOC_VERSION
DOC_MODIFIED                datetime    the most recent modification time of files visited so far
DOC_PAGE_HEIGHT             integer     height of page (in points)
DOC_PAGE_WIDTH              integer     width of page (in points)
DOC_PAGED                   boolean     output is paged, not continuous
DOC_PATH                    string      the full pathname of the current document
DOC_SHORT                   string      the base and extension of the current document
DOC_START                   datetime    the time document conversion started
DOC_TEXT_HEIGHT             integer     height of text area (in points)
DOC_TEXT_WIDTH              integer     width of text area available for text columns (in points)
DOC_TITLE                   string      combination of DOC_NAME and DOC_TYPE
MODIFIED_DATE               string      alias for DATE:DOC_MODIFIED

File:
FILE_BASE                   string      base part of current filename (e.g. {{mydoc}})
FILE_DIR                    string      directory of current filename (e.g. {{/doc/sdf}})
FILE_EXT                    string      extension of current filename (e.g. {{sdf}})
FILE_MODIFIED               datetime    time when this file was last modified
FILE_PATH                   string      current pathname (e.g. {{/doc/sdf/mydoc.sdf}})
!endblock

H2: Option Variables

These variables (except OPT_NOBARS) give the values of command-line options.
Variables marked with a (*) can be set via the {{MAC:init}} macro on the
top line of a document:

!block table
Name                        Type        Description
OPT_CONFIG                  string      configuration library (*)
OPT_DRIVER                  string      name of driver used to convert documents
OPT_EXT                     string      output extension
OPT_HEAD_LEVEL              integer     level to start headings at
OPT_HEAD_LOOK               string      look for headings
OPT_LOCALE                  string      locale
OPT_LOOK                    string      look (*)
OPT_NOBARS                  boolean     disable change bars (*)
OPT_NUMBER                  integer     line numbering fequency
OPT_PAGE_SIZE               string      page size setting (default is {{global}}) (*)
OPT_PP_xxx                  boolean     set if xxx post-processing requested
OPT_REPORT                  string      report to run
OPT_SPLIT_LEVEL             integer     level to split headings at for topics mode
OPT_STYLE                   string      document style (*)
OPT_TARGET                  string      target format
OPT_WIDTH                   integer     width for txt output (default is 70) (*)
!endblock

These variables can only be set within look libraries:

# Limit the first column size
!block table; format='40%'
Name                        Type        Description
OPT_BORDERS                 integer     high-level header/footer border control \
                                        (0=none; 1=above footer,below header; \
                                        2=above footer,above & below header)
OPT_COLUMNS                 integer     number of columns in text area (default is 1)
OPT_COLUMN_GAP              dimension   gap between columns in text area
OPT_COMPONENT_COVER         boolean     give book components a cover page
OPT_HEADINGS                integer     size in lines (0..4) of headers/footers \
                                        (Note: for values 2..4, header size is 2)
OPT_IX_COLUMNS              integer     number of columns in text area in the index (default is 1)
OPT_IX_COLUMN_GAP           dimension   gap between columns in text area in the index
OPT_IX_SIDEHEAD_GAP         dimension   width between side-head and text area in the index
OPT_IX_SIDEHEAD_WIDTH       dimension   width of side-head in the index
OPT_LIST_INDENT             dimension   size of each list indent in points
OPT_MARGIN_BOTTOM           string      size of margin below the footer, if any
OPT_MARGIN_INNER            string      size of inner margin
OPT_MARGIN_OUTER            string      size of outer margin
OPT_MARGIN_TOP              string      size of margin above the header, if any
OPT_NUMBER_PER_COMPONENT    boolean     number figures, etc. per component
OPT_SIDEHEAD_GAP            dimension   width between side-head and first text column
OPT_SIDEHEAD_WIDTH          dimension   width of side-head
#OPT_TEMPLATE                string      ???
!endblock

H2: Page Layout Variables

Page variables can only be set within look libraries.

Page tags:

!block table
Page    Usage
FIRST   the first page in the document
RIGHT   the page used for single-sided documents and the right hand side of double-sided documents
LEFT    the left hand side of double-sided documents; ignored for single-sided documents
!endblock

In the table below, {{frl}} is either:

* FIRST, RIGHT or LEFT, or
* {{COMPONENT}}_{{FRL}} where:
  - {{COMPONENT}} is the name of the component in upper-case
    (refer to {{SECT:Book Components}})
  - {{FRL}} is FIRST, RIGHT or LEFT.

If a component does not have a component-specific macro/variable
defined, then the generic macro/variable is used.

!block table
Name                        Type        Description
PAGE_{{frl}}_BACKGROUND     string      background image name
PAGE_{{frl}}_FOOTER_BORDER  string      border specification
PAGE_{{frl}}_FOOTER_GAP     dimension   gap between text area and footer area
PAGE_{{frl}}_FOOTER_HEIGHT  dimension   height of footer area
PAGE_{{frl}}_FOOTER_INNERn  string      inner text of line n (0..3) of footer
PAGE_{{frl}}_FOOTER_CENTERn string      centre text of line n (0..3) of footer
PAGE_{{frl}}_FOOTER_OUTERn  string      outer text of line n (0..3) of footer
PAGE_{{frl}}_HEADER_BORDER  string      border specification
PAGE_{{frl}}_HEADER_GAP     dimension   gap between header area and text area
PAGE_{{frl}}_HEADER_HEIGHT  dimension   height of header area
PAGE_{{frl}}_HEADER_INNERn  string      inner text of line n (1..2) of header
PAGE_{{frl}}_HEADER_CENTERn string      centre text of line n (1..2) of header
PAGE_{{frl}}_HEADER_OUTERn  string      outer text of line n (1..2) of header
!endblock

When [[FrameMaker]] is being used to generate [[PostScript]],
the background image name is mapped to a master page called
{{backgrnd}} within a file called {{backgrnd}}.mif.
At the moment, objects from the master page
(excluding TextRects) are directly transferred to the
generated MIF file. This means that objects in the
lower right hand corner of an A4 master page will not
will be positioned nicely if the paper size is changed
to A5, say.

A {{border specification}} string is a comma-separated list
of attributes which collectively describe the border.
The format of each attribute is name[=value].
The supported attributes are:

* {{top}} - a line above the area
* {{bottom}} - a line below the area
* {{box}} - a box around the area
* {{radius}} - for a box, the radius of the corner.

For {{top}}, {{bottom}} and {{box}}, the value of the
attribute is the line width in points.

H2: Miscellaneous Variables/Macros

P3: Controls

!block table; groups
Name                        Type        Description
Processing:
DEFAULT_LOCALE              string      default OPT_LOCALE (set in F)
DEFAULT_LOOK                string      default OPT_LOOK (set in F)
DEFAULT_TAB_SIZE            integer     default tab size (initially 8)
DEFAULT_TABLE_STYLE         string      default style for tables (initially {{columns}})
DEFAULT_XREF_STYLE          string      default style for cross-references (initially {{sections}})

Link expansion formats:
FORMAT_LINK_PAGE            string      default is: the $page manpage
FORMAT_LINK_PAGE_ENTRY      string      default is: the $entry entry in the $page manpage
FORMAT_LINK_PAGE_SECTION    string      default is: the section on "$sect" in the $page manpage
FORMAT_LINK_SECTION         string      default is: the section on "$sect"

HTMLDOC generation:
HTMLDOC                     boolean     generate HTML ready for HTMLDOC
HTMLDOC_OPTS                string      tuning options to pass to HTMLDOC
!endblock

P3: Information

!block table; groups
Name                        Type        Description
Package:
SDF                         phrase      PRD:SDF
SDF_BUGS                    phrase      EMAIL:sdf-bugs@mincom.com
SDF_FTP                     string      URL for SDF's FTP site
SDF_HOME                    string      library/configuration directory
SDF_USERS                   phrase      EMAIL:sdf-users@mincom.com
SDF_VERSION                 string      product version string (e.g. 2.000 beta1)
SDF_WWW                     string      URL for SDF's home page

Macros for default.sdg:
SDG_DESCRIPTION_POST        macro       finalisation after {{Description}}
SDG_DESCRIPTION_PRE         macro       initialisation before {{Description}}
SDG_BEGIN                   macro       hook for things before extracted text
SDG_END                     macro       hook for things after extracted text
SDF_OPT_HELP                macro       text explaining help option
SDF_OPT_STD                 macro       text explaining standard options

Old macro names:
BUILD_TITLE                 string      provided for backwards-compatibility
END_TOPIC                   string      provided for backwards-compatibility
SLIDE_DOWN                  string      provided for backwards-compatibility
SLIDE_UP                    string      provided for backwards-compatibility
SDF_DESCRIPTION_POST        macro       provided for backwards-compatibility
SDF_DESCRIPTION_PRE         macro       provided for backwards-compatibility
!endblock

H2: Programming Languages

!block table
Language                        Names
C                               c
C++                             c++, cpp, hpp, cc, h
COBOL                           cobol
CORBA IDL                       idl
FORTRAN                         fortran, f77, fc, f, for
Java                            java
MIMS COBOL                      mimscobol, pcom, precom
Object Pascal                   delphi, pascal, pas, int
Perl                            perl, pl, pm, sdp, sdr
Python                          python, jpython, py
Simple Document Format          sdf, sdm, sds, sdn, sdl, sde
Unix shell                      sh
Unix c-shell                    csh
!endblock

Language names are case insensitive.

H2: Colours

For PS (i.e. MIF) generation, the supported colour values are
{{Black}}, {{White}}, {{Red}}, {{Green}},
{{Blue}}, {{Yellow}}, {{Cyan}} and {{Magenta}}.
If a different colour is specified, it is ignored.

For HTML generation, any of the HTML colours names
(including those supported for PS generation) or the "#rrggbb" form
can be used. Useful variables are:

!block table; wrap=2; format='30,20,30,20'
Name            Value
COLOR_WHITE     'ffffff'
COLOR_BLACK     '000000'
COLOR_RED       'ff0000'
COLOR_GREEN     '00ff00'
COLOR_BLUE      '0000ff'
COLOR_YELLOW    'ffff00'
COLOR_MAGENTA   'ff00ff'
COLOR_CYAN      '00ffff'
COLOR_GREY      'c0c0c0'
!endblock

H2: Expression Formats

!block table; groups
Name            Description
Strings:
LOWER           convert a string to lowercase
LOWER1          convert the first character to lowercase
UPPER           convert a string to uppercase
UPPER1          convert the first character to uppercase

Dates:
CONCISE         alias for FORMAT_SDATE
DATE            format to a date only
DATETIME        format to a complete date-time format
FULL            alias for FORMAT_DATETIME
SDATE           format to a concise date only
TIME            format to a time only
YEAR            format to a 4-digit year
!endblock

Expression format XXX can be changed/defined via the FORMAT_XXX variable.

H2: Modules

!block table
Name            Description
bugtrack        extensions for bug tracking
defines         simplified product declaration/definition
delphi          extensions for delphi 1.x documentation
homepage        extensions for making SDF-like home pages easier to author
misc            miscellaneous goodies
objects         IT-related objects
testcase        extensions for test case documentation
usecases        extensions for Use Case documentation
!endblock

H2: Book Components

!block table
Name                Meaning
front               the cover component
pretoc              components before the contents
toc                 the table of contents
lof                 the list of figures
lot                 the list of tables
prechapter          components before the chapters
chapter             a normal chapter
appendix            an appendix
preix               components before the index
ix                  the index
!endblock

H2: Event Processing

KN: Supported symbols within actions:

!block table
Type        Symbols
paragraph   $style, $text, %attr, &PrependText, &AppendText, \
            $level, $prev_style, $prev_text, %prev_attr
phrase      $style, $text, %attr, $append
macro       $name, $args
filter      $name, $params
table       $style, %param
!endblock

KN: Special symbol meanings:

!block table; groups
Symbol          Meaning
paragraph:
&PrependText    a subroutine to add paragraphs before this one
&AppendText     a subroutine to add paragraphs after this one
$level          the current heading level ({{before}} this paragraph)
$prev_style     the style of the previous paragraph
$prev_text      the text of the previous paragraph
%prev_attr      the attributes of the previous paragraph
phrase:
$append         text to append onto the end of the phrase
!endblock


#H1: Format Specific Extensions
#
#H2: HTML
#
#H2: MIF
#
#H2: Plain Text
#
#H2: PODNote: for values 2..4, header size is 2)
OPT_IX_COLUMNS              integer     number of columns in text area in the index (default is 1)
OPT_IX_Csdf-2.001/doc/quickref/qr_sdf.html010064400042570001753000002337000672242332300166500ustar00iancmtr00000400000236






SDF 2.001: SDF Quick Reference




      

      

      Home | Catalog
      

      

      

      

      

      SDF Quick Reference
      

      MTR-SDF-0003.002 (Draft)
      

      Ian Clatworthy
      

      25 May 1999
      

      

      

      

      

      Table of Contents
      


      

      

      

      1. SDF - The Package
      

      1.1. Programs
      

      

      

Name


Purpose


      

      

sdf


convert SDF files to other formats


      

      

sdfapi


extract the Application Programming Interface from source code


      

      

sdfbatch


generate FrameMaker batch files


      

      

sdfcli


extract the Command Line Interface from a utility


      

      

sdfget


extract documentation embedded in source code


      

      

sdftest


execute SDF regression tests


      

      

sdngen


build an SDF tuning module from a FrameMaker template


      

      

fm2ps


convert FrameMaker files to PostScript (a wrapper for sdfbatch)


      

      

pod2sdf


convert POD to SDF


      

      

poddiff


compare POD files and report differences


      

      

prn2ps


convert Windows PostScript to Unix PostScript


      

      


      Environment variables used are:
      

      

      

Name


Description


      

      

SDFBIN


on MS-DOS/Windows systems, the directory containing SDF's scripts, (e.g. c:\sdf\bin\)


      

      

SDFOPTS


options always used by sdf (e.g. -Yc:\mysdflib)


      

      


      1.2. File Extension Conventions
      

      

      

Ext.


Format


Usage


Ext.


Format


Usage


      

      

ini


INI


configuration file


sde


SDF


SDF end module


      

      

sdf


SDF


normal SDF file


sdg


SDG


sdfget report


      

      

sdl


SDF


SDF locale


sdm


SDF


SDF module


      

      

sdn


SDF


SDF tuning module


sdo


TBL


SDF object register


      

      

sdp


Perl


SDF plug-in


sdr


Perl


SDF report


      

      

sds


SDF


SDF style module


sdt


HTML


SDF template


      

      


      

      2. sdf - The Program
      

      2.1. Command-line Options
      

      

      

Option


Long name


Description


      

      

-2


--format


the output format you want


      

      

-a


--parameters


parameters for the pre-filter


      

      

-c


--config


configuration library


      

      

-d


--driver


format driver - default is expand


      

      

-f


--flag


define flags (flag xxx maps to variable DOC_XXX)


      

      

-g


--get_report


prefilter using sdfget with the report specified


      

      

-h


--help


display help on options or a single option


      

      

-k


--look


look library


      

      

-l


--log_ext


log file extension (default is log)


      

      

-n


--split_level


heading level to autosplit into topics


      

      

-o


--out_ext


output file extension (default is out)


      

      

-p


--prefilter


pre-filter input file from each argument


      

      

-r


--report


report to pre-filter the input with


      

      

-s


--style


style of document


      

      

-t


--target


logical target format


      

      

-u


--uses


modules to use


      

      

-v


--verbose


verbose mode


      

      

-w


--width


width for text-based outputs


      

      

-y


--post_filter


filter to post-filter the output with


      

      

-z


--post_process


list of post processing actions to do


      

      

-D


--variable


define variables


      

      

-H


--head_level


initial heading level


      

      

-I


--include_path


search path for include files, templates, etc.


      

      

-K


--head_look


heading look (H, A or P)


      

      

-L


--locale


locale


      

      

-N


--line_numbers


number lines in pretty-printed source code


      

      

-O


--out_dir


output to input file's (or explicit) directory


      

      

-P


--plang


pre-filter as a programming language


      

      

-S


--page_size


page size for paper documents


      

      

-T


--trace_levels


debugging trace levels


      

      

-Y


--library_path


path to search for libraries and modules


      

      


      2.2. Useful Command Lines
      

      Generate format xxx for mydoc.sdf:
      

             sdf -2xxx mydoc

      

      Generate PDF via a FrameMaker book (on Unix):
      

             sdf -2book -zpdf mydoc

      

      Generate a man page:
      

             sdf -2man mydoc | nroff -man > mydoc.1

      

      Spell check a document:
      

             sdf mydoc | spell

      

      Pretty-print lang source code in format xxx:
      

             sdf -2xxx -Plang mysource
       sdf -2xxx -P mysource.lang
       sdf -2xxx -P -N5 mysource.lang   (with line numbering)

      

      Generate reference documentation in format xxx for mymod.sdm:
      

             sdf -2xxx mymod.sdm

      

      Generate format xxx for a table:
      

             sdf -2xxx mydata.tbl
       sdf -2xxx -aformat='15,75,10' mydata.tbl

      

      Generate format xxx for a MIMS topic, chapter or specification:
      

             sdf -2xxx +mt mydoc
       sdf -2xxx +mc mydoc
       sdf -2xxx +ms mydoc

      

      2.3. Target Formats
      

      The format naming conventions are:
      

        

      • xxx - generate (logical) format xxx

      • xxx_yyy - generate format xxx via yyy

      • xxx_ - generate format xxx directly.
      

      sdf's -2 option is used to specify the target format.
      

      2.3.1. Logical Formats
      

      

      

Format


Maps to


Format


Maps to


Format


Maps to


      

      

_dir


html_dir


book


ps_fmbook


doc


doc_fm


      

      

dvi


dvi_sgml


expand


sdf_expand


fvo


fvo_fm


      

      

hlp


hlp_mif


html


html_


htx


htx_


      

      

info


info_sgml


latex


latex_sgml


lyx


lyx_sgml


      

      

man


man_pod


mf6


mf6_


mif


mif_


      

      

pdf


pdf_mif


pod


pod_


ps


ps_fm


      

      

raw


sdf_raw


rtf


rtf_fm


sgml


sgml_


      

      

topics


html_topics


txt


txt_


      

      


      2.3.2. Explicit Formats
      

      

      

Format


Generates


      

      

doc_fm


Frame binary format via FrameMaker


      

      

dvi_sgml


DVI format via SGML


      

      

fvo_fm


FrameViewer format via FrameMaker


      

      

hlp_mif


Windows Help input files via MIF


      

      

html_


a HTML document


      

      

html_dir


an SDF directory in HTML


      

      

html_fm


a HTML document via FrameMaker


      

      

html_topics


HTML topics


      

      

htx_


MIMS HTX format


      

      

info_sgml


GNU info format via SGML


      

      

latex_


LaTeX format


      

      

latex_pod


LaTeX format via POD


      

      

latex_sgml


LaTeX format via SGML


      

      

lyx_sgml


a LyX file via SGML


      

      

man_pod


Man page format via POD


      

      

mf6_


MIMS F6 help format


      

      

mif_


Frame MIF format


      

      

pdf_html


PDF via HTMLDOC


      

      

pdf_mif


PostScript and PDF via FrameMaker


      

      

pod_


POD format


      

      

ps_fm


PostScript via FrameMaker


      

      

ps_fmbook


PostScript via a FrameMaker book


      

      

ps_html


PostScript via HTMLDOC


      

      

ps_pod


PostScript via POD


      

      

ps_sgml


PostScript via SGML


      

      

rtf_fm


RTF format via FrameMaker


      

      

rtf_mif


RTF format via MIF


      

      

rtf_sgml


RTF format via SGML format


      

      

sdf_expand


expanded SDF


      

      

sdf_raw


raw SDF


      

      

sgml_


SGML format


      

      

txt_


plain text format


      

      

txt_fm


plain text format via FrameMaker


      

      

txt_pod


plain text format via POD


      

      


      2.4. Document Styles
      

      

      

Style


Description


Style


Description


      

      

document


normal document (default)


fax


fascimile


      

      

listing


program listing


manual


user manual


      

      

memo


memorandum


minutes


minutes of a meeting


      

      

newslettr


newsletter


paper


technical paper


      

      


      2.5. Looks
      

      

      

Style


Description


      

      

fancy


look useful for manuals


      

      

infomap


Information Mapping™ 


      

      

overhead


look useful for overhead transparencies


      

      

plain


alias for simple


      

      

simple


look useful for normal documents


      

      


      2.6. Page Sizes
      

      

      

Name


Width


Height


Name


Width


Height


      

      

global


21.0cm


11.0in


A3


29.7cm


42.0cm


      

      

A4


21.0cm


29.7cm


A5


14.8cm


21.0cm


      

      

B4


25.7cm


36.4cm


B5


17.6cm


25.0cm


      

      

letter


8.5in


11.0in


legal


8.5in


14.0in


      

      

tabloid


11.0in


17.0in


      

      


      Rotated sizes are named with an appended R (e.g. A4R).
      

      2.7. Reports
      

      

      

Name


Description


      

      

sdf_dir


generate a directory tree of nested SDF documents


      

      


      2.8. Pre-filters
      

      Files with extensions matching a pre-filter name or alias have the name filter applied.
      

      

      

Name


Aliases


Name


Aliases


      

      

table


tbl


template


sdt


      

      

module


sdm


pod


pm,PL


      

      


      

      3. SDF - The Language
      

      3.1. Concepts and Conventions
      

      

      

Term


Description


      

      

paragraph


the basic building block of documents


      

      

phrase


a section of text delimited by {{ and }} within a paragraph


      

      

style


the type of a document, paragraph, phrase or table (e.g. H1)


      

      

attribute


a property of a paragraph or phrase (e.g. jump)


      

      

macro


a command embedded in a document (e.g. !define)


      

      

variable


a named value (e.g. DOC_NAME)


      

      

block


a section of text enclosed by block and endblock macros


      

      

filter


a rule to use when processing blocks or files (e.g. table)


      

      

module


a file containing reusable information


      

      

library


a directory containing modules


      

      


      For variables, the general conventions are:
      

        

      • lower-case for special symbols (e.g. tm)

      • edit-case for commonly used objects (e.g. Mincom)

      • upper-case for other variables (e.g. DOC_NAME).
      

      The general conventions for other symbols are:
      

        

      • upper-case for paragraph and phrase styles

      • lower-case for other names.
      

      3.2. Paragraph Styles
      

      

      

Tag


Description


      

      

A0 .. A6


appendix heading at level 0..6


      

      

Addr


line in an address


      

      

E


example


      

      

E80


example at least 80 characters per line


      

      

FA


figure anchor


      

      

FOOTER


page footer (in header/footer only)


      

      

FT


figure title


      

      

GL


glossary entry (term and definition are tab separated)


      

      

GLD


definition in a glossary


      

      

GLT


term in a glossary


      

      

H0 .. H6


normal heading at level 0..6


      

      

HEADER


page header (in header/footer only)


      

      

KN


normal paragraph - keep with next


      

      

KP


normal paragraph - keep with previous


      

      

L1 .. L6


paragraph (or plain list item) at level 1..6


      

      

Line


horizontal line


      

      

LF1 .. LF6


first entry in an ordered list at level 1..6


      

      

LI1 .. LI6


enumerated list item at level 1..6


      

      

LN1 .. LN6


next entry in an ordered list at level 1..6


      

      

LU1 .. LU6


unordered list at level 1..6


      

      

N


normal paragraph


      

      

NB


note begin


      

      

NE


note end


      

      

NV


name value


      

      

Note


a single paragraph note


      

      

P0 .. P6


plain heading at level 0..6


      

      

PB


page break


      

      

Sign


signature


      

      

V


verbatim (example with no embedded symbols)


      

      


      Special styles (implicitly terminated) are:
      

      

      

Tag


Description


      

      

>


verbatim paragraph


      

      

. .. ......


paragraph (or plain list item) at level 1..6


      

      

* .. ******


unordered list at level 1..6


      

      

- .. -----


unordered list at level 2..6


      

      

^ .. ^^^^^^


first entry in an ordered list at level 1..6


      

      

+ .. ++++++


next entry in an ordered list at level 1..6


      

      

& .. &&&&&&


labelled list item at level 1..6


      

      


      3.3. Paragraph Attributes
      

      

      

Name


Type


Description


      

      

align


string


alignment of paragraph within text column (1, Full, Left, Right, Center)


      

      

component


string


start a component within a book (see Book Components)


      

      

first


string


indent of first line (in points)


      

      

in


integer


list indent level (for examples only)


      

      

keep_next


boolean


keep this paragraph with the next one


      

      

keep_prev


boolean


keep this paragraph with the previous one


      

      

label


string


label for this paragraph (e.g. "Tip:")


      

      

left


string


left indent (in points)


      

      

noevents


boolean


do not do event processing on this paragraph


      

      

nopb


boolean


do not force this paragraph onto a new page


      

      

notoc


boolean


do not put this in the table of contents


      

      

noid


boolean


do not auto-generate an id for this paragraph


      

      

obj


string


format as the nominated phrase


      

      

orig_style


string


original style (useful in event processing)


      

      

out_style


string


output style to use


      

      

right


string


right indent (in points)


      

      

sp_after


string


space after this paragraph (in points)


      

      

sp_before


string


space before this paragraph (in points)


      

      

tabs


string


comma-separated list of tabstops


      

      

text


string


display the value instead of the existing text


      

      

top


string


place paragraph on a new page (1, 0, Page, Column, Left, Right)


      

      

wide


boolean


span the side-head


      

      


      3.4. Phrase Styles
      

      Leading whitespace is not removed for styles marked with (*).
      

      

      

Tag


Description


      

      

1


1st level emphasis


      

      

2


2nd level emphasis


      

      

3


3rd level emphasis


      

      

A


as-is


      

      

B


bold


      

      

C


source code (*)


      

      

CHAR


escape/special character


      

      

CMD


command


      

      

E


escape/special character


      

      

EMAIL


email address


      

      

EX


example text (*)


      

      

F


filename


      

      

FILE


filename


      

      

I


italic


      

      

IMPORT


figure


      

      

INLINE


embedded target format


      

      

JUMP


same as URL


      

      

L


POD link


      

      

N


normal


      

      

S


text with non-breaking spaces (*)


      

      

SECT


(jump to) document section


      

      

ST


strong emphasis


      

      

SUB


subscript


      

      

SUP


superscript


      

      

U


underline


      

      

URL


Uniform Resource Locator


      

      

X


POD index entry


      

      

Y


symbol (e.g. subroutine)


      

      

Z


zero width character (ala POD)


      

      


      The following styles are only supported in headers/footers:
      

      

      

Tag


Description


      

      

PAGECOUNT


highest page number


      

      

PAGENUM


current page number


      

      

PARALAST


text of last paragraph on page with the nominated style


      

      

PARANUM


paragraph number (e.g. Appendix A)


      

      

PARANUMONLY


paragraph number only (e.g. A)


      

      

PARASHORT


value of short attribute of paragraph


      

      

PARATEXT


paragraph text (e.g. Hardware requirements)


      

      


      The PARA* tags require a comma separated list of paragraph styles to be nominated as the text of the phrase, e.g. {{PARATEXT:H1,A1,P1}}.
      

      3.5. Phrase Attributes
      

      

      

Name


Type


Description


      

      

bgcolor


string


background colour


      

      

bold


boolean


enable bold


      

      

changed


boolean


enable change bars


      

      

class


string


CSS class (for HTML documents)


      

      

color


string


text colour


      

      

doc


string


for SECT, the name of the document containing the section


      

      

expand


boolean


expand object from short to long name


      

      

family


string


font family


      

      

id


string


identifier for this phrase (used by jumps)


      

      

index


string


indexing specification string (MIF only)


      

      

index_type


string


index type (MIF only)


      

      

italics


boolean


enable italics


      

      

jump


string


URL to jump to


      

      

short


string


text to display in header/footer when PARASHORT used


      

      

shrink


boolean


shrink object from long to short name


      

      

size


string


font size


      

      

style


string


custom CSS style information (for HTML documents)


      

      

text


string


display the value instead of the existing text


      

      

underline


boolean


enable underline


      

      

verbatim


boolean


ignore embedded symbols within this paragraph


      

      

xref


string


cross-referencing information (future)


      

      


      3.6. Escapes
      

      

      

Name


Output


Name


Output


Name


Output


      

      

2[


[[


2]


]]


2{


{{


      

      

2}


}}


Aacute


Á


aacute


á


      

      

Acirc


Â


acirc


â


AElig


Æ


      

      

aelig


æ


Agrave


À


agrave


à


      

      

amp


&


Aring


Å


aring


å


      

      

Atilde


Ã


atilde


ã


Auml


Ä


      

      

auml


ä


bullet


.


c


© 


      

      

Ccedil


Ç


ccedil


ç


cent


¢ 


      

      

dagger


^


doubledagger


#


Eacute


É


      

      

eacute


é


Ecirc


Ê


ecirc


ê


      

      

Egrave


È


egrave


è


emdash


--


      

      

emspace


  


endash


-


enspace


  


      

      

Euml


Ë


euml


ë


gt


>


      

      

Iacute


Í


iacute


í


Icirc


Î


      

      

icirc


î


Igrave


Ì


igrave


ì


      

      

Iuml


Ï


iuml


ï


lbrace


{


      

      

lbracket


[


lt


<


nbdash


-


      

      

nbspace


non-breaking space


nl


newline


Ntilde


Ñ


      

      

ntilde


ñ


Oacute


Ó


oacute


ó


      

      

Ocirc


Ô


ocirc


ô


Ograve


Ò


      

      

ograve


ò


Oslash


Ø


oslash


ø


      

      

Otilde


Õ


otilde


õ


Ouml


Ö


      

      

ouml


ö


pound


£ 


quot


"


      

      

r


® 


rbrace


}


rbracket


]


      

      

tab


tab


tm


™ 


Uacute


Ú


      

      

uacute


ú


Ucirc


Û


ucirc


û


      

      

Ugrave


Ù


ugrave


ù


Uuml


Ü


      

      

uuml


ü


yen


¥ 


yuml


ÿ


      

      


      For convenience, variables are provided for: amp, bullet, c, cent, dagger, doubledagger, emdash, endash, emspace, enspace, nbdash, nbspace, nbsp, nl, pound, r, reg, tab, tm, yen.
      

      3.7. Macros
      

      

      

Name


Description


      

      

back


ends a list (from POD)


      

      

begin


begin target-specific output (from POD)


      

      

block


begin a block of text


      

      

build_title


build a title page


      

      

catalog


build a catalog from objects already loaded


      

      

class


define a class of objects


      

      

clear


reset text wrapping around a figure


      

      

continued


continue a heading from a previous page


      

      

cut


ignore text until an = is found at the start of a line (from POD)


      

      

default


set a variable (if not already set)


      

      

define


set a variable


      

      

div


begin a division


      

      

else


begin alternative section


      

      

elseif


same as elsif


      

      

elsif


begin a conditional section


      

      

end


end target-specific output (from POD)


      

      

end_topic


mark the end of a topic


      

      

endblock


end a block of text


      

      

enddiv


end a division


      

      

endif


end conditional text


      

      

endmacro


end a macro definition


      

      

execute


include output from a command


      

      

export


export a variable to the format driver (and/or mark it for later exporting)


      

      

for


insert target-specific output (from POD)


      

      

getcli


extract command-line interface information


      

      

getcode


extract source code (i.e. non-documentation) from a file


      

      

getdoc


extract documentation embedded in source code


      

      

headn


level n heading (n = 1 .. 6) (from POD)


      

      

if


begin conditional text


      

      

import


import an external object (e.g. figure)


      

      

include


include another file


      

      

inherit


inherit entities from a library


      

      

init


initialise variables (before loading configuration files)


      

      

insert


call a macro


      

      

item


label an item in a list (from POD)


      

      

jumps


generate lines of jumps to headings


      

      

line


change message parameters


      

      

macro


begin a macro definition


      

      

message


output a message during execution


      

      

off


disable processing previously specified


      

      

on


specify processing for an event


      

      

output


dynamically change the output file used


      

      

over


begins a list (from POD)


      

      

perlapi


extract API information from a Perl library


      

      

pod


does nothing (from POD)


      

      

restrict


declare a restricted family of variables


      

      

script


execute a line of Perl


      

      

slide_down


decrease heading levels (e.g. H2 -> H3)


      

      

slide_up


increase heading levels (e.g. H2 -> H1)


      

      

subsections


specify the subsections for a topic


      

      

undef


clear a variable


      

      

use


load a library module


      

      


      3.8. Filters
      

      

      

Filter


Description


      

      

about


about section of a document


      

      

abstract


the abstract for a paper


      

      

address


an address


      

      

appendix


change headings to appendix style


      

      

ascii_graphic


fixed-width text, wide enough for ASCII graphics


      

      

box


surround a region of text with a box


      

      

center


centre a region


      

      

changed


mark a block of text as changed


      

      

chapter


chapter of a document (does nothing)


      

      

comment


ignore text


      

      

datestrings


define strings used in dates


      

      

default


provide defaults for a block of variables


      

      

define


define a block of variables


      

      

end


process text at the end


      

      

example


fixed-width text (e.g. source code)


      

      

front


front section of a document


      

      

get


extract embedded documentation


      

      

glossary


glossary section of document (alias for plain)


      

      

hlp_header


table of jumps at the top of a help topic


      

      

hlp_window


contents of a help popup window


      

      

inline


embed text into target format (e.g. HTML)


      

      

langdefs


define vgrind-like language definitions


      

      

links


define external links for a document (including stylesheets)


      

      

meta


define meta information for a document


      

      

namevalues


format a set of name-value pairs (e.g. as used in a title block)


      

      

nofill


a set of lines


      

      

note


a note


      

      

plain


change headings to plain style


      

      

pod


embedded POD


      

      

quote


a quotation


      

      

script


execute text as a Perl script


      

      

sdf


apply arbitrary phrase attributes to text


      

      

sections


paragraphs are sections


      

      

simple


generic filter for building others


      

      

stylesheet


define a stylesheet which should be inline in the HTML output


      

      

table


tabular data


      

      

template


alias for inline with expand set to true


      

      

title


title block for a memo, fax or minutes


      

      

topics


include a set of sub-topics


      

      

verbatim


fixed-width text, ignoring embedded symbols


      

      


      Classes and Programming Languages can also be used as filters.
      

      3.9. Figures
      

      Extension search rules:
      

      

      

When generating


The search order is


      

      

PostScript


epsi, eps, wmf, mif, gif


      

      

HTML


jpeg, jpg, png, gif


      

      

Windows Help


bmp


      

      


      import macro parameters:
      

      

      

Name


Description


      

      

alt


alternate text to display (ala HTML)


      

      

align


alignment (Left, Center, Right, Inner, Outer)


      

      

base


the prefix to prepend to the figure pathname to get the location needed for the HTML output


      

      

border


the border width in pixels


      

      

height


explicit height measurement (MIF only)


      

      

jump


the URL to jump to


      

      

listitem


the list indent level (e.g. 1)


      

      

mif_figure


the tag before the figure in the MIF source (only needed if more than one figure in the MIF file)


      

      

position


vertical position (Below, Top, Bottom)


      

      

title


figure caption


      

      

wide


figure straddles the side head area of the page


      

      

width


explicit width measurement (MIF only)


      

      

wrap_text


wrap text around a figure (ignored for HTML)


      

      


      Default conversion rules (from sdf.ini):
      

      

      

When generating


Create


From


Using the command


      

      

html


gif


eps


ps2gif -crop $source


      

      

html


gif


ps


ps2gif -crop $source


      

      

html


gif


prn


prn2ps -ops $source; ps2gif -crop $base.ps; rm $base.ps


      

      

ps


eps


ps


ps2epsi $source $dest


      

      

ps


eps


prn


prn2ps -ops $source; ps2epsi $base.ps $dest; rm $base.ps


      

      


      3.10. Tables
      

      table filter parameters:
      

      

      

Name


Description


      

      

align


alignment of table: one of Left, Center, Right, Inner, Outer


      

      

bgcolor


background colour for a table (HTML only)


      

      

bmargin


default bottom margin for table cells (MIF only)


      

      

cellpadding


padding size for table cells (HTML only)


      

      

cellspacing


spacing size between table cells (HTML only)


      

      

colaligns


a comma-separated list of horizontal alignments values (Left, Center, Right) for columns; alternatively, a single word containing the letters L, C and R


      

      

coltags


a comma-separated list of phrase styles to apply to columns


      

      

colvaligns


a comma-separated list of vertical alignments values (Top, Middle, Bottom, Baseline) for columns; alternatively, a single word containing the letters T, M, B and L


      

      

delete


a comma-separated list of columns to delete


      

      

footings


the number of footing rows at the end of the table


      

      

format


a comma-separated list of column width specifications; alternatively, a single number where each digit represents 10% of the space available to the table


      

      

groups


pattern of group-style rows (default is /:$/)


      

      

headings


the number of heading rows at the top of the table


      

      

keepindents


keep leading whitespace in cells


      

      

landscape


display the table in landscape mode (MIF only)


      

      

listitem


the list indent level (e.g. 1) of this table


      

      

lmargin


default left margin for table cells (MIF only)


      

      

narrow


if set, the table will only be as wide as required; otherwise the table will span the available space


      

      

niceheadings


set to 0 to disable _ to space conversion in headings


      

      

nocalcs


set to 0 to disable calculation processing within a table


      

      

noheadings


suppress headings in output


      

      

objects


alias for coltags (coltags is preferred)


      

      

oncell


Perl code to execute for each cell (internal use only!)


      

      

parseline


column headings parsing line (if not the first row in the text)


      

      

placement


vertical placement of table: one of Float, Pagetop, Columntop, Lefttop, Righttop (MIF only)


      

      

rmargin


default right margin for table cells (MIF only)


      

      

select


a comma-separated list of columns to display


      

      

sort


a comma-separated list of columns to sort the data rows by


      

      

style


overall look of the table (columns, rows, grid, plain, shade)


      

      

tags


alias for coltags (coltags is preferred)


      

      

title


table caption


      

      

tmargin


default top margin for table cells (MIF only)


      

      

type


alias for style (style is preferred)


      

      

where


an expression to filter the data rows with


      

      

wide


table straddles the side head area of the page


      

      

wrap


the number of data rows to display in a physical row


      

      


      Column width specifications:
      

      

      

Value


Meaning


      

      

30pt


an exact size (other supported units are cm, mm, " and in)


      

      

30%


a percentage of the size available


      

      

30


a percentage of the size available (% is implicit)


      

      

10-20


dynamic size between 10% and 20% of the total width


      

      

-20


dynamic size between 0% and 20% of the total width


      

      

10-


dynamic size between 10% and 100% of the total width


      

      

-


dynamic size between 0% and 100% of the total width


      

      

3*


3 units of the remaining space


      

      

*


same as 1*


      

      


      = can be used in place of - to get equalised column widths.
      

      Cell attributes:
      

      

      

Name


Value


      

      

align


horizontal alignment (Left, Center, Right)


      

      

angle


angle of text (0, 90, 180, 270)


      

      

bgcolor


background colour of cell


      

      

bruling


ruling setting for bottom of cell


      

      

cols


the number of columns this cell spans (default is 1)


      

      

fill


background colour fill % (100, 90, 70, 50, 30, 10, 3)


      

      

lruling


ruling setting for left of cell


      

      

nowrap


disable word wrap for this cell


      

      

paratag


paragraph style to apply to cell text (future)


      

      

rows


the number of rows this cell spans (default is 1)


      

      

rruling


ruling setting for right of cell


      

      

sdf


treat the cell text as SDF (rather than as phrase text)


      

      

tag


phrase tag to apply to cell text


      

      

truling


ruling setting for top of cell


      

      

valign


vertical alignment (Top, Middle, Bottom, Baseline)


      

      


      Permitted ruling values: Vthin, Thin, Medium, Thick, Double.
      

      3.11. Classes
      

      Data fields for the predefined classes are:
      

      

      

Field


Tag


Description


      

      

organisations:


 


 


      

      

Name


ORG


organisation name


      

      

Long


ORGN


long form of organisation name


      

      

Jump


 


URL for organisation


      

      

products:


 


 


      

      

Name


PRD


product name


      

      

Jump


 


URL for product


      

      

references:


 


 


      

      

Reference


REF


document code


      

      

Document


DOC


document title


      

      

Jump


 


URL for document


      

      

Version


 


version number


      

      

Status


 


status (e.g. Draft, Review or Final)


      

      

terms:


 


 


      

      

Term


TERM


term, acronym or abbreviation


      

      

Description


 


explanation


      

      

Jump


 


URL for term


      

      


      The REFNUMONLY tag can be used to mark a REF phrase where only the trailing number is output.
      

      Calculated fields for the references class:
      

      

      

Name


Description


      

      

XXX


if a matching xxx file is found, an image which jumps to that file


      

      

Cite


a string of the form [n]


      

      

Date


the date of the html file


      

      

Pages


the number of pages in the PostScript document


      

      

Printdoc


an image which launches the /cgi-bin/printdoc/ CGI script


      

      

Printer


alias for Printdoc


      

      


      Parameters of class filters:
      

      

      

Name


Type


Description


      

      

cited


boolean


number these objects as the cited ones (for [1] style references)


      

      

colaligns


string


a comma-separated list of horizontal alignments  values (Left, Center, Right) for columns; alternatively, a single word containing the letters L, C and R can be used for the value


      

      

columns


string


comma-separated list of attributes to display in table


      

      

colvaligns


string


a comma-separated list of vertical alignments  values (Top, Middle, Bottom, Baseline) for columns; alternatively, a single word containing the letters T, M, B and L can be used for the value


      

      

compact


boolean


display in a compact table, (make cellpadding data       boolean      define objects but do not display them


      

      

delete


string


a comma-separated list of columns to delete


      

      

headings


boolean


display the column headings


      

      

root


string


string to prepend to Jump attribute, if any


      

      

select


string


a comma-separated list of columns to display


      

      

sort


string


comma-separated list of columns to sort by


      

      

style


string


table style to use (the default is plain)


      

      

 


 


and cellspacing both equal to zero)


      

      

variables


boolean


define a variable for each object; the variable name is derived from the object name with underscores replacing non-alphanumeric characters


      

      

where


string


filter the rows using the nominated expression


      

      

wide


boolean


use sidehead when formatting on paper


      

      

wrap


integer


number of logical rows to place on a physical row


      

      


      3.12. Document Variables/Macros
      

      Controls
      

      

      

Name


Type


Description


      

      

DOC_ADMIN_LOGO


string


logo to use in administration document styles


      

      

DOC_ADMIN_LOGO_BASE


string


base directory for DOC_ADMIN_LOGO


      

      

DOC_APPROVE


string


person approving the document


      

      

DOC_APPROVE2


string


2nd person approving the document


      

      

DOC_APPROVE3


string


3rd person approving the document


      

      

DOC_AUTHOR


string


author of document


      

      

DOC_AUTHOR2


string


2nd author of document


      

      

DOC_AUTHOR3


string


3rd author of document


      

      

DOC_CODE


string


document code (*)


      

      

DOC_COMPONENT


string


current component type within a book


      

      

DOC_COMPONENT_LOGO


string


logo to use for components within a book


      

      

DOC_COVER


string


logical name of the cover page to use (e.g. original, project, manual, paper)


      

      

DOC_DISTRIBUTION


string


document distribution


      

      

DOC_HTML_LOGO


string


logo to use in HTML output


      

      

DOC_HTML_LOGO_BASE


string


base directory for HTML_LOGO


      

      

DOC_ID_SEP


string


separator used within DOC_ID


      

      

DOC_IX


boolean


build an index


      

      

DOC_LOF


boolean


build a list of figures


      

      

DOC_LOF_TITLE


string


list of figures title


      

      

DOC_LOGO


string


logo to use for document


      

      

DOC_LOGO_BASE


string


base directory for DOC_LOGO


      

      

DOC_LOT


boolean


build a list of tables


      

      

DOC_LOT_TITLE


string


list of tables title


      

      

DOC_MANUAL_LOGO


string


logo to use when generating paper manuals


      

      

DOC_NAME


string


document name, e.g. "SDF 2.000"


      

      

DOC_OWNER


string


person or company owning the copyright


      

      

DOC_PRODUCT


string


for man pages, the center string in the header


      

      

DOC_PROJECT


string


orginating project of document


      

      

DOC_SECTION


integer


for man pages, the section number


      

      

DOC_STATUS


string


status of document (*)


      

      

DOC_TITLE_LOGO


string


logo used in the title of a PostScript document


      

      

DOC_TOC


integer


table of contents level


      

      

DOC_TOC_GRAPHIC


string


graphic to include in TOC title


      

      

DOC_TOC_TITLE


string


table of contents title


      

      

DOC_TOPIC_LOGO


string


logo to use in HTML topics mode output


      

      

DOC_TOPIC_LOGO_BASE


string


base directory for DOC_TOPIC_LOGO


      

      

DOC_TWO_SIDES


boolean


build a two-sided document


      

      

DOC_TYPE


string


document type, e.g. "User Guide"


      

      

DOC_URL


string


URL of document


      

      

DOC_VERSION


string


version number of document (*)


      

      

Macros:


 


 


      

      

DOC_COMPONENT_BEGIN


macro


hook to initialise things before book component processing begins


      

      

DOC_COMPONENT_END


macro


hook to finalise things after book component processing ends


      

      

DOC_OFFICES


macro


for manuals, the text to put after the inside front cover


      

      

DOC_RECIPIENTS


macro


table of controlled copy recipients


      

      

DOC_TRADEMARKS


macro


text specifying trademarks used in document


      

      


      If the variables marked with (*) are not defined, build_title sets them using the references data, if possible.
      

      Information
      

      

      

Name


Type


Description


      

      

DOC_BASE


string


the base (filename) of the current document


      

      

DOC_COLUMN_WIDTH


integer


width of a text column (in points)


      

      

DOC_DIR


string


the directory of the current document


      

      

DOC_EXT


string


the extension of the current document


      

      

DOC_FULL_WIDTH


integer


width of text area including the side-head (in points)


      

      

DOC_ID


string


combination of DOC_CODE and DOC_VERSION


      

      

DOC_MODIFIED


datetime


the most recent modification time of files visited so far


      

      

DOC_PAGE_HEIGHT


integer


height of page (in points)


      

      

DOC_PAGE_WIDTH


integer


width of page (in points)


      

      

DOC_PAGED


boolean


output is paged, not continuous


      

      

DOC_PATH


string


the full pathname of the current document


      

      

DOC_SHORT


string


the base and extension of the current document


      

      

DOC_START


datetime


the time document conversion started


      

      

DOC_TEXT_HEIGHT


integer


height of text area (in points)


      

      

DOC_TEXT_WIDTH


integer


width of text area available for text columns (in points)


      

      

DOC_TITLE


string


combination of DOC_NAME and DOC_TYPE


      

      

MODIFIED_DATE


string


alias for DATE:DOC_MODIFIED


      

      

File:


 


 


      

      

FILE_BASE


string


base part of current filename (e.g. mydoc)


      

      

FILE_DIR


string


directory of current filename (e.g. /doc/sdf)


      

      

FILE_EXT


string


extension of current filename (e.g. sdf)


      

      

FILE_MODIFIED


datetime


time when this file was last modified


      

      

FILE_PATH


string


current pathname (e.g. /doc/sdf/mydoc.sdf)


      

      


      3.13. Option Variables
      

      These variables (except OPT_NOBARS) give the values of command-line options. Variables marked with a (*) can be set via the init macro on the top line of a document:
      

      

      

Name


Type


Description


      

      

OPT_CONFIG


string


configuration library (*)


      

      

OPT_DRIVER


string


name of driver used to convert documents


      

      

OPT_EXT


string


output extension


      

      

OPT_HEAD_LEVEL


integer


level to start headings at


      

      

OPT_HEAD_LOOK


string


look for headings


      

      

OPT_LOCALE


string


locale


      

      

OPT_LOOK


string


look (*)


      

      

OPT_NOBARS


boolean


disable change bars (*)


      

      

OPT_NUMBER


integer


line numbering fequency


      

      

OPT_PAGE_SIZE


string


page size setting (default is global) (*)


      

      

OPT_PP_xxx


boolean


set if xxx post-processing requested


      

      

OPT_REPORT


string


report to run


      

      

OPT_SPLIT_LEVEL


integer


level to split headings at for topics mode


      

      

OPT_STYLE


string


document style (*)


      

      

OPT_TARGET


string


target format


      

      

OPT_WIDTH


integer


width for txt output (default is 70) (*)


      

      


      These variables can only be set within look libraries:
      

      

      

Name


Type


Description


      

      

OPT_BORDERS


integer


high-level header/footer border control (0=none; 1=above footer,below header; 2=above footer,above & below header)


      

      

OPT_COLUMNS


integer


number of columns in text area (default is 1)


      

      

OPT_COLUMN_GAP


dimension


gap between columns in text area


      

      

OPT_COMPONENT_COVER


boolean


give book components a cover page


      

      

OPT_HEADINGS


integer


size in lines (0..4) of headers/footers (Note: for values 2..4, header size is 2)


      

      

OPT_IX_COLUMNS


integer


number of columns in text area in the index (default is 1)


      

      

OPT_IX_COLUMN_GAP


dimension


gap between columns in text area in the index


      

      

OPT_IX_SIDEHEAD_GAP


dimension


width between side-head and text area in the index


      

      

OPT_IX_SIDEHEAD_WIDTH


dimension


width of side-head in the index


      

      

OPT_LIST_INDENT


dimension


size of each list indent in points


      

      

OPT_MARGIN_BOTTOM


string


size of margin below the footer, if any


      

      

OPT_MARGIN_INNER


string


size of inner margin


      

      

OPT_MARGIN_OUTER


string


size of outer margin


      

      

OPT_MARGIN_TOP


string


size of margin above the header, if any


      

      

OPT_NUMBER_PER_COMPONENT


boolean


number figures, etc. per component


      

      

OPT_SIDEHEAD_GAP


dimension


width between side-head and first text column


      

      

OPT_SIDEHEAD_WIDTH


dimension


width of side-head


      

      


      3.14. Page Layout Variables
      

      Page variables can only be set within look libraries.
      

      Page tags:
      

      

      

Page


Usage


      

      

FIRST


the first page in the document


      

      

RIGHT


the page used for single-sided documents and the right hand side of double-sided documents


      

      

LEFT


the left hand side of double-sided documents; ignored for single-sided documents


      

      


      In the table below, frl is either:
      

        

      • FIRST, RIGHT or LEFT, or

      • COMPONENT_FRL where:
          

        • COMPONENT is the name of the component in upper-case (refer to Book Components)

        • FRL is FIRST, RIGHT or LEFT.
      

      If a component does not have a component-specific macro/variable defined, then the generic macro/variable is used.
      

      

      

Name


Type


Description


      

      

PAGE_frl_BACKGROUND


string


background image name


      

      

PAGE_frl_FOOTER_BORDER


string


border specification


      

      

PAGE_frl_FOOTER_GAP


dimension


gap between text area and footer area


      

      

PAGE_frl_FOOTER_HEIGHT


dimension


height of footer area


      

      

PAGE_frl_FOOTER_INNERn


string


inner text of line n (0..3) of footer


      

      

PAGE_frl_FOOTER_CENTERn


string


centre text of line n (0..3) of footer


      

      

PAGE_frl_FOOTER_OUTERn


string


outer text of line n (0..3) of footer


      

      

PAGE_frl_HEADER_BORDER


string


border specification


      

      

PAGE_frl_HEADER_GAP


dimension


gap between header area and text area


      

      

PAGE_frl_HEADER_HEIGHT


dimension


height of header area


      

      

PAGE_frl_HEADER_INNERn


string


inner text of line n (1..2) of header


      

      

PAGE_frl_HEADER_CENTERn


string


centre text of line n (1..2) of header


      

      

PAGE_frl_HEADER_OUTERn


string


outer text of line n (1..2) of header


      

      


      When FrameMaker is being used to generate PostScript, the background image name is mapped to a master page called backgrnd within a file called backgrnd.mif. At the moment, objects from the master page (excluding TextRects) are directly transferred to the generated MIF file. This means that objects in the lower right hand corner of an A4 master page will not will be positioned nicely if the paper size is changed to A5, say.
      

      A border specification string is a comma-separated list of attributes which collectively describe the border. The format of each attribute is name[=value]. The supported attributes are:
      

        

      • top - a line above the area

      • bottom - a line below the area

      • box - a box around the area

      • radius - for a box, the radius of the corner.
      

      For top, bottom and box, the value of the attribute is the line width in points.
      

      3.15. Miscellaneous Variables/Macros
      

      Controls
      

      

      

Name


Type


Description


      

      

Processing:


 


 


      

      

DEFAULT_LOCALE


string


default OPT_LOCALE (set in sdf.ini)


      

      

DEFAULT_LOOK


string


default OPT_LOOK (set in sdf.ini)


      

      

DEFAULT_TAB_SIZE


integer


default tab size (initially 8)


      

      

DEFAULT_TABLE_STYLE


string


default style for tables (initially columns)


      

      

DEFAULT_XREF_STYLE


string


default style for cross-references (initially sections)


      

      

Link expansion formats:


 


 


      

      

FORMAT_LINK_PAGE


string


default is: the $page manpage


      

      

FORMAT_LINK_PAGE_ENTRY


string


default is: the $entry entry in the $page manpage


      

      

FORMAT_LINK_PAGE_SECTION


string


default is: the section on "$sect" in the $page manpage


      

      

FORMAT_LINK_SECTION


string


default is: the section on "$sect"


      

      

HTMLDOC generation:


 


 


      

      

HTMLDOC


boolean


generate HTML ready for HTMLDOC


      

      

HTMLDOC_OPTS


string


tuning options to pass to HTMLDOC


      

      


      Information
      

      

      

Name


Type


Description


      

      

Package:


 


 


      

      

SDF


phrase


PRD:SDF


      

      

SDF_BUGS


phrase


EMAIL:sdf-bugs@mincom.com


      

      

SDF_FTP


string


URL for SDF's FTP site


      

      

SDF_HOME


string


library/configuration directory


      

      

SDF_USERS


phrase


EMAIL:sdf-users@mincom.com


      

      

SDF_VERSION


string


product version string (e.g. 2.000 beta1)


      

      

SDF_WWW


string


URL for SDF's home page


      

      

Macros for default.sdg:


 


 


      

      

SDG_DESCRIPTION_POST


macro


finalisation after Description


      

      

SDG_DESCRIPTION_PRE


macro


initialisation before Description


      

      

SDG_BEGIN


macro


hook for things before extracted text


      

      

SDG_END


macro


hook for things after extracted text


      

      

SDF_OPT_HELP


macro


text explaining help option


      

      

SDF_OPT_STD


macro


text explaining standard options


      

      

Old macro names:


 


 


      

      

BUILD_TITLE


string


provided for backwards-compatibility


      

      

END_TOPIC


string


provided for backwards-compatibility


      

      

SLIDE_DOWN


string


provided for backwards-compatibility


      

      

SLIDE_UP


string


provided for backwards-compatibility


      

      

SDF_DESCRIPTION_POST


macro


provided for backwards-compatibility


      

      

SDF_DESCRIPTION_PRE


macro


provided for backwards-compatibility


      

      


      3.16. Programming Languages
      

      

      

Language


Names


      

      

C


c


      

      

C++


c++, cpp, hpp, cc, h


      

      

COBOL


cobol


      

      

CORBA IDL


idl


      

      

FORTRAN


fortran, f77, fc, f, for


      

      

Java


java


      

      

MIMS COBOL


mimscobol, pcom, precom


      

      

Object Pascal


delphi, pascal, pas, int


      

      

Perl


perl, pl, pm, sdp, sdr


      

      

Python


python, jpython, py


      

      

Simple Document Format


sdf, sdm, sds, sdn, sdl, sde


      

      

Unix shell


sh


      

      

Unix c-shell


csh


      

      


      Language names are case insensitive.
      

      3.17. Colours
      

      For PS (i.e. MIF) generation, the supported colour values are Black, White, Red, Green, Blue, Yellow, Cyan and Magenta. If a different colour is specified, it is ignored.
      

      For HTML generation, any of the HTML colours names (including those supported for PS generation) or the "#rrggbb" form can be used. Useful variables are:
      

      

      

Name


Value


Name


Value


      

      

COLOR_WHITE


'ffffff'


COLOR_BLACK


'000000'


      

      

COLOR_RED


'ff0000'


COLOR_GREEN


'00ff00'


      

      

COLOR_BLUE


'0000ff'


COLOR_YELLOW


'ffff00'


      

      

COLOR_MAGENTA


'ff00ff'


COLOR_CYAN


'00ffff'


      

      

COLOR_GREY


'c0c0c0'


      

      


      3.18. Expression Formats
      

      

      

Name


Description


      

      

Strings:


 


      

      

LOWER


convert a string to lowercase


      

      

LOWER1


convert the first character to lowercase


      

      

UPPER


convert a string to uppercase


      

      

UPPER1


convert the first character to uppercase


      

      

Dates:


 


      

      

CONCISE


alias for FORMAT_SDATE


      

      

DATE


format to a date only


      

      

DATETIME


format to a complete date-time format


      

      

FULL


alias for FORMAT_DATETIME


      

      

SDATE


format to a concise date only


      

      

TIME


format to a time only


      

      

YEAR


format to a 4-digit year


      

      


      Expression format XXX can be changed/defined via the FORMAT_XXX variable.
      

      3.19. Modules
      

      

      

Name


Description


      

      

bugtrack


extensions for bug tracking


      

      

defines


simplified product declaration/definition


      

      

delphi


extensions for delphi 1.x documentation


      

      

homepage


extensions for making SDF-like home pages easier to author


      

      

misc


miscellaneous goodies


      

      

objects


IT-related objects


      

      

testcase


extensions for test case documentation


      

      

usecases


extensions for Use Case documentation


      

      


      3.20. Book Components
      

      

      

Name


Meaning


      

      

front


the cover component


      

      

pretoc


components before the contents


      

      

toc


the table of contents


      

      

lof


the list of figures


      

      

lot


the list of tables


      

      

prechapter


components before the chapters


      

      

chapter


a normal chapter


      

      

appendix


an appendix


      

      

preix


components before the index


      

      

ix


the index


      

      


      3.21. Event Processing
      

      Supported symbols within actions:
      

      

      

Type


Symbols


      

      

paragraph


$style, $text, %attr, &PrependText, &AppendText, $level, $prev_style, $prev_text, %prev_attr


      

      

phrase


$style, $text, %attr, $append


      

      

macro


$name, $args


      

      

filter


$name, $params


      

      

table


$style, %param


      

      


      Special symbol meanings:
      

      

      

Symbol


Meaning


      

      

paragraph:


 


      

      

&PrependText


a subroutine to add paragraphs before this one


      

      

&AppendText


a subroutine to add paragraphs after this one


      

      

$level


the current heading level (before this paragraph)


      

      

$prev_style


the style of the previous paragraph


      

      

$prev_text


the text of the previous paragraph


      

      

%prev_attr


the attributes of the previous paragraph


      

      

phrase:


 


      

      

$append


text to append onto the end of the phrase


      

      


      

      

      

      Home | Catalog
      

      

      




string


default style for cross-references (initiallysdf-2.001/doc/quickref/index.html010044400042570001753000002337000672242332300164770ustar00iancmtr00000400000236






SDF 2.001: SDF Quick Reference




      

      

      Home | Catalog
      

      

      

      

      

      SDF Quick Reference
      

      MTR-SDF-0003.002 (Draft)
      

      Ian Clatworthy
      

      25 May 1999
      

      

      

      

      

      Table of Contents
      


      

      

      

      1. SDF - The Package
      

      1.1. Programs
      

      

      

Name


Purpose


      

      

sdf


convert SDF files to other formats


      

      

sdfapi


extract the Application Programming Interface from source code


      

      

sdfbatch


generate FrameMaker batch files


      

      

sdfcli


extract the Command Line Interface from a utility


      

      

sdfget


extract documentation embedded in source code


      

      

sdftest


execute SDF regression tests


      

      

sdngen


build an SDF tuning module from a FrameMaker template


      

      

fm2ps


convert FrameMaker files to PostScript (a wrapper for sdfbatch)


      

      

pod2sdf


convert POD to SDF


      

      

poddiff


compare POD files and report differences


      

      

prn2ps


convert Windows PostScript to Unix PostScript


      

      


      Environment variables used are:
      

      

      

Name


Description


      

      

SDFBIN


on MS-DOS/Windows systems, the directory containing SDF's scripts, (e.g. c:\sdf\bin\)


      

      

SDFOPTS


options always used by sdf (e.g. -Yc:\mysdflib)


      

      


      1.2. File Extension Conventions
      

      

      

Ext.


Format


Usage


Ext.


Format


Usage


      

      

ini


INI


configuration file


sde


SDF


SDF end module


      

      

sdf


SDF


normal SDF file


sdg


SDG


sdfget report


      

      

sdl


SDF


SDF locale


sdm


SDF


SDF module


      

      

sdn


SDF


SDF tuning module


sdo


TBL


SDF object register


      

      

sdp


Perl


SDF plug-in


sdr


Perl


SDF report


      

      

sds


SDF


SDF style module


sdt


HTML


SDF template


      

      


      

      2. sdf - The Program
      

      2.1. Command-line Options
      

      

      

Option


Long name


Description


      

      

-2


--format


the output format you want


      

      

-a


--parameters


parameters for the pre-filter


      

      

-c


--config


configuration library


      

      

-d


--driver


format driver - default is expand


      

      

-f


--flag


define flags (flag xxx maps to variable DOC_XXX)


      

      

-g


--get_report


prefilter using sdfget with the report specified


      

      

-h


--help


display help on options or a single option


      

      

-k


--look


look library


      

      

-l


--log_ext


log file extension (default is log)


      

      

-n


--split_level


heading level to autosplit into topics


      

      

-o


--out_ext


output file extension (default is out)


      

      

-p


--prefilter


pre-filter input file from each argument


      

      

-r


--report


report to pre-filter the input with


      

      

-s


--style


style of document


      

      

-t


--target


logical target format


      

      

-u


--uses


modules to use


      

      

-v


--verbose


verbose mode


      

      

-w


--width


width for text-based outputs


      

      

-y


--post_filter


filter to post-filter the output with


      

      

-z


--post_process


list of post processing actions to do


      

      

-D


--variable


define variables


      

      

-H


--head_level


initial heading level


      

      

-I


--include_path


search path for include files, templates, etc.


      

      

-K


--head_look


heading look (H, A or P)


      

      

-L


--locale


locale


      

      

-N


--line_numbers


number lines in pretty-printed source code


      

      

-O


--out_dir


output to input file's (or explicit) directory


      

      

-P


--plang


pre-filter as a programming language


      

      

-S


--page_size


page size for paper documents


      

      

-T


--trace_levels


debugging trace levels


      

      

-Y


--library_path


path to search for libraries and modules


      

      


      2.2. Useful Command Lines
      

      Generate format xxx for mydoc.sdf:
      

             sdf -2xxx mydoc

      

      Generate PDF via a FrameMaker book (on Unix):
      

             sdf -2book -zpdf mydoc

      

      Generate a man page:
      

             sdf -2man mydoc | nroff -man > mydoc.1

      

      Spell check a document:
      

             sdf mydoc | spell

      

      Pretty-print lang source code in format xxx:
      

             sdf -2xxx -Plang mysource
       sdf -2xxx -P mysource.lang
       sdf -2xxx -P -N5 mysource.lang   (with line numbering)

      

      Generate reference documentation in format xxx for mymod.sdm:
      

             sdf -2xxx mymod.sdm

      

      Generate format xxx for a table:
      

             sdf -2xxx mydata.tbl
       sdf -2xxx -aformat='15,75,10' mydata.tbl

      

      Generate format xxx for a MIMS topic, chapter or specification:
      

             sdf -2xxx +mt mydoc
       sdf -2xxx +mc mydoc
       sdf -2xxx +ms mydoc

      

      2.3. Target Formats
      

      The format naming conventions are:
      

        

      • xxx - generate (logical) format xxx

      • xxx_yyy - generate format xxx via yyy

      • xxx_ - generate format xxx directly.
      

      sdf's -2 option is used to specify the target format.
      

      2.3.1. Logical Formats
      

      

      

Format


Maps to


Format


Maps to


Format


Maps to


      

      

_dir


html_dir


book


ps_fmbook


doc


doc_fm


      

      

dvi


dvi_sgml


expand


sdf_expand


fvo


fvo_fm


      

      

hlp


hlp_mif


html


html_


htx


htx_


      

      

info


info_sgml


latex


latex_sgml


lyx


lyx_sgml


      

      

man


man_pod


mf6


mf6_


mif


mif_


      

      

pdf


pdf_mif


pod


pod_


ps


ps_fm


      

      

raw


sdf_raw


rtf


rtf_fm


sgml


sgml_


      

      

topics


html_topics


txt


txt_


      

      


      2.3.2. Explicit Formats
      

      

      

Format


Generates


      

      

doc_fm


Frame binary format via FrameMaker


      

      

dvi_sgml


DVI format via SGML


      

      

fvo_fm


FrameViewer format via FrameMaker


      

      

hlp_mif


Windows Help input files via MIF


      

      

html_


a HTML document


      

      

html_dir


an SDF directory in HTML


      

      

html_fm


a HTML document via FrameMaker


      

      

html_topics


HTML topics


      

      

htx_


MIMS HTX format


      

      

info_sgml


GNU info format via SGML


      

      

latex_


LaTeX format


      

      

latex_pod


LaTeX format via POD


      

      

latex_sgml


LaTeX format via SGML


      

      

lyx_sgml


a LyX file via SGML


      

      

man_pod


Man page format via POD


      

      

mf6_


MIMS F6 help format


      

      

mif_


Frame MIF format


      

      

pdf_html


PDF via HTMLDOC


      

      

pdf_mif


PostScript and PDF via FrameMaker


      

      

pod_


POD format


      

      

ps_fm


PostScript via FrameMaker


      

      

ps_fmbook


PostScript via a FrameMaker book


      

      

ps_html


PostScript via HTMLDOC


      

      

ps_pod


PostScript via POD


      

      

ps_sgml


PostScript via SGML


      

      

rtf_fm


RTF format via FrameMaker


      

      

rtf_mif


RTF format via MIF


      

      

rtf_sgml


RTF format via SGML format


      

      

sdf_expand


expanded SDF


      

      

sdf_raw


raw SDF


      

      

sgml_


SGML format


      

      

txt_


plain text format


      

      

txt_fm


plain text format via FrameMaker


      

      

txt_pod


plain text format via POD


      

      


      2.4. Document Styles
      

      

      

Style


Description


Style


Description


      

      

document


normal document (default)


fax


fascimile


      

      

listing


program listing


manual


user manual


      

      

memo


memorandum


minutes


minutes of a meeting


      

      

newslettr


newsletter


paper


technical paper


      

      


      2.5. Looks
      

      

      

Style


Description


      

      

fancy


look useful for manuals


      

      

infomap


Information Mapping™ 


      

      

overhead


look useful for overhead transparencies


      

      

plain


alias for simple


      

      

simple


look useful for normal documents


      

      


      2.6. Page Sizes
      

      

      

Name


Width


Height


Name


Width


Height


      

      

global


21.0cm


11.0in


A3


29.7cm


42.0cm


      

      

A4


21.0cm


29.7cm


A5


14.8cm


21.0cm


      

      

B4


25.7cm


36.4cm


B5


17.6cm


25.0cm


      

      

letter


8.5in


11.0in


legal


8.5in


14.0in


      

      

tabloid


11.0in


17.0in


      

      


      Rotated sizes are named with an appended R (e.g. A4R).
      

      2.7. Reports
      

      

      

Name


Description


      

      

sdf_dir


generate a directory tree of nested SDF documents


      

      


      2.8. Pre-filters
      

      Files with extensions matching a pre-filter name or alias have the name filter applied.
      

      

      

Name


Aliases


Name


Aliases


      

      

table


tbl


template


sdt


      

      

module


sdm


pod


pm,PL


      

      


      

      3. SDF - The Language
      

      3.1. Concepts and Conventions
      

      

      

Term


Description


      

      

paragraph


the basic building block of documents


      

      

phrase


a section of text delimited by {{ and }} within a paragraph


      

      

style


the type of a document, paragraph, phrase or table (e.g. H1)


      

      

attribute


a property of a paragraph or phrase (e.g. jump)


      

      

macro


a command embedded in a document (e.g. !define)


      

      

variable


a named value (e.g. DOC_NAME)


      

      

block


a section of text enclosed by block and endblock macros


      

      

filter


a rule to use when processing blocks or files (e.g. table)


      

      

module


a file containing reusable information


      

      

library


a directory containing modules


      

      


      For variables, the general conventions are:
      

        

      • lower-case for special symbols (e.g. tm)

      • edit-case for commonly used objects (e.g. Mincom)

      • upper-case for other variables (e.g. DOC_NAME).
      

      The general conventions for other symbols are:
      

        

      • upper-case for paragraph and phrase styles

      • lower-case for other names.
      

      3.2. Paragraph Styles
      

      

      

Tag


Description


      

      

A0 .. A6


appendix heading at level 0..6


      

      

Addr


line in an address


      

      

E


example


      

      

E80


example at least 80 characters per line


      

      

FA


figure anchor


      

      

FOOTER


page footer (in header/footer only)


      

      

FT


figure title


      

      

GL


glossary entry (term and definition are tab separated)


      

      

GLD


definition in a glossary


      

      

GLT


term in a glossary


      

      

H0 .. H6


normal heading at level 0..6


      

      

HEADER


page header (in header/footer only)


      

      

KN


normal paragraph - keep with next


      

      

KP


normal paragraph - keep with previous


      

      

L1 .. L6


paragraph (or plain list item) at level 1..6


      

      

Line


horizontal line


      

      

LF1 .. LF6


first entry in an ordered list at level 1..6


      

      

LI1 .. LI6


enumerated list item at level 1..6


      

      

LN1 .. LN6


next entry in an ordered list at level 1..6


      

      

LU1 .. LU6


unordered list at level 1..6


      

      

N


normal paragraph


      

      

NB


note begin


      

      

NE


note end


      

      

NV


name value


      

      

Note


a single paragraph note


      

      

P0 .. P6


plain heading at level 0..6


      

      

PB


page break


      

      

Sign


signature


      

      

V


verbatim (example with no embedded symbols)


      

      


      Special styles (implicitly terminated) are:
      

      

      

Tag


Description


      

      

>


verbatim paragraph


      

      

. .. ......


paragraph (or plain list item) at level 1..6


      

      

* .. ******


unordered list at level 1..6


      

      

- .. -----


unordered list at level 2..6


      

      

^ .. ^^^^^^


first entry in an ordered list at level 1..6


      

      

+ .. ++++++


next entry in an ordered list at level 1..6


      

      

& .. &&&&&&


labelled list item at level 1..6


      

      


      3.3. Paragraph Attributes
      

      

      

Name


Type


Description


      

      

align


string


alignment of paragraph within text column (1, Full, Left, Right, Center)


      

      

component


string


start a component within a book (see Book Components)


      

      

first


string


indent of first line (in points)


      

      

in


integer


list indent level (for examples only)


      

      

keep_next


boolean


keep this paragraph with the next one


      

      

keep_prev


boolean


keep this paragraph with the previous one


      

      

label


string


label for this paragraph (e.g. "Tip:")


      

      

left


string


left indent (in points)


      

      

noevents


boolean


do not do event processing on this paragraph


      

      

nopb


boolean


do not force this paragraph onto a new page


      

      

notoc


boolean


do not put this in the table of contents


      

      

noid


boolean


do not auto-generate an id for this paragraph


      

      

obj


string


format as the nominated phrase


      

      

orig_style


string


original style (useful in event processing)


      

      

out_style


string


output style to use


      

      

right


string


right indent (in points)


      

      

sp_after


string


space after this paragraph (in points)


      

      

sp_before


string


space before this paragraph (in points)


      

      

tabs


string


comma-separated list of tabstops


      

      

text


string


display the value instead of the existing text


      

      

top


string


place paragraph on a new page (1, 0, Page, Column, Left, Right)


      

      

wide


boolean


span the side-head


      

      


      3.4. Phrase Styles
      

      Leading whitespace is not removed for styles marked with (*).
      

      

      

Tag


Description


      

      

1


1st level emphasis


      

      

2


2nd level emphasis


      

      

3


3rd level emphasis


      

      

A


as-is


      

      

B


bold


      

      

C


source code (*)


      

      

CHAR


escape/special character


      

      

CMD


command


      

      

E


escape/special character


      

      

EMAIL


email address


      

      

EX


example text (*)


      

      

F


filename


      

      

FILE


filename


      

      

I


italic


      

      

IMPORT


figure


      

      

INLINE


embedded target format


      

      

JUMP


same as URL


      

      

L


POD link


      

      

N


normal


      

      

S


text with non-breaking spaces (*)


      

      

SECT


(jump to) document section


      

      

ST


strong emphasis


      

      

SUB


subscript


      

      

SUP


superscript


      

      

U


underline


      

      

URL


Uniform Resource Locator


      

      

X


POD index entry


      

      

Y


symbol (e.g. subroutine)


      

      

Z


zero width character (ala POD)


      

      


      The following styles are only supported in headers/footers:
      

      

      

Tag


Description


      

      

PAGECOUNT


highest page number


      

      

PAGENUM


current page number


      

      

PARALAST


text of last paragraph on page with the nominated style


      

      

PARANUM


paragraph number (e.g. Appendix A)


      

      

PARANUMONLY


paragraph number only (e.g. A)


      

      

PARASHORT


value of short attribute of paragraph


      

      

PARATEXT


paragraph text (e.g. Hardware requirements)


      

      


      The PARA* tags require a comma separated list of paragraph styles to be nominated as the text of the phrase, e.g. {{PARATEXT:H1,A1,P1}}.
      

      3.5. Phrase Attributes
      

      

      

Name


Type


Description


      

      

bgcolor


string


background colour


      

      

bold


boolean


enable bold


      

      

changed


boolean


enable change bars


      

      

class


string


CSS class (for HTML documents)


      

      

color


string


text colour


      

      

doc


string


for SECT, the name of the document containing the section


      

      

expand


boolean


expand object from short to long name


      

      

family


string


font family


      

      

id


string


identifier for this phrase (used by jumps)


      

      

index


string


indexing specification string (MIF only)


      

      

index_type


string


index type (MIF only)


      

      

italics


boolean


enable italics


      

      

jump


string


URL to jump to


      

      

short


string


text to display in header/footer when PARASHORT used


      

      

shrink


boolean


shrink object from long to short name


      

      

size


string


font size


      

      

style


string


custom CSS style information (for HTML documents)


      

      

text


string


display the value instead of the existing text


      

      

underline


boolean


enable underline


      

      

verbatim


boolean


ignore embedded symbols within this paragraph


      

      

xref


string


cross-referencing information (future)


      

      


      3.6. Escapes
      

      

      

Name


Output


Name


Output


Name


Output


      

      

2[


[[


2]


]]


2{


{{


      

      

2}


}}


Aacute


Á


aacute


á


      

      

Acirc


Â


acirc


â


AElig


Æ


      

      

aelig


æ


Agrave


À


agrave


à


      

      

amp


&


Aring


Å


aring


å


      

      

Atilde


Ã


atilde


ã


Auml


Ä


      

      

auml


ä


bullet


.


c


© 


      

      

Ccedil


Ç


ccedil


ç


cent


¢ 


      

      

dagger


^


doubledagger


#


Eacute


É


      

      

eacute


é


Ecirc


Ê


ecirc


ê


      

      

Egrave


È


egrave


è


emdash


--


      

      

emspace


  


endash


-


enspace


  


      

      

Euml


Ë


euml


ë


gt


>


      

      

Iacute


Í


iacute


í


Icirc


Î


      

      

icirc


î


Igrave


Ì


igrave


ì


      

      

Iuml


Ï


iuml


ï


lbrace


{


      

      

lbracket


[


lt


<


nbdash


-


      

      

nbspace


non-breaking space


nl


newline


Ntilde


Ñ


      

      

ntilde


ñ


Oacute


Ó


oacute


ó


      

      

Ocirc


Ô


ocirc


ô


Ograve


Ò


      

      

ograve


ò


Oslash


Ø


oslash


ø


      

      

Otilde


Õ


otilde


õ


Ouml


Ö


      

      

ouml


ö


pound


£ 


quot


"


      

      

r


® 


rbrace


}


rbracket


]


      

      

tab


tab


tm


™ 


Uacute


Ú


      

      

uacute


ú


Ucirc


Û


ucirc


û


      

      

Ugrave


Ù


ugrave


ù


Uuml


Ü


      

      

uuml


ü


yen


¥ 


yuml


ÿ


      

      


      For convenience, variables are provided for: amp, bullet, c, cent, dagger, doubledagger, emdash, endash, emspace, enspace, nbdash, nbspace, nbsp, nl, pound, r, reg, tab, tm, yen.
      

      3.7. Macros
      

      

      

Name


Description


      

      

back


ends a list (from POD)


      

      

begin


begin target-specific output (from POD)


      

      

block


begin a block of text


      

      

build_title


build a title page


      

      

catalog


build a catalog from objects already loaded


      

      

class


define a class of objects


      

      

clear


reset text wrapping around a figure


      

      

continued


continue a heading from a previous page


      

      

cut


ignore text until an = is found at the start of a line (from POD)


      

      

default


set a variable (if not already set)


      

      

define


set a variable


      

      

div


begin a division


      

      

else


begin alternative section


      

      

elseif


same as elsif


      

      

elsif


begin a conditional section


      

      

end


end target-specific output (from POD)


      

      

end_topic


mark the end of a topic


      

      

endblock


end a block of text


      

      

enddiv


end a division


      

      

endif


end conditional text


      

      

endmacro


end a macro definition


      

      

execute


include output from a command


      

      

export


export a variable to the format driver (and/or mark it for later exporting)


      

      

for


insert target-specific output (from POD)


      

      

getcli


extract command-line interface information


      

      

getcode


extract source code (i.e. non-documentation) from a file


      

      

getdoc


extract documentation embedded in source code


      

      

headn


level n heading (n = 1 .. 6) (from POD)


      

      

if


begin conditional text


      

      

import


import an external object (e.g. figure)


      

      

include


include another file


      

      

inherit


inherit entities from a library


      

      

init


initialise variables (before loading configuration files)


      

      

insert


call a macro


      

      

item


label an item in a list (from POD)


      

      

jumps


generate lines of jumps to headings


      

      

line


change message parameters


      

      

macro


begin a macro definition


      

      

message


output a message during execution


      

      

off


disable processing previously specified


      

      

on


specify processing for an event


      

      

output


dynamically change the output file used


      

      

over


begins a list (from POD)


      

      

perlapi


extract API information from a Perl library


      

      

pod


does nothing (from POD)


      

      

restrict


declare a restricted family of variables


      

      

script


execute a line of Perl


      

      

slide_down


decrease heading levels (e.g. H2 -> H3)


      

      

slide_up


increase heading levels (e.g. H2 -> H1)


      

      

subsections


specify the subsections for a topic


      

      

undef


clear a variable


      

      

use


load a library module


      

      


      3.8. Filters
      

      

      

Filter


Description


      

      

about


about section of a document


      

      

abstract


the abstract for a paper


      

      

address


an address


      

      

appendix


change headings to appendix style


      

      

ascii_graphic


fixed-width text, wide enough for ASCII graphics


      

      

box


surround a region of text with a box


      

      

center


centre a region


      

      

changed


mark a block of text as changed


      

      

chapter


chapter of a document (does nothing)


      

      

comment


ignore text


      

      

datestrings


define strings used in dates


      

      

default


provide defaults for a block of variables


      

      

define


define a block of variables


      

      

end


process text at the end


      

      

example


fixed-width text (e.g. source code)


      

      

front


front section of a document


      

      

get


extract embedded documentation


      

      

glossary


glossary section of document (alias for plain)


      

      

hlp_header


table of jumps at the top of a help topic


      

      

hlp_window


contents of a help popup window


      

      

inline


embed text into target format (e.g. HTML)


      

      

langdefs


define vgrind-like language definitions


      

      

links


define external links for a document (including stylesheets)


      

      

meta


define meta information for a document


      

      

namevalues


format a set of name-value pairs (e.g. as used in a title block)


      

      

nofill


a set of lines


      

      

note


a note


      

      

plain


change headings to plain style


      

      

pod


embedded POD


      

      

quote


a quotation


      

      

script


execute text as a Perl script


      

      

sdf


apply arbitrary phrase attributes to text


      

      

sections


paragraphs are sections


      

      

simple


generic filter for building others


      

      

stylesheet


define a stylesheet which should be inline in the HTML output


      

      

table


tabular data


      

      

template


alias for inline with expand set to true


      

      

title


title block for a memo, fax or minutes


      

      

topics


include a set of sub-topics


      

      

verbatim


fixed-width text, ignoring embedded symbols


      

      


      Classes and Programming Languages can also be used as filters.
      

      3.9. Figures
      

      Extension search rules:
      

      

      

When generating


The search order is


      

      

PostScript


epsi, eps, wmf, mif, gif


      

      

HTML


jpeg, jpg, png, gif


      

      

Windows Help


bmp


      

      


      import macro parameters:
      

      

      

Name


Description


      

      

alt


alternate text to display (ala HTML)


      

      

align


alignment (Left, Center, Right, Inner, Outer)


      

      

base


the prefix to prepend to the figure pathname to get the location needed for the HTML output


      

      

border


the border width in pixels


      

      

height


explicit height measurement (MIF only)


      

      

jump


the URL to jump to


      

      

listitem


the list indent level (e.g. 1)


      

      

mif_figure


the tag before the figure in the MIF source (only needed if more than one figure in the MIF file)


      

      

position


vertical position (Below, Top, Bottom)


      

      

title


figure caption


      

      

wide


figure straddles the side head area of the page


      

      

width


explicit width measurement (MIF only)


      

      

wrap_text


wrap text around a figure (ignored for HTML)


      

      


      Default conversion rules (from sdf.ini):
      

      

      

When generating


Create


From


Using the command


      

      

html


gif


eps


ps2gif -crop $source


      

      

html


gif


ps


ps2gif -crop $source


      

      

html


gif


prn


prn2ps -ops $source; ps2gif -crop $base.ps; rm $base.ps


      

      

ps


eps


ps


ps2epsi $source $dest


      

      

ps


eps


prn


prn2ps -ops $source; ps2epsi $base.ps $dest; rm $base.ps


      

      


      3.10. Tables
      

      table filter parameters:
      

      

      

Name


Description


      

      

align


alignment of table: one of Left, Center, Right, Inner, Outer


      

      

bgcolor


background colour for a table (HTML only)


      

      

bmargin


default bottom margin for table cells (MIF only)


      

      

cellpadding


padding size for table cells (HTML only)


      

      

cellspacing


spacing size between table cells (HTML only)


      

      

colaligns


a comma-separated list of horizontal alignments values (Left, Center, Right) for columns; alternatively, a single word containing the letters L, C and R


      

      

coltags


a comma-separated list of phrase styles to apply to columns


      

      

colvaligns


a comma-separated list of vertical alignments values (Top, Middle, Bottom, Baseline) for columns; alternatively, a single word containing the letters T, M, B and L


      

      

delete


a comma-separated list of columns to delete


      

      

footings


the number of footing rows at the end of the table


      

      

format


a comma-separated list of column width specifications; alternatively, a single number where each digit represents 10% of the space available to the table


      

      

groups


pattern of group-style rows (default is /:$/)


      

      

headings


the number of heading rows at the top of the table


      

      

keepindents


keep leading whitespace in cells


      

      

landscape


display the table in landscape mode (MIF only)


      

      

listitem


the list indent level (e.g. 1) of this table


      

      

lmargin


default left margin for table cells (MIF only)


      

      

narrow


if set, the table will only be as wide as required; otherwise the table will span the available space


      

      

niceheadings


set to 0 to disable _ to space conversion in headings


      

      

nocalcs


set to 0 to disable calculation processing within a table


      

      

noheadings


suppress headings in output


      

      

objects


alias for coltags (coltags is preferred)


      

      

oncell


Perl code to execute for each cell (internal use only!)


      

      

parseline


column headings parsing line (if not the first row in the text)


      

      

placement


vertical placement of table: one of Float, Pagetop, Columntop, Lefttop, Righttop (MIF only)


      

      

rmargin


default right margin for table cells (MIF only)


      

      

select


a comma-separated list of columns to display


      

      

sort


a comma-separated list of columns to sort the data rows by


      

      

style


overall look of the table (columns, rows, grid, plain, shade)


      

      

tags


alias for coltags (coltags is preferred)


      

      

title


table caption


      

      

tmargin


default top margin for table cells (MIF only)


      

      

type


alias for style (style is preferred)


      

      

where


an expression to filter the data rows with


      

      

wide


table straddles the side head area of the page


      

      

wrap


the number of data rows to display in a physical row


      

      


      Column width specifications:
      

      

      

Value


Meaning


      

      

30pt


an exact size (other supported units are cm, mm, " and in)


      

      

30%


a percentage of the size available


      

      

30


a percentage of the size available (% is implicit)


      

      

10-20


dynamic size between 10% and 20% of the total width


      

      

-20


dynamic size between 0% and 20% of the total width


      

      

10-


dynamic size between 10% and 100% of the total width


      

      

-


dynamic size between 0% and 100% of the total width


      

      

3*


3 units of the remaining space


      

      

*


same as 1*


      

      


      = can be used in place of - to get equalised column widths.
      

      Cell attributes:
      

      

      

Name


Value


      

      

align


horizontal alignment (Left, Center, Right)


      

      

angle


angle of text (0, 90, 180, 270)


      

      

bgcolor


background colour of cell


      

      

bruling


ruling setting for bottom of cell


      

      

cols


the number of columns this cell spans (default is 1)


      

      

fill


background colour fill % (100, 90, 70, 50, 30, 10, 3)


      

      

lruling


ruling setting for left of cell


      

      

nowrap


disable word wrap for this cell


      

      

paratag


paragraph style to apply to cell text (future)


      

      

rows


the number of rows this cell spans (default is 1)


      

      

rruling


ruling setting for right of cell


      

      

sdf


treat the cell text as SDF (rather than as phrase text)


      

      

tag


phrase tag to apply to cell text


      

      

truling


ruling setting for top of cell


      

      

valign


vertical alignment (Top, Middle, Bottom, Baseline)


      

      


      Permitted ruling values: Vthin, Thin, Medium, Thick, Double.
      

      3.11. Classes
      

      Data fields for the predefined classes are:
      

      

      

Field


Tag


Description


      

      

organisations:


 


 


      

      

Name


ORG


organisation name


      

      

Long


ORGN


long form of organisation name


      

      

Jump


 


URL for organisation


      

      

products:


 


 


      

      

Name


PRD


product name


      

      

Jump


 


URL for product


      

      

references:


 


 


      

      

Reference


REF


document code


      

      

Document


DOC


document title


      

      

Jump


 


URL for document


      

      

Version


 


version number


      

      

Status


 


status (e.g. Draft, Review or Final)


      

      

terms:


 


 


      

      

Term


TERM


term, acronym or abbreviation


      

      

Description


 


explanation


      

      

Jump


 


URL for term


      

      


      The REFNUMONLY tag can be used to mark a REF phrase where only the trailing number is output.
      

      Calculated fields for the references class:
      

      

      

Name


Description


      

      

XXX


if a matching xxx file is found, an image which jumps to that file


      

      

Cite


a string of the form [n]


      

      

Date


the date of the html file


      

      

Pages


the number of pages in the PostScript document


      

      

Printdoc


an image which launches the /cgi-bin/printdoc/ CGI script


      

      

Printer


alias for Printdoc


      

      


      Parameters of class filters:
      

      

      

Name


Type


Description


      

      

cited


boolean


number these objects as the cited ones (for [1] style references)


      

      

colaligns


string


a comma-separated list of horizontal alignments  values (Left, Center, Right) for columns; alternatively, a single word containing the letters L, C and R can be used for the value


      

      

columns


string


comma-separated list of attributes to display in table


      

      

colvaligns


string


a comma-separated list of vertical alignments  values (Top, Middle, Bottom, Baseline) for columns; alternatively, a single word containing the letters T, M, B and L can be used for the value


      

      

compact


boolean


display in a compact table, (make cellpadding data       boolean      define objects but do not display them


      

      

delete


string


a comma-separated list of columns to delete


      

      

headings


boolean


display the column headings


      

      

root


string


string to prepend to Jump attribute, if any


      

      

select


string


a comma-separated list of columns to display


      

      

sort


string


comma-separated list of columns to sort by


      

      

style


string


table style to use (the default is plain)


      

      

 


 


and cellspacing both equal to zero)


      

      

variables


boolean


define a variable for each object; the variable name is derived from the object name with underscores replacing non-alphanumeric characters


      

      

where


string


filter the rows using the nominated expression


      

      

wide


boolean


use sidehead when formatting on paper


      

      

wrap


integer


number of logical rows to place on a physical row


      

      


      3.12. Document Variables/Macros
      

      Controls
      

      

      

Name


Type


Description


      

      

DOC_ADMIN_LOGO


string


logo to use in administration document styles


      

      

DOC_ADMIN_LOGO_BASE


string


base directory for DOC_ADMIN_LOGO


      

      

DOC_APPROVE


string


person approving the document


      

      

DOC_APPROVE2


string


2nd person approving the document


      

      

DOC_APPROVE3


string


3rd person approving the document


      

      

DOC_AUTHOR


string


author of document


      

      

DOC_AUTHOR2


string


2nd author of document


      

      

DOC_AUTHOR3


string


3rd author of document


      

      

DOC_CODE


string


document code (*)


      

      

DOC_COMPONENT


string


current component type within a book


      

      

DOC_COMPONENT_LOGO


string


logo to use for components within a book


      

      

DOC_COVER


string


logical name of the cover page to use (e.g. original, project, manual, paper)


      

      

DOC_DISTRIBUTION


string


document distribution


      

      

DOC_HTML_LOGO


string


logo to use in HTML output


      

      

DOC_HTML_LOGO_BASE


string


base directory for HTML_LOGO


      

      

DOC_ID_SEP


string


separator used within DOC_ID


      

      

DOC_IX


boolean


build an index


      

      

DOC_LOF


boolean


build a list of figures


      

      

DOC_LOF_TITLE


string


list of figures title


      

      

DOC_LOGO


string


logo to use for document


      

      

DOC_LOGO_BASE


string


base directory for DOC_LOGO


      

      

DOC_LOT


boolean


build a list of tables


      

      

DOC_LOT_TITLE


string


list of tables title


      

      

DOC_MANUAL_LOGO


string


logo to use when generating paper manuals


      

      

DOC_NAME


string


document name, e.g. "SDF 2.000"


      

      

DOC_OWNER


string


person or company owning the copyright


      

      

DOC_PRODUCT


string


for man pages, the center string in the header


      

      

DOC_PROJECT


string


orginating project of document


      

      

DOC_SECTION


integer


for man pages, the section number


      

      

DOC_STATUS


string


status of document (*)


      

      

DOC_TITLE_LOGO


string


logo used in the title of a PostScript document


      

      

DOC_TOC


integer


table of contents level


      

      

DOC_TOC_GRAPHIC


string


graphic to include in TOC title


      

      

DOC_TOC_TITLE


string


table of contents title


      

      

DOC_TOPIC_LOGO


string


logo to use in HTML topics mode output


      

      

DOC_TOPIC_LOGO_BASE


string


base directory for DOC_TOPIC_LOGO


      

      

DOC_TWO_SIDES


boolean


build a two-sided document


      

      

DOC_TYPE


string


document type, e.g. "User Guide"


      

      

DOC_URL


string


URL of document


      

      

DOC_VERSION


string


version number of document (*)


      

      

Macros:


 


 


      

      

DOC_COMPONENT_BEGIN


macro


hook to initialise things before book component processing begins


      

      

DOC_COMPONENT_END


macro


hook to finalise things after book component processing ends


      

      

DOC_OFFICES


macro


for manuals, the text to put after the inside front cover


      

      

DOC_RECIPIENTS


macro


table of controlled copy recipients


      

      

DOC_TRADEMARKS


macro


text specifying trademarks used in document


      

      


      If the variables marked with (*) are not defined, build_title sets them using the references data, if possible.
      

      Information
      

      

      

Name


Type


Description


      

      

DOC_BASE


string


the base (filename) of the current document


      

      

DOC_COLUMN_WIDTH


integer


width of a text column (in points)


      

      

DOC_DIR


string


the directory of the current document


      

      

DOC_EXT


string


the extension of the current document


      

      

DOC_FULL_WIDTH


integer


width of text area including the side-head (in points)


      

      

DOC_ID


string


combination of DOC_CODE and DOC_VERSION


      

      

DOC_MODIFIED


datetime


the most recent modification time of files visited so far


      

      

DOC_PAGE_HEIGHT


integer


height of page (in points)


      

      

DOC_PAGE_WIDTH


integer


width of page (in points)


      

      

DOC_PAGED


boolean


output is paged, not continuous


      

      

DOC_PATH


string


the full pathname of the current document


      

      

DOC_SHORT


string


the base and extension of the current document


      

      

DOC_START


datetime


the time document conversion started


      

      

DOC_TEXT_HEIGHT


integer


height of text area (in points)


      

      

DOC_TEXT_WIDTH


integer


width of text area available for text columns (in points)


      

      

DOC_TITLE


string


combination of DOC_NAME and DOC_TYPE


      

      

MODIFIED_DATE


string


alias for DATE:DOC_MODIFIED


      

      

File:


 


 


      

      

FILE_BASE


string


base part of current filename (e.g. mydoc)


      

      

FILE_DIR


string


directory of current filename (e.g. /doc/sdf)


      

      

FILE_EXT


string


extension of current filename (e.g. sdf)


      

      

FILE_MODIFIED


datetime


time when this file was last modified


      

      

FILE_PATH


string


current pathname (e.g. /doc/sdf/mydoc.sdf)


      

      


      3.13. Option Variables
      

      These variables (except OPT_NOBARS) give the values of command-line options. Variables marked with a (*) can be set via the init macro on the top line of a document:
      

      

      

Name


Type


Description


      

      

OPT_CONFIG


string


configuration library (*)


      

      

OPT_DRIVER


string


name of driver used to convert documents


      

      

OPT_EXT


string


output extension


      

      

OPT_HEAD_LEVEL


integer


level to start headings at


      

      

OPT_HEAD_LOOK


string


look for headings


      

      

OPT_LOCALE


string


locale


      

      

OPT_LOOK


string


look (*)


      

      

OPT_NOBARS


boolean


disable change bars (*)


      

      

OPT_NUMBER


integer


line numbering fequency


      

      

OPT_PAGE_SIZE


string


page size setting (default is global) (*)


      

      

OPT_PP_xxx


boolean


set if xxx post-processing requested


      

      

OPT_REPORT


string


report to run


      

      

OPT_SPLIT_LEVEL


integer


level to split headings at for topics mode


      

      

OPT_STYLE


string


document style (*)


      

      

OPT_TARGET


string


target format


      

      

OPT_WIDTH


integer


width for txt output (default is 70) (*)


      

      


      These variables can only be set within look libraries:
      

      

      

Name


Type


Description


      

      

OPT_BORDERS


integer


high-level header/footer border control (0=none; 1=above footer,below header; 2=above footer,above & below header)


      

      

OPT_COLUMNS


integer


number of columns in text area (default is 1)


      

      

OPT_COLUMN_GAP


dimension


gap between columns in text area


      

      

OPT_COMPONENT_COVER


boolean


give book components a cover page


      

      

OPT_HEADINGS


integer


size in lines (0..4) of headers/footers (Note: for values 2..4, header size is 2)


      

      

OPT_IX_COLUMNS


integer


number of columns in text area in the index (default is 1)


      

      

OPT_IX_COLUMN_GAP


dimension


gap between columns in text area in the index


      

      

OPT_IX_SIDEHEAD_GAP


dimension


width between side-head and text area in the index


      

      

OPT_IX_SIDEHEAD_WIDTH


dimension


width of side-head in the index


      

      

OPT_LIST_INDENT


dimension


size of each list indent in points


      

      

OPT_MARGIN_BOTTOM


string


size of margin below the footer, if any


      

      

OPT_MARGIN_INNER


string


size of inner margin


      

      

OPT_MARGIN_OUTER


string


size of outer margin


      

      

OPT_MARGIN_TOP


string


size of margin above the header, if any


      

      

OPT_NUMBER_PER_COMPONENT


boolean


number figures, etc. per component


      

      

OPT_SIDEHEAD_GAP


dimension


width between side-head and first text column


      

      

OPT_SIDEHEAD_WIDTH


dimension


width of side-head


      

      


      3.14. Page Layout Variables
      

      Page variables can only be set within look libraries.
      

      Page tags:
      

      

      

Page


Usage


      

      

FIRST


the first page in the document


      

      

RIGHT


the page used for single-sided documents and the right hand side of double-sided documents


      

      

LEFT


the left hand side of double-sided documents; ignored for single-sided documents


      

      


      In the table below, frl is either:
      

        

      • FIRST, RIGHT or LEFT, or

      • COMPONENT_FRL where:
          

        • COMPONENT is the name of the component in upper-case (refer to Book Components)

        • FRL is FIRST, RIGHT or LEFT.
      

      If a component does not have a component-specific macro/variable defined, then the generic macro/variable is used.
      

      

      

Name


Type


Description


      

      

PAGE_frl_BACKGROUND


string


background image name


      

      

PAGE_frl_FOOTER_BORDER


string


border specification


      

      

PAGE_frl_FOOTER_GAP


dimension


gap between text area and footer area


      

      

PAGE_frl_FOOTER_HEIGHT


dimension


height of footer area


      

      

PAGE_frl_FOOTER_INNERn


string


inner text of line n (0..3) of footer


      

      

PAGE_frl_FOOTER_CENTERn


string


centre text of line n (0..3) of footer


      

      

PAGE_frl_FOOTER_OUTERn


string


outer text of line n (0..3) of footer


      

      

PAGE_frl_HEADER_BORDER


string


border specification


      

      

PAGE_frl_HEADER_GAP


dimension


gap between header area and text area


      

      

PAGE_frl_HEADER_HEIGHT


dimension


height of header area


      

      

PAGE_frl_HEADER_INNERn


string


inner text of line n (1..2) of header


      

      

PAGE_frl_HEADER_CENTERn


string


centre text of line n (1..2) of header


      

      

PAGE_frl_HEADER_OUTERn


string


outer text of line n (1..2) of header


      

      


      When FrameMaker is being used to generate PostScript, the background image name is mapped to a master page called backgrnd within a file called backgrnd.mif. At the moment, objects from the master page (excluding TextRects) are directly transferred to the generated MIF file. This means that objects in the lower right hand corner of an A4 master page will not will be positioned nicely if the paper size is changed to A5, say.
      

      A border specification string is a comma-separated list of attributes which collectively describe the border. The format of each attribute is name[=value]. The supported attributes are:
      

        

      • top - a line above the area

      • bottom - a line below the area

      • box - a box around the area

      • radius - for a box, the radius of the corner.
      

      For top, bottom and box, the value of the attribute is the line width in points.
      

      3.15. Miscellaneous Variables/Macros
      

      Controls
      

      

      

Name


Type


Description


      

      

Processing:


 


 


      

      

DEFAULT_LOCALE


string


default OPT_LOCALE (set in sdf.ini)


      

      

DEFAULT_LOOK


string


default OPT_LOOK (set in sdf.ini)


      

      

DEFAULT_TAB_SIZE


integer


default tab size (initially 8)


      

      

DEFAULT_TABLE_STYLE


string


default style for tables (initially columns)


      

      

DEFAULT_XREF_STYLE


string


default style for cross-references (initially sections)


      

      

Link expansion formats:


 


 


      

      

FORMAT_LINK_PAGE


string


default is: the $page manpage


      

      

FORMAT_LINK_PAGE_ENTRY


string


default is: the $entry entry in the $page manpage


      

      

FORMAT_LINK_PAGE_SECTION


string


default is: the section on "$sect" in the $page manpage


      

      

FORMAT_LINK_SECTION


string


default is: the section on "$sect"


      

      

HTMLDOC generation:


 


 


      

      

HTMLDOC


boolean


generate HTML ready for HTMLDOC


      

      

HTMLDOC_OPTS


string


tuning options to pass to HTMLDOC


      

      


      Information
      

      

      

Name


Type


Description


      

      

Package:


 


 


      

      

SDF


phrase


PRD:SDF


      

      

SDF_BUGS


phrase


EMAIL:sdf-bugs@mincom.com


      

      

SDF_FTP


string


URL for SDF's FTP site


      

      

SDF_HOME


string


library/configuration directory


      

      

SDF_USERS


phrase


EMAIL:sdf-users@mincom.com


      

      

SDF_VERSION


string


product version string (e.g. 2.000 beta1)


      

      

SDF_WWW


string


URL for SDF's home page


      

      

Macros for default.sdg:


 


 


      

      

SDG_DESCRIPTION_POST


macro


finalisation after Description


      

      

SDG_DESCRIPTION_PRE


macro


initialisation before Description


      

      

SDG_BEGIN


macro


hook for things before extracted text


      

      

SDG_END


macro


hook for things after extracted text


      

      

SDF_OPT_HELP


macro


text explaining help option


      

      

SDF_OPT_STD


macro


text explaining standard options


      

      

Old macro names:


 


 


      

      

BUILD_TITLE


string


provided for backwards-compatibility


      

      

END_TOPIC


string


provided for backwards-compatibility


      

      

SLIDE_DOWN


string


provided for backwards-compatibility


      

      

SLIDE_UP


string


provided for backwards-compatibility


      

      

SDF_DESCRIPTION_POST


macro


provided for backwards-compatibility


      

      

SDF_DESCRIPTION_PRE


macro


provided for backwards-compatibility


      

      


      3.16. Programming Languages
      

      

      

Language


Names


      

      

C


c


      

      

C++


c++, cpp, hpp, cc, h


      

      

COBOL


cobol


      

      

CORBA IDL


idl


      

      

FORTRAN


fortran, f77, fc, f, for


      

      

Java


java


      

      

MIMS COBOL


mimscobol, pcom, precom


      

      

Object Pascal


delphi, pascal, pas, int


      

      

Perl


perl, pl, pm, sdp, sdr


      

      

Python


python, jpython, py


      

      

Simple Document Format


sdf, sdm, sds, sdn, sdl, sde


      

      

Unix shell


sh


      

      

Unix c-shell


csh


      

      


      Language names are case insensitive.
      

      3.17. Colours
      

      For PS (i.e. MIF) generation, the supported colour values are Black, White, Red, Green, Blue, Yellow, Cyan and Magenta. If a different colour is specified, it is ignored.
      

      For HTML generation, any of the HTML colours names (including those supported for PS generation) or the "#rrggbb" form can be used. Useful variables are:
      

      

      

Name


Value


Name


Value


      

      

COLOR_WHITE


'ffffff'


COLOR_BLACK


'000000'


      

      

COLOR_RED


'ff0000'


COLOR_GREEN


'00ff00'


      

      

COLOR_BLUE


'0000ff'


COLOR_YELLOW


'ffff00'


      

      

COLOR_MAGENTA


'ff00ff'


COLOR_CYAN


'00ffff'


      

      

COLOR_GREY


'c0c0c0'


      

      


      3.18. Expression Formats
      

      

      

Name


Description


      

      

Strings:


 


      

      

LOWER


convert a string to lowercase


      

      

LOWER1


convert the first character to lowercase


      

      

UPPER


convert a string to uppercase


      

      

UPPER1


convert the first character to uppercase


      

      

Dates:


 


      

      

CONCISE


alias for FORMAT_SDATE


      

      

DATE


format to a date only


      

      

DATETIME


format to a complete date-time format


      

      

FULL


alias for FORMAT_DATETIME


      

      

SDATE


format to a concise date only


      

      

TIME


format to a time only


      

      

YEAR


format to a 4-digit year


      

      


      Expression format XXX can be changed/defined via the FORMAT_XXX variable.
      

      3.19. Modules
      

      

      

Name


Description


      

      

bugtrack


extensions for bug tracking


      

      

defines


simplified product declaration/definition


      

      

delphi


extensions for delphi 1.x documentation


      

      

homepage


extensions for making SDF-like home pages easier to author


      

      

misc


miscellaneous goodies


      

      

objects


IT-related objects


      

      

testcase


extensions for test case documentation


      

      

usecases


extensions for Use Case documentation


      

      


      3.20. Book Components
      

      

      

Name


Meaning


      

      

front


the cover component


      

      

pretoc


components before the contents


      

      

toc


the table of contents


      

      

lof


the list of figures


      

      

lot


the list of tables


      

      

prechapter


components before the chapters


      

      

chapter


a normal chapter


      

      

appendix


an appendix


      

      

preix


components before the index


      

      

ix


the index


      

      


      3.21. Event Processing
      

      Supported symbols within actions:
      

      

      

Type


Symbols


      

      

paragraph


$style, $text, %attr, &PrependText, &AppendText, $level, $prev_style, $prev_text, %prev_attr


      

      

phrase


$style, $text, %attr, $append


      

      

macro


$name, $args


      

      

filter


$name, $params


      

      

table


$style, %param


      

      


      Special symbol meanings:
      

      

      

Symbol


Meaning


      

      

paragraph:


 


      

      

&PrependText


a subroutine to add paragraphs before this one


      

      

&AppendText


a subroutine to add paragraphs after this one


      

      

$level


the current heading level (before this paragraph)


      

      

$prev_style


the style of the previous paragraph


      

      

$prev_text


the text of the previous paragraph


      

      

%prev_attr


the attributes of the previous paragraph


      

      

phrase:


 


      

      

$append


text to append onto the end of the phrase


      

      


      

      

      

      Home | Catalog
      

      

      




string


default style for cross-references (initiallysdf-2.001/doc/sdfbig.gif010064400042570001753000000011510632062614400146110ustar00iancmtr00000400000236GIF89aBkóÿÿÿffÌÌ3™f,BkÿÈI«½8ëÍ»ÿ`(ŽdižhšlËNåÎôFß7üê®UW½Õì2´ˆG_¸T&‘±§ºsV™RëUIaŠØmX,óŽ5M¹œvÑm0ŒÝžkáYc|œöéfrzZuwx[ƒb8jo€j]9_†Ž|?“ƒ—ˆ`–zŒ~‰ik˜‹ ¡¥Y‰¤y›a‡2n¯«·²gµ:³£œp6° u±XxÀSÊPÉ¿ºÏT•¹¸Ó¾Ã¦k”’¶Ôv¸Œ™Ó8*æçèéêíëéíñïçñîóæõ÷øòú)ùý(þ4!pàˆz–@¨Æ"
@qD
+j´x‘]Â	ÿ+väRãH
%Ež4	2%Ç‹)%¸|	1¦Ì’#gÞÙ’b:–=q
ô„͉.75*éR:™}
5©Ô¦T+D5±u'M§4»’{ajÓ«E3˜å™biÑ®iÛªôÊ’¬A›vêÜ÷ªV«xÏ–X+40[´sá&¶:˜qÖ¿?ð\–ñXË`«ú$ºq_ÍéÎåJáÏ!ÜŽ{8ó¹·X1ßù^ÔÉ›m;.\úõn¶µå>š×\pѨUÝúñ³Åu7?¾Nqód“ë‹žó÷׎†CwÞ»ásê5e›Í]zèöóN¯Vx»|?ëß×£×o%ôù0ñv]€¹±àIœižz¨ ý'^ƒÌH¡W@";sdf-2.001/doc/home.sdf010075500042570001753000000120500672243755000143240ustar00iancmtr00000400000236# Load the general homepage formatting module
!use "homepage"

# Change these when a new version is released
!define VERSION         "2.001"
!define RELEASED        "25-May-99"

# General configuration stuff
!define HTML_BG_COLOR COLOR_WHITE
!define sqbullet      '{{IMPORT: sqbull.gif}}E'

# Define the title and metadata
!define HTML_TITLE    "SDF - The Author-friendly Markup Language"
!block meta
Name|Content
description|A free documentation tool for generating HTML, PostScript,\
 Windows Help, PDF, LaTeX, man pages, SGML, RTF, MIF, POD, GNU info\
 and plain text, all from a single source. Minimises time and effort\
 by supporting rule-based generation of hypertext, formatting,\
 indexing, etc. The SDF language is easy to read, powerful and\
 easy to embed in most programming languages.

keywords|word processing, desktop publishing,\
 literate programming, embedded documentation, Perl, Delphi, C, C++,\
 Java, FrameMaker, authoring, intranet, free software
!endblock

# Key pages (to get relative URLs, use -DLOCAL_DOCS)
!default WEB_SITE       $var{'LOCAL_DOCS'} ? "" : \
                        "http://www.mincom.com/mtr/sdf/"
!default SAMPLES_PAGE   "$var{'WEB_SITE'}samples/"
!default RESOURCES_PAGE "$var{'WEB_SITE'}resources/"
!default NEWS_PAGE      "$var{'WEB_SITE'}news/"
!default DOWNLOAD_PAGE  "$var{'WEB_SITE'}download/"
!default TEMPLATES_PAGE  "$var{'WEB_SITE'}templates/"
!default BUGSDB_PAGE    "$var{'WEB_SITE'}bugs/index.html"

# Links to third-party stuff
!default PERL_URL       "http://www.perl.com"
!default POD2PS_URL     "http://www.oasis.leo.org/perl/scripts/textproc/pod2ps.dsc.html"
!default SGMLTOOLS_URL  "http://www.xs4all.nl/~cg/sgmltools/"
!default FRAME_URL      "http://www.adobe.com/prodindex/framemaker/main.html"
!default ACROBAT_URL    "http://www.adobe.com/prodindex/acrobat/"

!block homepage_table
A|B|C
{{IMPORT:sdfbig.gif}}|S<    >|<<
!homepage_title "Simple Document Format"
>>

||
Key pages||<<
!block table; style="plain"; cellpadding=0; cellspacing=0; noheadings; wrap=3
Reference
[[sqbullet]]\
{{A[jump="catalog.html"]                Document Catalog}}[[nl]]\
[[sqbullet]]\
{{A[jump="faq/index.html"]              Frequently Asked Questions}}[[nl]]\
[[sqbullet]]\
{{A[jump="paper/sdfintro.html"]         Overview Paper}}
S<    >
[[sqbullet]]\
{{A[jump=SAMPLES_PAGE]                  Sample Showcase}}[[nl]]\
[[sqbullet]]\
{{A[jump=RESOURCES_PAGE]                Resource Center}}[[nl]]\
[[sqbullet]]\
{{A[jump=NEWS_PAGE]                     Latest News}}
!endblock
>>

||
What is it?||<<
    SDF is a freely available documentation system designed and developed by
    {{A[jump="mailto:ianc@mincom.com"] Ian Clatworthy}}, with help from
    many others. Based on a simple, readable markup language,
    SDF generates high quality output in multiple formats, all 
    derived from a single document source.
    Supported output formats include HTML, PostScript, PDF, man pages,
    POD, LaTeX, SGML, MIMS HTX and F6 help, MIF, RTF,
    Windows help and plain text.
    If you want to:

    [[sqbullet]] publish documents or reports on the Web or in
                 multiple formats[[nl]]
    [[sqbullet]] maintain a large documentation suite using rule-based
                 formatting and hypertext generation[[nl]]
    [[sqbullet]] embed documentation in source code or pretty print source code

    then SDF may be for you.
>>

||
What does it need?||<<

    [[sqbullet]] {{A[jump="http://www.perl.com/perl/"]Perl}} 5.005 or later.[[nl]]
    [[sqbullet]] For generating PostScript, the freely available
    {{A[jump="http://www.easysw.com/~mike/htmldoc/"]HTMLDOC}} program or
    {{A[jump="http://www.oasis.leo.org/perl/scripts/textproc/pod2ps.dsc.html"]pod2ps}}
     program or {{A[jump="http://www.xs4all.nl/~cg/sgmltools/"]SGML-Tools}}
     and LaTeX packages. Alternatively, you need
    a word processor which can import MIF or RTF -
    Adobe's
    {{A[jump="http://www.adobe.com/prodindex/framemaker/main.html"]FrameMaker}}
    is preferred.[[nl]]
    [[sqbullet]] For generating PDF,
    {{A[jump="http://www.adobe.com"]Adobe's}}
    {{A[jump="http://www.adobe.com/prodindex/acrobat/"]Acrobat}}
    is recommended.[[nl]]
    [[sqbullet]] For generating Windows Help files, a help compiler is required.
>>

||
Where can I get it?||<<
    The current version is {{B:[[VERSION]]}}, released [[RELEASED]].
    You can download the latest release from {{URL:[[DOWNLOAD_PAGE]]}}
    in a variety of formats.
    SDF templates are also available from {{URL:[[TEMPLATES_PAGE]]}}.
>>

||
Support?||<<
    An on-line {{A[jump=BUGSDB_PAGE] bug database}}
    provides information on known bugs and requested enhancements.
    Any problems with the software or the documentation can be reported to
    the mailing list {{EMAIL:sdf-bugs@mincom.com}}.
    For general queries, mail {{EMAIL:sdf-users@mincom.com}}.
    To subscribe to either list, send a message to 
    {{EMAIL: factotum@mincom.com}}
    with {{subscribe sdf-bugs}} or {{subscribe sdf-users}}
    as the message body.
>>
!endblock

N[align=Center] Questions about these pages?
Send some mail to {{EMAIL:sdf-bugs@mincom.com}}.
sdf-2.001/doc/sqbull.gif010064400042570001753000000014740622022217000146530ustar00iancmtr00000400000236GIF89a÷¿¿¿¿¿¿¿¿¿ÀÀÀÀÜÀ¤Èð¼¼¼¼¼¼¼¼¼€€€€€€€€€<\<\\<|\<œ\<¼\<Ü\<ü\<<|<\|<||<œ|<¼|<Ü|<ü|<<œ<\œ<|œ<œœ<¼œ<Üœ<üœ<<¼<\¼<|¼<œ¼<¼¼<ܼ<ü¼<<Ü<\Ü<|Ü<œÜ<¼Ü<ÜÜ<üÜ<<ü<\ü<|ü<œü<¼ü<Üü<üü<<<\\<\|<\œ<\¼<\Ü<\ü<\<\\\\\|\\œ\\¼\\Ü\\ü\\<|\\|\||\œ|\¼|\Ü|\ü|\<œ\\œ\|œ\œœ\¼œ\Üœ\üœ\<¼\\¼\|¼\œ¼\¼¼\ܼ\ü¼\<Ü\\Ü\|Ü\œÜ\¼Ü\ÜÜ\üÜ\<ü\\ü\|ü\œü\¼ü\Üü\üü\<<|\<||<|œ<|¼<|Ü<|ü<|<\|\\||\|œ\|¼\|Ü\|ü\|<||\|||||œ||¼||Ü||ü||<œ|\œ||œ|œœ|¼œ|Üœ|üœ|<¼|\¼||¼|œ¼|¼¼|ܼ|ü¼|<Ü|\Ü||Ü|œÜ|¼Ü|ÜÜ|üÜ|<ü|\ü||ü|œü|¼ü|Üü|üü|<<œ\<œ|<œœ<œ¼<œÜ<œü<œ<\œ\\œ|\œœ\œ¼\œÜ\œü\œ<|œ\|œ||œœ|œ¼|œÜ|œü|œ<œœ\œœ|œœœœœ¼œœÜœœüœœ<¼œ\¼œ|¼œœ¼œ¼¼œÜ¼œü¼œ<Üœ\Üœ|ÜœœÜœ¼ÜœÜÜœüÜœ<üœ\üœ|üœœüœ¼üœÜüœüüœ<<¼\<¼|<¼œ<¼¼<¼Ü<¼ü<¼<\¼\\¼|\¼œ\¼¼\¼Ü\¼ü\¼<|¼\|¼||¼œ|¼¼|¼Ü|¼ü|¼<œ¼\œ¼|œ¼œœ¼¼œ¼Üœ¼üœ¼<¼¼\¼¼|¼¼Ðåдý˜åå˜{{˜ÿûð  ¤€€€ÿÿÿÿÿÿÿÿÿÿÿÿ,!ñ	H°`ÚjKpŸÂ…
2D¨p">†fÄ;sdf-2.001/doc/home.html010064400042570001753000000136770672243757600145410ustar00iancmtr00000400000236






SDF - The Author-friendly Markup Language






      

      

      

      

      

      

      

 


    


 S i m p l e 
       D o c u m e n t 
       F o r m a t 
             
      		

      

      

 


 


 


      

      

Key pages


 



      

      

 Document Catalog
       Frequently Asked Questions
       Overview Paper
      		

    


 Sample Showcase
       Resource Center
       Latest News
      		

      

      

      		

      

      

 


 


 


      

      

What is it?


 


SDF is a freely available documentation system designed and developed by Ian Clatworthy, with help from many others. Based on a simple, readable markup language, SDF generates high quality output in multiple formats, all derived from a single document source. Supported output formats include HTML, PostScript, PDF, man pages, POD, LaTeX, SGML, MIMS HTX and F6 help, MIF, RTF, Windows help and plain text. If you want to:

        publish documents or reports on the Web or in multiple formats
         maintain a large documentation suite using rule-based formatting and hypertext generation
         embed documentation in source code or pretty print source code
      

      then SDF may be for you.
      
      		

      

      

 


 


 


      

      

What does it need?


 


  Perl 5.005 or later.
         For generating PostScript, the freely available HTMLDOC program or pod2ps program or SGML-Tools and LaTeX packages. Alternatively, you need a word processor which can import MIF or RTF - Adobe's FrameMaker is preferred.
         For generating PDF, Adobe's Acrobat is recommended.
         For generating Windows Help files, a help compiler is required.
      		

      

      

 


 


 


      

      

Where can I get it?


 


The current version is 2.001, released 25-May-99. You can download the latest release from http://www.mincom.com/mtr/sdf/download/ in a variety of formats. SDF templates are also available from http://www.mincom.com/mtr/sdf/templates/.


      

      

 


 


 


      

      

Support?


 


An on-line bug database provides information on known bugs and requested enhancements. Any problems with the software or the documentation can be reported to the mailing list sdf-bugs@mincom.com. For general queries, mail sdf-users@mincom.com. To subscribe to either list, send a message to factotum@mincom.com with subscribe sdf-bugs or subscribe sdf-users as the message body.


      

      


      Questions about these pages? Send some mail to sdf-bugs@mincom.com.
      

      

      

      

      

      



sdf-2.001/doc/catalog.html010064400042570001753000000113740672242767600152130ustar00iancmtr00000400000236






SDF 2.001: SDF Document Catalog




      

      

      Home
      

      

      

      

      

      SDF Document Catalog
      

      SDF-DOCS
      

      

      25 May 1999
      

      

      

      

      Getting started | Manuals | Tutorials | Other documents
      

      This page lists the supporting documentation available for SDF version 2.001. For the latest documentation, visit the SDF Document Catalog on the SDF Web Site. Documentation for local extensions, if any, may be found here.
      

      Getting started
      

      

      

(PDF)


(PS)


The SDF Document Development System


25-May-99


27 pages


      

      

(PDF)


(PS)


SDF Frequently Asked Questions


25-May-99


12 pages


      

      

(PDF)


(PS)


SDF Quick Reference


25-May-99


33 pages


      

      


      Manuals
      

      

      

(PDF)


(PS)


SDF User Guide


25-May-99


98 pages


      

      

(PDF)


(PS)


SDF Reference


25-May-99


193 pages


      

      

(PDF)


(PS)


SDF Guru Guide


25-May-99


58 pages


      

      


      Tutorials
      

      

      

(PDF)


(PS)


Generating HTML Using SDF


25-May-99


16 pages


      

      

(PDF)


(PS)


SDF for POD Users


25-May-99


15 pages


      

      


      Other documents
      

      

      

(PDF)


(PS)


SDF Release Notes


25-May-99


89 pages


      

      


      

      

      

      Home
      

      

      



tting started | Manuals | Tutorials | Other documents
      

      This page lists the supporting documentation available for SDF version 2.001. For the latest documentation, vsdf-2.001/doc/website010064400042570001753000000000530647024566400142630ustar00iancmtr00000400000236prefix_Jump=http://www.mincom.com/mtr/sdf/
sdf-2.001/doc/pdf.gif010064400042570001753000000002310647547731400141400ustar00iancmtr00000400000236GIF87a¢ÿÿÿîîîÝ,f8ºÜ® ÊI窘†žÔIb7 wBëj©xF¬KÇs[Öp˜{\DŒÄ¤o˜8•Iô	¦ÈªTiÌ*·Å¦3!Çg+w\$‹ÄÕèÛìKÙqùìÈÏïuy@„…†	;sdf-2.001/perllib/004075500042570001753000000000000672243774600135735ustar00iancmtr00000400000236sdf-2.001/perllib/sdf/004075500042570001753000000000000672243775200143445ustar00iancmtr00000400000236sdf-2.001/perllib/sdf/subs.pl010064400042570001753000000727360671627316200156650ustar00iancmtr00000400000236# $Id$
$VERSION{''.__FILE__} = '$Revision$';
#
# >>Title::     SDF Subroutines Library
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# This library provides the built-in subroutines for
# [[SDF]] files.
#
# >>Description::
#
# >>Limitations::
#
# >>Resources::
#
# >>Implementation::
#


# Make sure we can call the Value function from the main package
sub Value {&SDF_USER'Value;}

# Switch to the user package
package SDF_USER;

##### Constants #####

##### Variables #####

# Tables of macro arguments & filter parameters
%_sdf_macro_args_info = ();
@_sdf_macro_args_data = ();
%_sdf_filter_params_info = ();
@_sdf_filter_params_data = ();

# Cache of views
%_sdf_view_cache = ();

##### Initialisation #####

#
# >>Description::
# {{Y:InitSubs}} initialises the global variables in this module.
#
sub InitSubs {

    %_sdf_macro_args_info = ();
    @_sdf_macro_args_data = ();
    %_sdf_filter_params_info = ();
    @_sdf_filter_params_data = ();
    %_sdf_view_cache = ();
}

##### Routines #####

#
# >>Description::
# {{Y:Var}} returns the value of a variable.
#
sub Var {
    local($name) = @_;
    local($value);

    # Activate event processing
    $value = $var{$name};

    # Return result
    return $value;
}

#
# >>Description::
# {{Y:Escape}} escape special symbols within paragraph text.
# Note that it isn't necessary to escape leading characters or patterns.
#
sub Escape {
    local($text) = @_;
#   local();

    $text =~ s/[<>]/$& eq '>' ? 'E' : 'E'/eg;
    if ($text =~ s/\[\[/E<2[>/g) {
        $text =~ s/\]\]/E<2]>/g;
    }
    if ($text =~ s/\{\{/E<2{>/g) {
        $text =~ s/\}\}/E<2}>/g;
    }
    return $text;
}

#
# >>Description::
# {{Y:FormatVar}} formats a variable.
#
sub FormatVar {
    local($fmt, $data) = @_;
    local($result);

    $fmt = $var{$fmt} if &Var($fmt) ne '';
    return sprintf($fmt, &Var($data));
}

#
# >>Description::
# {{Y:FormatTime}} formats a datetime variable.
#
sub FormatTime {
    local($fmt, $time) = @_;
    local($result);

    $fmt = $var{$fmt} if $var{$fmt} ne '';
    $time = $var{$time} if $var{$time} ne '';
    return $time ? &'MiscDateFormat($fmt, $time) : '';
}

#
# >>Description::
# {{Y:PrependText}} is used within a paragraph event handler to
# add [[SDF]] before this paragraph.
#
sub PrependText {
    local(@sdf) = @_;
#   local();

    unshift(@_prepend, @sdf);
}

#
# >>Description::
# {{Y:AppendText}} is used within a paragraph event handler to
# add [[SDF]] after a paragraph.
#
sub AppendText {
    local(@sdf) = @_;
#   local();

    push(@_append, @sdf);
}

#
# >>Description::
# {{Y:DefineAttrs}} is used within a paragraph or phrase event handler to
# define attributes.
#
sub DefineAttrs {
    local(%new) = @_;
#   local();
    local($new);

    for $new (keys %new) {
        $attr{$new} = $new{$new};
    }
}

#
# >>Description::
# {{Y:DefaultAttrs}} is used within a paragraph or object event handler to
# define attributes not already set.
#
sub DefaultAttrs {
    local(%new) = @_;
#   local();
    local($new);

    for $new (keys %new) {
        $attr{$new} = $new{$new} unless defined($attr{$new});
    }
}

#
# >>Description::
# {{Y:FindFile}} searches the include path for the nominated file.
# If the file is found, the pathname of the file is returned,
# otherwise the empty string is returned. If {{image}} is true,
# a target-specific set of extensions is searched for,
# complete with implicit image format conversion.
#
sub FindFile {
    local($filename, $image) = @_;
    local($fullname);

    # Get the list of directories to search
    use Cwd;
    my @dirs = ('.');
    my $dir = $var{'DOC_DIR'};
    push(@dirs, $dir) if $dir ne cwd();
    push(@dirs, @include_path, $'sdf_lib);

    # Do the search
    if ($image) {
        my $context = $var{'OPT_TARGET'};
        my @exts = @{$'SDF_IMAGE_EXTS{$context} || $'SDF_IMAGE_EXTS{'ps'}};
        &'AppTrace("user", 5, "searching for image '$filename' in directories (" .
          join(",", @dirs) . ") with $context extensions (" .
          join(",", @exts) . ")");
        $fullname = &'NameFindOrGenerate($filename, \@dirs, \@exts, $context);
    }
    else {
        &'AppTrace("user", 5, "searching for file '$filename' in directories (" .
          join(",", @dirs) . ")");
        $fullname = &'NameFind($filename, @dirs);
    }

    # Return results
    &'AppTrace("user", 2, "file '$filename' -> '$fullname'") if
      $fullname ne '';
    return $fullname;
}

#
# >>Description::
# {{Y:FindModule}} searches the module path for the nominated file.
# If the file is found, the pathname of the file is returned,
# otherwise the empty string is returned.
#
sub FindModule {
    local($filename) = @_;
    local($fullname);

    # Get the list of directories to search
    use Cwd;
    my @dirs = ('.');
    my $dir = $var{'DOC_DIR'};
    push(@dirs, $dir) if $dir ne cwd();
    push(@dirs, @module_path, $'sdf_lib, "$'sdf_lib/stdlib");

    # Do the search
    &'AppTrace("user", 4, "searching for module '$filename' in directories (" .
      join(",", @dirs) . ")");
    $fullname = &'NameFind($filename, @dirs);

    # Return results
    &'AppTrace("user", 2, "module '$filename' -> '$fullname'") if
      $fullname ne '';
    return $fullname;
}

#
# >>Description::
# {{Y:FindLibrary}} searches the library path for a library and
# returns the directory name of the library. If the library is not
# found, an empty string is returned.
#
sub FindLibrary {
    local($lib) = @_;
    local($fullname);
    local($lib_path);

    # Get the list of directories to search
    use Cwd;
    my @dirs = ('.');
    my $dir = $var{'DOC_DIR'};
    push(@dirs, $dir) if $dir ne cwd();
    push(@dirs, @library_path, $'sdf_lib);

    # Do the search
    &'AppTrace("user", 3, "searching for library '$lib' in directories (" .
      join(",", @dirs) . ")");
    $fullname = '';
    for $dir (@dirs) {
        $lib_path = $dir eq $'NAME_DIR_SEP ? "$dir$lib" : "$dir$'NAME_DIR_SEP$lib";
        if (-d $lib_path) {
            $fullname = $lib_path;
            last;
        }
    }

    # Return results
    &'AppTrace("user", 2, "library '$lib' -> '$fullname'") if
      $fullname ne '';
    return $fullname;
}

#
# >>Description::
# {{Y:ExecMacro}} executes a macro.
# This routine validates the arguments and either:
#
# * gets the macro data (for macros implemented in [[SDF]]), or
# * calls the matching subroutine (for macros implemented in [[Perl]]).
#
# {{missing}} determines the action if the macro isn't found:
#
# * {{ok}} - do nothing
# * {{warning}} - report a warning
# * {{error}} - report an error.
#
sub ExecMacro {
    local($name, $args, $missing) = @_;
    local(@text);
    local($macro_fn);

    # Set the context for messages
    $'app_context = 'macro on ' unless $'sdf_sections;

    # Activate event processing
    &ReportEvents('macro') if @'sdf_report_names;
    &ExecEventsNameMask(*evcode_macro, *evmask_macro) if @evcode_macro;
    &ReportEvents('macro', 'Post') if @'sdf_report_names;

    # Macros implemented in Perl have a subroutine which can be called
    $macro_fn = $name . "_Macro";
    if (defined &$macro_fn) {

        # Validate the arguments and call the matching subroutine
        @text = &$macro_fn(&SdfMacroArgs($name, $args));

        # For macros which generate output which doesn't come from a file,
        # we need to make the output a section so that line numbers don't
        # increment within the generated output.
        return ()    unless @text;
        return @text if $name =~ /^_/ || $text[0] =~ /^\!_bof/;
        return ("!_bos_ $'app_lineno;macro on ", @text,
                "!_eos_ $'app_lineno;$'app_context");
    }

    # For macros implemented in SDF, the macro is stored in %macro
    elsif (defined($macro{$name})) {

        # Validate the arguments
        &'AppMsg("warning", "ignoring arguments for macro '$name'") if $args ne '';

        # Return the data
        return ("!_bos_ $'app_lineno;macro on ", split("\n", $macro{$name}),
                "!_eos_ $'app_lineno;$'app_context");
    }

    # If we reach here, macro is unknown
    if ($missing eq 'error') {
        &'AppMsg("error", "unknown macro '$name'");
    }
    elsif ($missing eq 'warning') {
        &'AppMsg("warning", "unknown macro '$name'");
    }
    return ();
}

#
# >>Description::
# {{Y:ExecFilter}} applies a filter to a block of text.
# This routine validates the parameters and calls the matching subroutine.
# {{lineno}}, {{filename}} and {{context}} are used for messages,
# if provided.
sub ExecFilter {
    local($name, *text, $params, $lineno, $filename, $context) = @_;
#   local();
    local($orig_lineno, $orig_filename, $orig_context);
    local($filter_fn);
    local($plug_in);

    # Do nothing unless there's a filter
    return if $name eq '';

    # Setup the message parameters, if necessary
    $orig_lineno   = $'app_lineno;
    $orig_filename = $'ARGV;
    $orig_context  = $'app_context;
    $'app_lineno   = $lineno    if defined $lineno;
    $'ARGV         = $filename  if defined $filename;
    $'app_context  = $context   if defined $context;

    # Activate event processing
    &ReportEvents('filter') if @'sdf_report_names;
    &ExecEventsNameMask(*evcode_filter, *evmask_filter) if @evcode_filter;
    &ReportEvents('filter', 'Post') if @'sdf_report_names;

    # If necessary, load the plug-in, if any
    $filter_fn = $name . "_Filter";
    if (defined &$filter_fn ||
        $lang_aliases{$name}) {
        # do nothing
    }
    else {
        $plug_in = &FindModule(&'NameJoin('', $name, 'sdp'));
        if ($plug_in) {
            unless (require $plug_in) {
                &'AppMsg("warning", "unable to load plug-in '$plug_in'");
            }
        }
    }

    # Call the filter. If a function is not defined for the filter,
    # it may be a programming language.
    if (defined &$filter_fn) {
        &$filter_fn(*text, &SdfFilterParams($name, $params));
    }
    elsif ($lang_aliases{"\L$name"}) {
        $params .= "; lang='$name'";
        &example_Filter(*text, &SdfFilterParams('example', $params));
    }
    else {
        &'AppMsg("error", "unknown filter '$name'");
    }

    # Restore the message parameters
    $'app_lineno  = $orig_lineno;
    $'ARGV        = $orig_filename;
    $'app_context = $orig_context;
}

#
# >>Description::
# {{Y:SdfMacroArgs}} parses and checks the arguments for a macro.
#
sub SdfMacroArgs {
    local($macro, $args) = @_;
    local(%arg);
    local($info, $index, $last);
    local($format, @rules);
    local($junk, $name, $type, $default, $rule);
    local($ok, $value);

    # Get the arguments info
    $info = $_sdf_macro_args_info{$macro};
    if ($info ne '') {
        ($index, $last) = split(/:/, $info, 2);
    }
    else {
        # Compile the arguments
        $index = $#_sdf_macro_args_data + 1;
        ($format, @rules) = &'TableParse(eval "\@_${macro}_MacroArgs");
        push(@_sdf_macro_args_data, @rules);
        $last = $#_sdf_macro_args_data;
        $_sdf_macro_args_info{$macro} = join(':', $index, $last);
    }

    # Process the argument table
    for (; $index <= $last; $index++) {
        ($junk, $name, $type, $default, $rule) =
             split(/\000/, $_sdf_macro_args_data[$index], 5);

        # If there is nothing left, use the default, if any
        if ($args eq '') {
            &'AppMsg("error", "argument '$name' missing for macro '$macro'")
              if $default eq '';
            $value = $default eq '_NULL_' ? '' : $default;
        }

        # Otherwise, get the next argument
        else {
            ($value, $args) = &_SdfMacroNextArg($args, $type);

            # Validate the rule, if any
            &'AppMsg("warning", "bad value '$value' for argument '$name' for macro '$macro'")
              if ($value ne '' && !&'MiscCheckRule($value, $rule, $type));
        }

        # Save the value
#print "$macro arg $name=$value<\n";
        $arg{$name} = $value;
    }

    # Return result
    %arg;
}

#
# >>_Description::
# {{Y:_SdfMacroNextArg}} parses the next argument from args.
#
sub _SdfMacroNextArg {
    local($args, $type) = @_;
    local($arg, $rest);

    # Get the next argument. For performance, we only check the
    # first character or two of the type:
    # * sy => symbol
    # * r => rest
    # * f => filter
    # * e => eventid
    $args =~ s/^\s+//;
    return split(/\s+/, $args, 2)   if $type =~ /^sy/;
    return ($args, '')              if $type =~ /^r/;
    return split(/\s*\;/, $args, 2) if $type =~ /^[ef]/;

    # If we reach here, we need to evaluate the argument
    ($arg, $rest) = split(/\s*\;/, $args, 2);
    $arg = &'_SdfEvaluate($arg, $type eq 'condition' ? '' : 'warning');
    return ($arg, $rest);
}

#
# >>Description::
# {{Y:SdfFilterParams}} checks the parameters for a filter.
# {{@rules}} is the table of rules.
#
sub SdfFilterParams {
    local($filter, $params) = @_;
    local(%param);
    local(@param_table);
    local($info, $index, $last);
    local($format, @rules);
    local($junk, $name, $type, $rule);
    local($value);
    local($unknown, %unknown);

    # Get the parameters
    %param = &'SdfAttrSplit($params);

    # Get the parameter table
    @param_table = eval "\@_${filter}_FilterParams";

    # Skip validation if arbitary parameters are permitted
    return %param if $param_table[0] eq 'ANY';

    # Get the parameters info
    $info = $_sdf_filter_params_info{$filter};
    if ($info ne '') {
        ($index, $last) = split(/:/, $info, 2);
    }
    else {
        # Compile the parameters
        $index = $#_sdf_filter_params_data + 1;
        ($format, @rules) = &'TableParse(@param_table);
        push(@_sdf_filter_params_data, @rules);
        $last = $#_sdf_filter_params_data;
        $_sdf_filter_params_info{$filter} = join(':', $index, $last);
    }

    # Validate each parameter, using the order in the rules table
    %unknown = %param;
    for (; $index <= $last; $index++) {
        ($junk, $name, $type, $rule) =
             split(/\000/, $_sdf_filter_params_data[$index], 4);
        $value = $param{$name};
#print "$filter param $name=$value<\n";
        delete $unknown{$name};

        # Validate the rule, if any
        if ($value ne '' && !&'MiscCheckRule($value, $rule, $type)) {
            &'AppMsg("warning", "bad value '$value' for '$name' for filter '$filter'");
        }
    }

    # Check for unknown parameters
    $unknown = join(',', sort keys %unknown);
    if ($unknown ne '') {
        &'AppMsg("warning", "unknown parameter(s) '$unknown' for filter '$filter'");
    }

    # Return result
    return %param;
}

#
# >>Description::
# {{Y:SdfTableParams}} checks the parameters for a table/record/cell macro.
# {{%names}}, {{%types}} and {{%rules}} are the tables of names, types and
# rules respectively.
#
sub SdfTableParams {
    local($macro, $params, *names, *types, *rules) = @_;
    local(%param);
    local($name, $value, $type, $rule);

    # Get the parameters
    %param = &'SdfAttrSplit($params);

    # Remove parameters which only apply to other targets
    &'SdfAttrClean(*param);

    # Check the parameters are legal
    for $name (sort keys %param) {
        $value = $param{$name};
        $type = $types{$name};
        $rule = $rules{$name};
#print "table param $name=$value<\n";

        # Check the parameter is known
        unless ($names{$name}) {
            &'AppMsg("warning", "unknown $macro parameter '$name'");
            delete $param{$name};
            next;
        }

        # Validate the rule, if any
        if ($value ne '' && !&'MiscCheckRule($value, $rule, $type)) {
            &'AppMsg("warning", "bad value '$value' for $macro parameter '$name'");
        }
    }

    # Return result
    return %param;
}

#
# >>Description::
# {{Y:ReportEvents}} calls the report event processing routines, if any.
#
sub ReportEvents {
    local($tag, $post) = @_;
#   local();
    local($rpt);
    local($fn);

    for $rpt (@'sdf_report_names) {
        $fn = "${rpt}_ReportEvent${post}";
        &$fn($tag) if defined &$fn;
    }
}

#
# >>Description::
# {{Y:ExecEventsStyleMask}} executes events of a particular type.
# {{@code}} is the stack of code; {{@mask}} is the stack of masks.
# Masking is done using {{$style}}.
#
sub ExecEventsStyleMask {
    local(*code, *mask) = @_;
#   local();
    local($event, $action, $mask);
    local($old_match_rule);

    # Ensure multi-line matching is enabled
    $old_match_rule = $*;
    $* = 1;

    for ($event = $#code; $event >= 0; $event--) {

        # get the action to execute, if any
        $action = $code[$event];
        next if $action eq '';

        # Mask out events
        $mask = $mask[$event];
        next if $mask ne '' && $style !~ /^$mask$/;
        return if $attr{'noevents'};

        # execute the action
        eval $action;
        &'AppMsg("warning", "execution of '$action' failed: $@") if $@;
    }

    # Restore the multi-line match flag setting
    $* = $old_match_rule;
}

#
# >>Description::
# {{Y:ExecEventsNameMask}} executes events of a particular type.
# {{@code}} is the stack of code; {{@mask}} is the stack of masks.
# Masking is done using {{$name}}.
#
sub ExecEventsNameMask {
    local(*code, *mask) = @_;
#   local();
    local($event, $action, $mask);
    local($old_match_rule);

    # Ensure multi-line matching is enabled
    $old_match_rule = $*;
    $* = 1;

    for ($event = $#code; $event >= 0; $event--) {

        # get the action to execute, if any
        $action = $code[$event];
        next if $action eq '';

        # Mask out events
        $mask = $mask[$event];
        next if $mask ne '' && $name !~ /^$mask$/;

        # execute the action
        eval $action;
        &'AppMsg("warning", "execution of '$action' failed: $@") if $@;
    }

    # Restore the multi-line match flag setting
    $* = $old_match_rule;
}
#
# >>Description::
# {{Y:FileFetch}} handles fetching of files for text inclusion macros.
# Files created under MS-DOS can be included on Unix without
# problems. i.e. trailing Ctrl-M characters are stripped.
#
sub FileFetch {
    local(*file, $fname) = @_;
    local($ok);
    local($_);

    # Fetch the file
    $ok = open(SDF_INCLUDE, $fname);
    if ($ok) {
        @file = ;
        for $_ (@file) {
            s/[ \t\n\r]+$//;
        }
        close(SDF_INCLUDE);
    }

    # Return result
    return $ok;
}

#
# >>Description::
# {{Y:CommandMacro}} is the common processing for macros which
# execute a command on a file.
#
sub CommandMacro {
    local($cmd, %arg) = @_;
    local(@text);
    local($filename, $fullname);

    # Get the file location
    $filename = $arg{'filename'};
    $fullname = &FindFile($filename);
    if ($fullname eq '') {
        &'AppMsg("warning", "unable to find '$filename'");
        return ();
    }

    # Execute the command
    unless (&FileFetch(*text, "$cmd $fullname|")) {
        &'AppMsg("warning", "unable to execute command '$cmd' on '$fullname'");
        return ();
    }

    # Filter the text
    &ExecFilter($arg{'filter'}, *text, $arg{'params'});

    # Return result
    return ("!_bof_ '$fullname'", @text, "!_eof_");
}

#
# >>Description::
# {{Y:CommandFilter}} is the common processing for filters which
# execute a command on text.
#
sub CommandFilter {
    local(*text, $cmd, $filter) = @_;
#   local();

    # For now, assume the text came from FILE_PATH
    my $tmp_file = $var{'FILE_PATH'};

    # When the above assumption is no good, we need to do something like ..
    #unless (open(TMPFILE, ">$tmp_file")) {
    #    &'AppMsg("warning", "unable to open tmp file '$tmp_file' in filter '$filter'");
    #}
    #for my $line (@text) {
    #    print TMPFILE "$line\n";
    #}

    # Execute the command
    @text = ();
    unless (&FileFetch(*text, "$cmd < $tmp_file |")) {
        &'AppMsg("warning", "unable to execute command '$cmd' in filter '$filter'");
    }
}

#
# >>Description::
# {{Y:Related}} handles the related function.
#
sub Related {
    local($topic) = @_;
    local($newsdf);
    local(@groups, @excludes);
    local(@members, %already, $grp, $item);

    # Get the groups
    @groups = split(/\000/, $_sdf_jump_groups{$topic});
    @excludes = ($topic);

    # Get the ordered list of members from the groups
    # To exclude items, we pretend we have found them already
    @members = ();
    %already = ();
    grep($already{$_}++, @excludes);
    for $grp (@groups) {
        for $item (split(/\000/, $_sdf_jump_members{$grp})) {
            if ($already{$item} eq '') {
                push(@members, $item);
                $already{$item}++;
            }
        }
    }
    
    # Create the matching SDF
    $newsdf= '';
    for $item (@members) {
        $newsdf .= "L1:{{J:$item}}\n";
    }

    # Return result
    return $newsdf;
}

#
# >>Description::
# {{Y:CheckParaObject}} is a paragraph event handler which
# makes a paragraph an object if the {{PATTR:obj}} attribute
# is set.
#
sub CheckParaObject {
    local($obj);

    # Do nothing unless this is an object
    return unless defined $attr{'obj'};

    # Convert the paragraph to an object
    $obj = $attr{'obj'};
    delete $attr{'obj'};
    $text = '{{' . &'SdfJoin($obj, $text) . '}}';
}

#
# >>Description::
# {{Y:BuildSectJump}} is a event handler which
# builds the jump attribute for a SECT phrase.
#
sub BuildSectJump {
    local($doc);
    local($id);

    # Make it a cross-reference, but don't change the existing value, if any
    #$attr{'xref'} = 1 unless $attr{'xref'};

    # Do nothing if a jump already exists
    return if defined $attr{'jump'};

    # Convert the text to something which is safe as an id
    $id = &TextToId($text);

    # Convert reference codes to document titles as they are
    # just too long to be nice to use :-)
    if ($attr{'ref'}) {
        $attr{'doc'} = $obj_name{'references',$attr{'ref'},'Document'};
        delete $attr{'ref'};
    }

    # Handle sections in another document
    $doc = $attr{'doc'};
    if ($doc ne '') {
        delete $attr{'doc'};
        unless ($obj_long{'references',$doc}) {
            &'AppMsg('warning', "unknown document '$doc'");
        }
        else {
            #if ($var{'HTML_TOPICS_MODE'} || $var{'HTML_SUBTOPICS_MODE'}) {
            #    &'AppMsg('warning', "cross-document section jumps not yet supported in topics mode");
            #}
            $attr{'jump'} = $obj_long{'references',$doc,'Jump'} . "#$id";
        }
    }

    # Handle sections in this document
    else {
        if ($var{'HTML_TOPICS_MODE'} || $var{'HTML_SUBTOPICS_MODE'}) {
            $attr{'jump'} = $jump{$text} || $jump{$id};
        }
        else {
            $attr{'jump'} = "#$id";
        }
    }
}

#
# >>Description::
# {{Y:TextToId}} converts an arbitary text string to a string
# which is safe to use as an {{id}} attribute.
#
sub TextToId {
    local($text) = @_;

    $text =~ s/([\\'])/\\$1/g;
    $text =~ s/[\?\.]$//;
    return $text;
}

#
# >>Description::
# {{Y:ConvertXRef}} is a event handler which
# convert phrases with an xref attribute to a special style.
#
sub ConvertXRef {

    return unless $attr{'xref'};
    $style = '__xref';
    $text = $attr{'xref'};
    $text = $var{'DEFAULT_XREF_STYLE'} if $text == 1;
}

#
# >>Description::
# {{Y:Value}} returns the value of an attribute for an object ($name)
# in a class. $view is an optional {{view}} name.
# Within a view, the parameters supported are:
#
# * {{prefix_xxx}} - prefix for attribute {{xxx}}
# * {{suffix_xxx}} - suffix for attribute {{xxx}}.
#
sub Value {
    local($class, $name, $attr, $view) = @_;
    local($result);
    local($fn);
    local($fn2);
    local($known);
    local($ok, %param);

    # At the moment, we check the lookup function, then the data store.
    # This allows the function to override the stored value.
    # Is it better to check the stored value first?
    # If so, then should we cache the function results in the store?
    $known = 1;
    $fn = "${class}_${attr}_Value";
    if (defined &$fn) {
        $result = &$fn($name, $view);
    }
    elsif (!defined($result = $obj_name{$class,$name,$attr})) {
        $fn2 = "${class}_Value";
        if (defined &$fn2) {
            ($known, $result) = &$fn2($attr, $name, $view);
        }
    }

    # Apply view, if any
    if ($view) {
        ($ok, %param) = &LoadView($view);
        if ($ok) {
            $result = $param{"prefix_$attr"} . $result;
            $result .= $param{"suffix_$attr"};
        }
        else {
            &'AppMsg("warning", "load of view '$view' failed: $@");
        }
    }

    # Check the attribute is known and return
    unless ($known) {
        &'AppMsg("warning", "undefined attribute '$attr' for object '$name' in class '$class'");
        return '';
    }
#print STDERR "attr: $attr, view: $view, result: $result.\n" if $view;
    return $result;
}

#
# >>Description::
# {{Y:LoadView}} loads view {{name}}.
# The loading rules are:
#
# ^ If a view has already been loaded, it is returned.
# + If the name of a view is a file, then the view
#   is loaded from that file. The format is a same
#   as a set of name-value pairs in an {{FMT:INI}} file.
# + If the name of a view is a directory, then a view
#   with {{prefix_Jump=name/}} is returned.
# + Otherwise, {{ok}} is set to 0 and an empty view is returned.
# 
sub LoadView {
    local($name) = @_;
    local($ok, %params);

    # Check if the view has already been loaded
    if (defined $_sdf_view_cache{$name}) {
        return (1, %{$_sdf_view_cache{$name}});
    }

    # Load set from file, if possible
    if (-f $name) {
        if (open(CONV_SET, $name)) {
            my $nv_text = join("\n", );
            close(CONV_SET);
            %params = &main'AppSectionValues($nv_text);
#print STDERR "nv_text: $nv_text<\n";
#for $igc (sort keys %params) {
#print STDERR "$igc: $params{$igc}.\n";
#}
        }
        else {
            return (0);
        }
    }

    # Build set from directory, if possible
    elsif (-d $name) {
        %params = ('prefix_Jump', "$name/");
    }

    # No luck
    else {
        return (0);
    }

    # Save the view in the cache
    $_sdf_view_cache{$name} = { %params };

    # Return result
    return (1, %params);
}

#
# >>Description::
# {{Y:Previous}} returns the previous paragraph text for a given
# paragraph style.
#
sub Previous {
    local($style) = @_;
#   local($result);

    return $previous_text_for_style{$style};
}

#
# >>Description::
# {{Y:ExpandLink}} returns the expanded text and URL for an L phrase.
#
sub ExpandLink {
    local($text) = @_;
    local($expanded, $url);
    local($page, $sect, $entry);
    local($format);

    # Get the page and section
    ($page, $sect, $entry) = &ParseLink($text);

    # Get the format to use
    if ($page ne '') {
        if ($sect ne '') {
            $format = $var{'FORMAT_LINK_PAGE_SECTION'} ||
                      'the section on "$sect" in the $page manpage';
        }
        elsif ($entry ne '') {
            $format = $var{'FORMAT_LINK_PAGE_ENTRY'} ||
                      'the $entry entry in the $page manpage';
        }
        else {
            $format = $var{'FORMAT_LINK_PAGE'} ||
                      'the $page manpage';
        }
    }
    else {
        $format = $var{'FORMAT_LINK_SECTION'} ||
                  'the section on "$sect"';
    }

    # Expand the text
    $expanded = $format;
    $expanded =~ s/\$page/$page/g;
    $expanded =~ s/\$sect/$sect/g;
    $expanded =~ s/\$entry/$entry/g;

    # Get the URL
    $page =~ s/\s*\(\d\)$//;
    $url = &BuildLinkUrl($page, $sect, $entry);

    # Return the result
    return ($expanded, $url);
}

#
# >>Description::
# {{Y:ParseLink}} parses the text of an L phrase.
#
sub ParseLink {
    local($text) = @_;
    local($page, $sect, $entry);

    if ($text =~ m:/:) {
        ($page, $entry) = split(/\//, $text, 2);
        if ($entry =~ /^"(.*)"$/) {
            $sect = $1;
            $entry = '';
        }
    }
    elsif ($text =~ /^"/ || $text =~ / /) {
        $page = '';
        $sect = $text;
        $entry = '';
    }
    else {
        $page = $text;
        $sect = '';
        $entry = '';
    }
    $sect =~ s/^"//;
    $sect =~ s/"$//;

    return ($page, $sect, $entry);
}

#
# >>Description::
# {{Y:BuildLinkUrl}} generates a url from the parts of a L phrase.
# Special construction and/or searching rules can be provided
# by overriding the default implementation, which is simplistic
# by design.
#
sub BuildLinkUrl {
    local($page, $sect, $entry) = @_;
    local($url);

    $url = $page ne '' ? "$page.html" : '';
    if ($entry ne '') {
        $url .= "#$entry";
    }
    elsif ($sect ne '') {
        $url .= "#$sect";
    }
    return $url;
}

#
# >>Description::
# {{Y:ProcessImageAttrs}} processes a set of image attributes.
# This routine provides the common logic between the import macro
# and import special style.
#
sub ProcessImageAttrs {
    local(*filename, *attr) = @_;
#   local();
    local($fullname);
    local($base);

    # Search for an image file - the 2nd option switches on searching
    # (and converting) of an extension from a target-derived list
    $fullname = &FindFile($filename, 1);

    # take out any silly ./'s that are added  --tjh
    $fullname =~ s/^\.\///;

    # Check the figure exists
    if ($fullname eq '') {
        &'AppMsg("warning", "unable to find image '$filename'");
        $fullname = $filename;
    }
    $attr{'fullname'} = $fullname;

    # Update the filename
    $filename = (&'NameSplit($fullname))[3];

    # Prepend the base location, if necessary
    $base = $attr{'base'};
    if (defined($base)) {
        $filename = $base . $filename;
        delete $attr{'base'};
    }
}

# package return value
1;
) {
    #    &'AppMsg("warning", "sdf-2.001/perllib/sdf/filters.pl010075500042570001753000002025500672237401400163440ustar00iancmtr00000400000236# $Id$
$VERSION{''.__FILE__} = '$Revision$';
#
# >>Title::     SDF Filters Library
#
# >>Copyright::
# Copyright (c) 1992-1999, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 23-Oct-98 ianc    Add datestrings filter
# 29-Jul-97 peterh  Add 'noslide' parameter to topics filter.
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# This library provides the built-in filters for
# [[SDF]] files.
#
# >>Description::
# A filter called {{xxx}} maps to:
#
# * a parameter table called {{_xxx_FilterParams}}
# * a subroutine called {{xxx_Filter}}.
#
# The routine interface is:
#
# =  &xxx_Filter(*text, %param);
#
# :where:
#
# * {{@text}} is the text (original in and result out)
# * {{%param}} is the parameters.
#
# If the text is a table, the filter also has a data model
# (i.e. validation table) called {{xxx_FilterModel}}.
# For mapping tables, the convention is to name
# each associative array xxx_yyy where:
#
# * {{xxx}} is the filter name
# * {{yyy}} is the column name (all in lowercase).
#
# >>Limitations::
# The 'proxy' idea is only supported for phrase styles at the moment.
# Should this be generalised to other configurable entities?
#
# The configuration filters should be rationalised to use one or two
# common support routines.
#
# >>Resources::
#
# >>Implementation::
#


# Switch to the user package
package SDF_USER;

##### Constants #####

##
## >>Description::
## {{Y:TBL_FORMAT}} is the lookup table for default table formats.
## The key is the number of columns.
##
#%TBL_FORMAT = (
#    1,      9,
#    2,      37,
#    3,      334,
#    4,      3331,
#    5,      22222,
#);

#
# >>Description::
# {{Y:DEFAULT_LANG_STYLE}} is the default lookup table for styles used to
# format different parts of a language. The key is the state:
#
# * c - comment
# * a - additional comment
# * s - string
# * l - literal
# * kw - keywords.
#
# By default, comments are placed in italics, keywords in bold and
# strings/literals are fixed-width.
#
# Note: The style must be a single letter as [A-Z]<> style phrases are used.
#
%DEFAULT_LANG_STYLE = (
    'c',    'I',
    'a',    'I',
    's',    'C',
    'l',    'C',
    'kw',   'B',
);

# These are the lookup tables for alignment characters
%_ALIGN_NAMES = (
    'L',    'Left',
    'C',    'Center',
    'R',    'Right',
);
%_VALIGN_NAMES = (
    'T',    'Top',
    'M',    'Middle',
    'B',    'Bottom',
    'L',    'Baseline',
);

# These are the built-in table aliases
%_TABLE_ALIASES = (
    'Columns',  'columns',
    'Rows',     'rows',
    'Grid',     'grid',
    'Plain',    'plain',
    'Shade',    'shade',
);

##### Variables #####

# flag for table validation
$validate = 0;

# tables of topic info and the jumps for a section
@topics = ();
@levels = ();
%topic_label = ();
%topic_level = ();
%topic_prev = ();
%topic_next = ();
%topic_up = ();
%jump = ();
%jump_label = ();

# state of formatting attributes for the sdf filter
%sdf_attrs = ();
@sdf_attr_stk = ();

# lookup table for language styles & definitions
%languages = ();
%lang_aliases = ();
%lang_style = %DEFAULT_LANG_STYLE;
%lang_keywords = ();
%lang_tokens = ();

# mapping tables for document styles/variables
%docstyles_name = ();
%docstyles_to = ();
%docstyles_vars = ();
%variables_name = ();
%variables_type = ();
%variables_rule = ();

# mapping tables for paragraph styles/attributes
%parastyles_name = ();
%parastyles_category = ();
%parastyles_to = ();
%parastyles_attrs = ();
%paraattrs_name = ();
%paraattrs_type = ();
%paraattrs_rule = ();
%paraattrs_to = ();
%paraattrs_map = ();
%paraattrs_attrs = ();

# mapping tables for phrase styles/attributes
%phrasestyles_name = ();
%phrasestyles_category = ();
%phrasestyles_to = ();
%phrasestyles_attrs = ();
%phraseattrs_name = ();
%phraseattrs_type = ();
%phraseattrs_rule = ();
%phraseattrs_to = ();
%phraseattrs_map = ();
%phraseattrs_attrs = ();

# mapping tables for table styles/parameters
%tablestyles_name = ();
%tablestyles_to = ();
%tablestyles_params = ();
%tableparams_name = ();
%tableparams_type = ();
%tableparams_rule = ();
%tableparams_to = ();
%tableparams_map = ();
%tableparams_params = ();

# mapping tables for row parameters
%rowparams_name = ();
%rowparams_type = ();
%rowparams_rule = ();
%rowparams_to = ();
%rowparams_map = ();
%rowparams_params = ();

# mapping tables for cell parameters
%cellparams_name = ();
%cellparams_type = ();
%cellparams_rule = ();
%cellparams_to = ();
%cellparams_map = ();
%cellparams_params = ();


##### Initialisation #####

#
# >>Description::
# {{Y:InitFilters}} initialises the global variables in this module.
#
sub InitFilters {

    @topics = ();
    @levels = ();
    %topic_label = ();
    %topic_level = ();
    %topic_prev = ();
    %topic_next = ();
    %topic_up = ();
    %jump = ();
    %jump_label = ();

    $validate = $'verbose;
    %sdf_attrs = ();
    @sdf_attr_stk = ();

    %languages = ();
    %lang_aliases = ();
    %lang_style = %DEFAULT_LANG_STYLE;

    %docstyles_name = ();
    %docstyles_to = ();
    %docstyles_vars = ();
    %variables_name = ();
    %variables_type = ();
    %variables_rule = ();

    %parastyles_name = ();
    %parastyles_to = ();
    %parastyles_attrs = ();
    %parastyles_category = ();
    %paraattrs_name = ();
    %paraattrs_type = ();
    %paraattrs_rule = ();
    %paraattrs_to = ();
    %paraattrs_map = ();
    %paraattrs_attrs = ();

    %phrasestyles_name = ();
    %phrasestyles_category = ();
    %phrasestyles_to = ();
    %phrasestyles_attrs = ();
    %phraseattrs_name = ();
    %phraseattrs_type = ();
    %phraseattrs_rule = ();
    %phraseattrs_to = ();
    %phraseattrs_map = ();
    %phraseattrs_attrs = ();

    %tablestyles_name = ();
    %tablestyles_to = ();
    %tablestyles_params = ();
    %tableparams_name = ();
    %tableparams_type = ();
    %tableparams_rule = ();
    %tableparams_to = ();
    %tableparams_map = ();
    %tableparams_params = ();

    %rowparams_name = ();
    %rowparams_type = ();
    %rowparams_rule = ();
    %rowparams_to = ();
    %rowparams_map = ();
    %rowparams_params = ();

    %cellparams_name = ();
    %cellparams_type = ();
    %cellparams_rule = ();
    %cellparams_to = ();
    %cellparams_map = ();
    %cellparams_params = ();
}

##### Support Routines #####

#
# >>_Description::
# {{Y:_FilterValidate}} validates the data for a filter which
# expects a table.
#
sub _FilterValidate {
    local(*data, *model) = @_;
#   local();
    local(@parsed_model);

    # It would be better not to parse this each time, but
    # as it only happens during validate mode, its not worth
    # caching the results just yet
    @parsed_model = &'TableParse(@model);
    &'TableValidate(*data, *parsed_model);
}

#
# >>_Description::
# {{Y:_SkipHeader}} skips the top comment in a block of text where
# the commenting conventions are derived from the language ({{lang}}).
# The default language is {{sdf}}. The top comment must be the first
# thing on the first line of the file (except for {{sdf}} files where
# it may start on the second line if the first line is a {{!init}} line).
#
sub _SkipHeader {
    local(*text, $lang) = @_;
#   local();

    # Get the comment conventions for the nominated language
    $lang = 'sdf' if $lang eq '';
    &_SetLang($lang);
    my $start1 = $lang_tokens{'cb'};
    my $end1   = $lang_tokens{'ce'};
    my $start2 = $lang_tokens{'ab'};
    my $end2   = $lang_tokens{'ae'};

    # For SDF files, ignore the !init line for now, if any
    my $init_line = shift(@text) if $text[0] =~ /^\!init/;


    # Remove the line-based comment, if any
    if ($end1 eq "\n") {
        while ($text[0] =~ /^$start1/) {
            shift(@text);
        }
    }               
    elsif ($end2 eq "\n") {
        while ($text[0] =~ /^$start2/) {
            shift(@text);
        }
    }               

    # Remove the stream-based comment, if any
    elsif ($text[0] =~ /^$start1/) {
        while (@text && $text[0] !~ /$end1/) {
            shift(@text);
        }
        shift(@text) if @text;
    }               
    elsif ($text[0] =~ /^$start2/) {
        while (@text && $text[0] !~ /$end2/) {
            shift(@text);
        }
        shift(@text) if @text;
    }               

    # Restore the !init line, if any
    unshift(@text, $init_line) if $init_line;
}

#
# >>_Description::
# {{Y:_Pure}} escapes special symbols within example text.
# Note that it isn't necessary to escape leading characters or
# patterns as the line will be explicitly tagged later.
#
sub _Pure {
    local(*text) = @_;
#   local();
    local($line);

    # Escape phrase patterns
    for $line (@text) {
        $line =~ s/[<>]/$& eq '>' ? 'E' : 'E'/eg;
        if ($line =~ s/\[\[/E<2[>/g) {
            $line =~ s/\]\]/E<2]>/g;
        }
        if ($line =~ s/\{\{/E<2{>/g) {
            $line =~ s/\}\}/E<2}>/g;
        }
    }
}

#
# >>_Description::
# {{Y:_SetLang}} sets the current language to be {{lang}}, i.e. it
# resets the {{lang_token}} and {{lang_keyword}} lookup tables.
# (Thanks to Prachin Ranavat for the initial code.)
#
sub _SetLang {
    local($lang) = @_;
#   local();
    local($x, $name, $value);

    # Get the language tokens
    %lang_tokens = ();
    foreach $x (split(':',$languages{$lang_aliases{$lang}})) {
        ($name, $value) = split('=', $x, 2);

        # Covert vgrind definition metasymbols to perl metasymbols
        $value =~ s/\\d/\\b/g;
        $value =~ s/\\a/.*/g;
        $value =~ s/\\p/\\w+/g;
        $value =~ s/\\e/[^\\\\]?/g;
        $value =~ s/\*/\\*/g;
    	$value = "\n" if $value eq '$';
        $lang_tokens{$name} = $value;
    }

    # Get the keywords
    %lang_keywords = ();
    foreach $x (split(/\s+/, $lang_tokens{'kw'})) {
        $lang_keywords{$x} = 1;
    }
}

#
# >>_Description::
# {{Y:_FmtLang}} formats {{@text}} for the specified language.
# (Thanks to Prachin Ranavat for the initial code.)
#
sub _FmtLang {
    local(*text, $lang) = @_;
#   local();
    local($line);
    local($state);
    local($prefix);

    # Set the current language
    &_SetLang($lang);

    # Process each line of code that needs to be pretty formatted.
    # As each line is a separate paragraph and comments, etc. can
    # be multi-line (but SDF phrases cannot cross paragraph boundaries),
    # we need to end/restart phrases accordingly.
    $state = '';
    for $line (@text) {
        $prefix = $state ? "$lang_style{$state}<" : '';
    	$line =~ s/([^ \r\t\f\(\)\[\]\,\;\=\+\:]+)/&_WordFmt($1, *state)/eg;

        if ($state) {
            $line .= '>';
            $state = '' if $lang_tokens{$state.'e'} eq "\n";
        }
        $line =~ s/(\S)/$prefix$1/ if $prefix;
    }        
}

#
# >>_Description::
# {{Y:_WordFmt}} formats a word of a programming language.
# This routine is used by {{Y:_FmtLang}}.
# (Thanks to Prachin Ranavat for the initial code.)
#
sub _WordFmt {
    local($word, *state) = @_;
    local($result);
    local($start, $token);
    local($keyword);

    # If we are already in a state, look for the ending token
    if ($state) {
        if (($word =~ /$lang_tokens{$state.'e'}$/)) {
            $word .= '>';
            $state = '';
        }
        return $word;
    }

    # Check for a single word within a state
    return "$lang_style{'c'}<$word>" if defined $lang_tokens{'cb'} &&
       $word =~ /^$lang_tokens{'cb'}.*$lang_tokens{'ce'}$/;
    return "$lang_style{'a'}<$word>" if defined $lang_tokens{'ab'} &&
       $word =~ /^$lang_tokens{'ab'}.*$lang_tokens{'ae'}$/;
    return "$lang_style{'s'}<$word>" if defined $lang_tokens{'sb'} &&
       $word =~ /^$lang_tokens{'sb'}.*$lang_tokens{'se'}$/;
    return "$lang_style{'l'}<$word>" if defined $lang_tokens{'lb'} &&
       $word =~ /^$lang_tokens{'lb'}.*$lang_tokens{'le'}$/;

    # Look for a starting token
    for $start ('c', 'a', 's', 'l') {
        $token = $lang_tokens{$start.'b'};
        if (defined $token && $word =~ /^$token/) {
            $state = $start;
            return "$lang_style{$start}<$word";
        }
    }

    # Convert the word to a keyword for matching purposes
    $keyword = $word;
    $keyword =~ tr/A-Z/a-z/ if $lang_tokens{'oc'};

    # Check for a keyword, potentially at the end of a line
    return "$lang_style{'kw'}<$word>\n" if $word =~ s/\n$// &&
      $lang_keywords{$word};
    return "$lang_style{'kw'}<$word>" if $lang_keywords{$word};

    # If we reach here, we found nothing special
    return $word;
}

#
# >>_Description::
# {{Y:_DefineLang}} stores a vgrind-like language definition.
# (Thanks to Prachin Ranavat for the initial code.)
#
sub _DefineLang {
    local(*lang_def) = @_;
#   local();
    local($i, $_, $virtual_line);
    local($langs, $rest, $main, @aliases);

    # Append lines to create a virtual line
    $virtual_line = '';
    for ($i = 0; $i <= $#lang_def; $i++) {
    	$_ = $lang_def[$i];
	    chop;
    	$_ =~ s/\s*\\$//;
    	#$_ =~ s/^\s+://;
    	$_ =~ s/^\s+/ /;
    	$virtual_line .= $_;
    }
    @lang_def = ();

    # Store the definition
    ($langs, $rest) = split(':', $virtual_line, 2);
    ($main, @aliases) = split('\|', $langs);
    $languages{$main} = $rest;
    for $_ ($main, @aliases) {
        $lang_aliases{$_} = $main;
    }
}

##### Topic Filters #####

# sdf - normal sdf
@_sdf_FilterParams = ('ANY');
sub sdf_Filter {
    local(*text, %param) = @_;

    # leave the text as it is, unless attributes are specified
    if (%param) {
        # Using a global variable like this seems like a hack but
        # it does this job nicely, provided with save and restore its value
        push(@sdf_attrs_stk, join("\000", %sdf_attrs));
        %sdf_attrs = %param;
        unshift(@text, "!on paragraph ''; __sdf; &DefaultAttrs(%sdf_attrs)");
        push   (@text, '!off paragraph __sdf',
            '!script %sdf_attrs = split("\000", pop(@sdf_attrs_stk))');
    }
}

# front - front section of (and configuration file for) a manual
@_front_FilterParams = ();
sub front_Filter {
    local(*text, %param) = @_;

    # leave the text as it is
}

# about - about section of a manual
@_about_FilterParams = ();
sub about_Filter {
    local(*text, %param) = @_;

    # For html, leave things as they are
    #return if $var{'OPT_DRIVER'} eq 'html';

    # Use plain headings & exclude them from the table of contents, if necessary
    unshift(@text, '!on paragraph \'H\d\'; __about;' .
                   '$style =~ s/H(\d)/"P" . ($1 + 1)/e;' .
                   'if ($1 == 1) { $attr{"component"} = "prechapter" }' .
                   'else { $attr{"notoc"} = 1 }');
    push   (@text, '!off paragraph __about');
}

# appendix - change headings to appendix style
@_appendix_FilterParams = ();
sub appendix_Filter {
    local(*text, %param) = @_;

    # change headings
    unshift(@text, '!on paragraph \'H\d\'; __appendix; $style =~ s/H/A/');
    push   (@text, '!off paragraph __appendix');
}

# plain - change headings to plain style
@_plain_FilterParams = ();
sub plain_Filter {
    local(*text, %param) = @_;

    # change headings
    unshift(@text, '!on paragraph \'H\d\'; __plain; $style =~ s/H/P/');
    push   (@text, '!off paragraph __plain');
}

##### General Filters #####

# verbatim - fixed width verbatim text
@_verbatim_FilterParams = (
    'Name       Type        Rule',
    'skipheader boolean',
    'lang       string',
    'wide       boolean',
    'listitem   integer',
);
sub verbatim_Filter {
    local(*text, %param) = @_;
    local($style, $attrs, $line);

    # Preprocess the text, if necessary
    my $lang = $param{'lang'};
    &_SkipHeader(*text, $lang) if $param{'skipheader'};

    # Prefix each line with the appropriate example style
    $style = "V";
    if ($param{'wide'} && $param{'listitem'}) {
        $attrs = "[wide;in=$param{'listitem'}]";
    }
    elsif ($param{'wide'}) {
        $attrs = '[wide]';
    }
    else {
        $attrs = $param{'listitem'} ? "[in=$param{'listitem'}]" : ':';
    }
    for $line (@text) {
        $line = "$style$attrs$line";
    }
}

# example - fixed width text
@_example_FilterParams = (
    'Name       Type        Rule',
    'skipheader boolean',
    'lang       string',
    'wide       boolean',
    'listitem   integer',
    'pure       boolean',
);
sub example_Filter {
    local(*text, %param) = @_;
    local($style, $attrs, $line);

    # Preprocess the text, if necessary. Note that pretty printing
    # implies pure processing, so that special characters within the
    # source code are protected.
    my $lang = $param{'lang'};
    $lang = "\L$lang";
    &_SkipHeader(*text, $lang) if $param{'skipheader'};
    &_Pure(*text)              if $param{'pure'} || $lang ne '';
    &_FmtLang(*text, $lang)    if $lang ne '';

    # Prefix each line with the appropriate example style
    $style = $param{'wide'} ? 'E80' : 'E';
    $attrs = $param{'listitem'} ? "[in=$param{'listitem'}]" : ':';
    for $line (@text) {
        $line = $line =~ /^\f/ ? "PB:$'" : "$style$attrs$line";
    }
}

# note - a notice
@_note_FilterParams = (
    'Name       Type        Rule',
    'label      string',
);
sub note_Filter {
    local(*text, %param) = @_;

    # surround the note with the right stuff
    unshift(@text, $param{'label'} ? "NB[label='$param{'label'}']" : "NB:");
    push   (@text, 'NE:');
}

# table - table in [[TBL]] format
# Parameters are given below.
#
# !block table
# Parameter     Description
# style         overall look of the table
# format        column widths
# title         table caption
# headings      headings (if not the first row in the text)
# tags          colon separated list of phrase styles to apply to columns
# niceheadings  set to 0 to disable _ to space conversion
# noheadings    suppress headings in output
# groups        pattern of group-style rows (default is /:$/)
# type          same as style (provided for backwards compatibility)
# wide          table straddles the side head area of the page
# bgcolor       background colour for a table (HTML only)
# cellpadding   padding size for table cells (HTML only)
# cellspacing   spacing size between table cells (HTML only)
# !endblock
#
@_table_FilterParams = (
    'Name           Type        Rule',
    'align          string',
    'bgcolor        string',
    'bmargin        integer',
    'cellpadding    integer',
    'cellspacing    integer',
    'colaligns      string',
    'coltags        string',
    'colvaligns     string',
    'delete         string',
    'footings       integer',
    'format         string',
    'groups         string',
    'headings       integer',
    'keepindents    boolean',
    'landscape      string',
    'listitem       integer',
    'lmargin        integer',
    'narrow         boolean',
    'niceheadings   boolean',
    'nocalcs        boolean',
    'noheadings     boolean',
    'objects        string',
    'oncell         string',
    'parseline      string',
    'placement      string',
    'rmargin        integer',
    'select         string',
    'sort           string',
    'style          string',
    'tags           string',
    'title          string',
    'tmargin        integer',
    'type           string',
    'where          string',
    'wide           boolean',
    'wrap           integer',
);
sub table_Filter {
    local(*text, %param) = @_;
    local($style, @tbl);
    local($grp_search, @body_tags, $noheadings, $nocalcs, $nice_hdgs, $on_cell);
    local($tbl_header, @flds);
    local(@sort_by);
    local(@delete, @select);
    local(@col_aligns, $align);
    local(@col_valigns, $valign);
    local($bgcolor);
    local($body_start, $footing_count, $footing_start, %default_heading);
    local(@headings, @footings);
    local($row_type, $row_text);
    local($format, $tbl_cols, $fmt_cols);
    local(@sdf, %values, $tag, $cell, %cell);
    local($fld, $width, $height, $row, $col, $last_row, $last_col);
    local(%cover, $hidden, $rowspan, $colspan, $i, $j);
    local($wrap, $wrap_counter);
    local($actual_cols);
    local($keepindents);

    # Get the table style (type is supported for backwards compatibility)
    $style = $param{'style'} ne '' ? $param{'style'} : $param{'type'};
    delete $param{'type'};
    $style = $_TABLE_ALIASES{$style} if $_TABLE_ALIASES{$style};
    $style = &Var('DEFAULT_TABLE_STYLE') if $style eq '';
    $param{'style'} = $style;

    # Activate event processing
    &ReportEvents('table') if @'sdf_report_names;
    &ExecEventsStyleMask(*evcode_table, *evmask_table);
    &ReportEvents('table', 'Post') if @'sdf_report_names;

    # Parse the text into a table
    if (defined $param{'parseline'}) {
        unshift(@text, $param{'parseline'});
        delete $param{'parseline'};
    }
    @tbl = &'TableParse(@text);

    # Filter and sort the table, if requested
    if ($param{'where'} ne '') {
        @tbl = &'TableFilter(*tbl, $param{'where'}, *var);
        delete $param{'where'};
    }
    if ($param{'sort'} ne '') {
        @sort_by = $param{'sort'} == 1 ? () : split(/,/, $param{'sort'});
        @tbl = &'TableSort(*tbl, @sort_by);
        delete $param{'sort'};
    }
    if ($param{'delete'} ne '') {
        @delete = split(/,/, $param{'delete'});
        @tbl = &'TableDeleteFields(*tbl, @delete);
        delete $param{'delete'};
    }
    if ($param{'select'} ne '') {
        @select = split(/,/, $param{'select'});
        @tbl = &'TableSelectFields(*tbl, @select);
        delete $param{'select'};
    }
    
    # The groups attribute is the pattern to match for groups
    if ($param{'groups'} ne '') {
        $grp_search = $param{'groups'};
        $grp_search = ':$' if $grp_search == 1;
        delete $param{'groups'};
    }

    # Get the phrase styles for the columns, if any
    # (tags and objects are supported for backwards compatibility)
    @body_tags = split(",", $param{'coltags'} || $param{'tags'} || $param{'objects'});
    delete $param{'coltags'};
    delete $param{'tags'};
    delete $param{'objects'};

    # Get the alignments for the columns
    if ($param{'colaligns'} =~ /^[LCR]+$/) {
        @col_aligns = ();
        for $align (split(//, $param{'colaligns'})) {
            push(@col_aligns, $_ALIGN_NAMES{$align});
        }
        $param{'colaligns'} = join(',', @col_aligns);
    }
    else {
        @col_aligns = split(/,/, $param{'colaligns'});
    }

    # Get the vertical alignments for the columns
    if ($param{'colvaligns'} =~ /^[TMBL]+$/) {
        @col_valigns = ();
        for $valign (split(//, $param{'colvaligns'})) {
            push(@col_valigns, $_VALIGN_NAMES{$valign});
        }
    }
    else {
        @col_valigns = split(/,/, $param{'colvaligns'});
    }
    delete $param{'colvaligns'};

    # Get the noheadings flag
    $noheadings = $param{'noheadings'};
    delete $param{'noheadings'};

    # Get the nocalcs flag
    $nocalcs = $param{'nocalcs'};
    delete $param{'nocalcs'};

    # Get the niceheadings flag
    $nice_hdgs = defined($param{'niceheadings'}) ? $param{'niceheadings'} : 1;
    delete $param{'niceheadings'};

    # Get the keepindents flag
    $keepindents = $param{'keepindents'};
    delete $param{'keepindents'};

    # Get the background colour
    $bgcolor = $param{'bgcolor'};
    delete $param{'bgcolor'};

    # Get the oncell processing code
    $oncell = $param{'oncell'};
    delete $param{'oncell'};

    # Get the number of logical rows displayed on a physical row
    if (defined $param{'wrap'}) {
        $wrap = $param{'wrap'};
        $wrap_counter = $wrap;
        delete $param{'wrap'};
    }
    else {
        $wrap = 0;
    }

    # Check the column count in the format is ok
    # (Note: TableFieldsCheck checks for duplicate columns)
    $tbl_header = shift @tbl;
    @flds = &'TableFieldsCheck($tbl_header);
    $tbl_cols = scalar(@flds);

    # Calculate the row number of the first body row
    if (defined $param{'headings'}) {
        $body_start = $param{'headings'};
        delete $param{'headings'};
    }
    elsif ($noheadings) {
        $body_start = 0;
    }
    else {
        # Build the default heading:
        # * get a copy of the data so we don't corrupt the fields array
        # * niceheadings => a single _ becomes a space; multiple become 1 less
        %default_heading = ();
        for $fld (@flds) {
            $cell = $fld;
            $cell =~ s/_(_*)/$& eq '_' ? ' ' : $1/eg if $nice_hdgs;
            $default_heading{$fld} = $cell;
        }
        unshift(@tbl, &'TableRecJoin(*flds, %default_heading));
        $body_start = 1;
    }

    # If there are multiple records per rows and heading rows, we
    # duplicate the heading rows as one would expect
    if ($wrap && $body_start) {
        @headings = ();
        for $rec (@tbl[0 .. $body_start - 1]) {
            for $i (1 .. $wrap) {
                push(@headings, $rec);
            }
        }
        splice(@tbl, 0, $body_start, @headings);
        $body_start = scalar(@headings);
    }

    # Calculate the row number of the first footing row,
    # taking care to ignore macro rows
    $footing_start = scalar(@tbl);
    if (defined $param{'footings'}) {
        $footing_count = $param{'footings'};
        delete $param{'footings'};
        if ($footing_count >= 1) {
            $i = $footing_count;
            for ($row = $#tbl; $row > 0; $row--) {
                next if $tbl[$row] =~ /^!/;
                $i--;
                last if $i == 0;
            }
        }
        $footing_start = $row;
    }

    # If there are multiple records per rows and footing rows, we
    # duplicate the footing rows as one would expect
    if ($wrap && $footing_count) {
        @footings = ();
        for $rec (@tbl[$footing_start .. $#tbl]) {
            for $i (1 .. $wrap) {
                push(@footings, $rec);
            }
        }
        splice(@tbl, $footing_start, $footing_count, @footings);
    }

    # Initialise the variables exported for oncell processing
    $last_col = $tbl_cols - 1;
    $last_row = scalar(@tbl) - 1;
    $row = 0;
    $col = 0;

    # Build the output
    %cover = ();
    $actual_cols = $tbl_cols;
    $actual_cols *= $wrap if $wrap;
    @sdf = ("!table $actual_cols;" . &'SdfAttrJoin(*param));
    for $rec (@tbl) {
        if ($rec =~ /^!/) {
            push(@sdf, $rec);
            next;
        }
 
        %values = &'TableRecSplit(*flds, $rec);
        cell:
        for ($col = 0; $col <= $#flds; $col++) {
            $fld = $flds[$col];
            $hidden = $cover{$row,$col};
            $cell = $values{$fld};

            # Decide what type of row this is
            if ($col == 0) {
                if ($row < $body_start) {
                    $row_type = 'Heading';
                }
                elsif ($row == $footing_start) {
                    $wrap_counter = $wrap;
                    $row_type = 'Footing';
                }
                elsif ($row >  $footing_start) {
                    $row_type = 'Footing';
                }
                elsif ($grp_search ne '' && $cell =~ /$grp_search/) {
                    $row_type = 'Group';
                    # group rows reset row wrapping, if any
                    $wrap_counter = $wrap;
                }
                else {
                    $wrap_counter = $wrap if $row_type eq 'Group';
                    $row_type = '';
                }
                $row_text = $row_type ? "!row '$row_type'" : "!row";
                if ($wrap) {
                    if ($wrap_counter++ >= $wrap) {
                        $wrap_counter = 1;
                    }
                    else {
                        $row_text = '';
                    }
                }
                push(@sdf, $row_text) if $row_text;
            }

            # If this cell is covered by the span of another,
            # check that it is blank
            if ($hidden && $cell ne '') {
                &'AppMsg("warning", "ignoring hidden cell ($row,$col)='$cell'");
            }

            # Get the custom cell attributes, if any.
            # Multi-line cells are implicitly 'sdf' already,
            # although the top line may contain other cell attributes
            %cell = ();
            if (substr($cell, 0, 1) eq "\n") {
                ($cell, %cell) = &'SdfParseCell(substr($cell, 1));
                $cell{'sdf'} = 1;
            }
            else {
                ($cell, %cell) = &'SdfParseCell($cell);
            }

            # Enable spreadsheet-like access/calculations
            &calc_table() unless $nocalcs;

            # Handle hidden cells
            if ($hidden) {
                push(@sdf, "!cell hidden");
                next cell;
            }

            # Add the default cell attributes
            unless (defined($cell{'align'})) {
                $cell{'align'} = $col_aligns[$col] if $col_aligns[$col];
            }
            unless (defined($cell{'valign'})) {
                $cell{'valign'} = $col_valigns[$col] if $col_valigns[$col];
            }
            unless (defined($cell{'tag'})) {
                $cell{'tag'} = $row_type eq '' ? $body_tags[$col] : 2;
            }
            unless (defined($cell{'bgcolor'})) {
                $cell{'bgcolor'} = $bgcolor if $bgcolor ne '';
            }
            $cell{'cols'} = 1 unless defined($cell{'cols'});
            $cell{'rows'} = 1 unless defined($cell{'rows'});

            # Activate 'oncell' processing
            if ($oncell) {
                eval $oncell;
                if ($@) {
                    &'AppMsg("error", "oncell processing failed: $@");
                }
            }

            # Cover the cells hidden by this one
            $rowspan = $cell{'rows'};
            $colspan = $cell{'cols'};
            for ($i = 0; $i < $rowspan; $i++) {
                for ($j = 0; $j < $colspan; $j++) {
                    $cover{$row+$i,$col+$j} = 1;
                }
            }

            # Convert the cell contents to SDF, if necessary
            if ($cell{"sdf"}) {
                delete $cell{"sdf"};
            }
            else {
                # Replace leading whitespace with
                # non-breaking spaces if requested
                if ($keepindents) {
                    $cell =~ s/^([ ]+)/'E' x length($1)/eg;
                    #print STDERR "cell is $cell<\n";
                }
                if ($cell{'tag'} ne '') {
                    $cell = "{{" . $cell{'tag'} . ":$cell}}";
                }
                $cell = ":$cell";
            }

            # Add the cell
            delete $cell{'tag'};
            push(@sdf, "!cell " . &'SdfAttrJoin(*cell), split("\n", $cell));
        }

        # We only increment the row number for non-macro rows
        $row++;
    }
    push(@sdf, "!endtable");

    # Update the buffer
    @text = scalar(@sdf) > 2 ? @sdf : ();
}


# ascii_graphic - format a text diagram
sub ascii_graphic_Filter {
    local(*text, %param) = @_;

    @text = grep(s/^/E80:/, @text);
}

# abstract - format a paper abstract
@_abstract_FilterParams = ();
sub abstract_Filter {
    local(*text, %param) = @_;

    # indent margins (18 pts = 1/4 inch) and emphasise the text
    unshift(@text, '!on paragraph \'\'; __abstract; ' .
        '@attr{"left", "right", "first", "obj"} = (18, 18, 18, 1)');
    push   (@text, '!off paragraph __abstract');

    # For HTML and HLP, add a heading
    if ($var{'OPT_TARGET'} eq 'html' || $var{'OPT_TARGET'} eq 'hlp') {
        unshift(@text, 'P1: Abstract');
    }
}

# quote - format a quote
sub quote_Filter {
    local(*text, %param) = @_;

    if ($var{'OPT_DRIVER'} eq 'html') {
        # emphasise the text
        unshift(@text, '!on paragraph \'\'; __quote; $attr{"obj"} = 1');
    }
    else {
        # indent margins (18 pts = 1/4 inch) and emphasise the text
        unshift(@text, '!on paragraph \'\'; __quote; ' .
            '@attr{"left", "right", "first", "obj"} = (18, 18, 18, 1)');
    }
    push(@text, '!off paragraph __quote');
}

# address - format an address
sub address_Filter {
    local(*text, %param) = @_;
#   local();
    local($line);

    for $line (@text) {
        $line = "Addr:$line";
    }
}

# nofill - format a set of lines
sub nofill_Filter {
    local(*text, %param) = @_;
#   local();
    local($para);

    $para = join('{{CHAR:nl}}', @text);
    @text = ($para);
}

# sections - convert text of paragraphs to sections (for HTML and help)
@_sections_FilterParams = ();
sub sections_Filter {
    local(*text, %param) = @_;

    if ($var{'OPT_TARGET'} eq 'html' || $var{'OPT_TARGET'} eq 'hlp') {
        unshift(@text, '!on paragraph \'\'; __sections; $attr{"obj"} = "SECT"');
        #unshift(@text, '!on paragraph \'\'; __sections; $attr{"obj"} = "SECT";'.
        #               '$attr{"text"} = $text; $text =~ s/\\.$//');
        push   (@text, '!off paragraph __sections');
    }
}

# topics - include topics
@_topics_FilterParams = (
    'Name           Type        Rule',
    'intro          string',
    'noslide        boolean',
    'data           boolean',
);
@_topics_FilterModel = (
    'Field      Category    Rule',
    'Topic      mandatory',
    'Label      optional',
    'Level      optional',
    'Next       optional',
    'Prev       optional',
    'Up         optional',
);
sub topics_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($topic);
    local($label);
    local($file);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_topics_FilterModel) if $validate;

    # Get the list of fields
    @flds = &'TableFields(shift @tbl);

    # If this is topics data, store it
    if ($param{'data'}) {
        for $rec (@tbl) {
            %values = &'TableRecSplit(*flds, $rec);
            $file = $values{'Topic'};
            $topic_label{$file} = $values{'Label'};
            $topic_level{$file} = $values{'Level'};
            $topic_next{$file} = $values{'Next'};
            $topic_prev{$file} = $values{'Prev'};
            $topic_up{$file} = $values{'Up'};
        }
        return;
    }

    # When we're building the sub-topics,
    # display the labels as jumps to the sub-topics
    if ($var{'HTML_SUBTOPICS_MODE'}) {
        push(@text, $param{'intro'}) if $param{'intro'} ne '';
        for $rec (@tbl) {
            %values = &'TableRecSplit(*flds, $rec);
            $topic = $values{'Topic'};
            $file = $topic;
            # this next line is needed once topics mode supports files
            # outside the current directory
            #$file = &'NameAbsolute(&FindFile("$topic.sdf"));
            $label = $values{'Label'} ? $values{'Label'} : $topic_label{$file};
            $label = $topic if $label eq '';
            #push(@text, "L1[jump='$topic.html'] $label");

            # Build the topic file
            push(@text, "!include '$topic.sdf'");
        }
    }

    # Otherwise, include the topics as subsections
    else {
        for $rec (@tbl) {
            %values = &'TableRecSplit(*flds, $rec);
            $topic = $values{'Topic'};
            push(@text, "!include '$topic.sdf'");
        }
    }

    unless ($param{'noslide'}) {
        unshift(@text, "!slide_down");
        push(@text, "!slide_up");
    }
}

# jumps - include jumps data
@_jumps_FilterParams = ();
@_jumps_FilterModel = (
    'Field      Category    Rule',
    'Jump       key',
    'Physical   mandatory',
);
sub jumps_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($jump);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_jumps_FilterModel) if $validate;

    # Get the list of fields
    @flds = &'TableFields(shift @tbl);

    # Store the data
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);
        $jump = $values{'Jump'};
        $jump{$jump} = $values{'Physical'};
    }
}

# title - title block for memos, faxes, etc.
@_title_FilterParams = (
    'Name           Type        Rule',
    'type           string',
    'toc            integer',
    'format         string',
);
sub title_Filter {
    local(*text, %param) = @_;
#   local();
    local($format);
    local($params);
    local($target);
    local($title);
    local($logo);

    # Turn the data into a name-values block
    $format = defined($param{'format'}) ? $param{'format'} : '28';
    $params = "format=$format";
    @text = ("!block namevalues; $params", @text, '!endblock');

    # Prepend a title box, if necessary
    $target = $var{'OPT_TARGET'};
    $title = $param{'type'} || $var{'DOC_TYPE'};
    if ($title ne '') {
        if ($target eq 'html') {
            unshift(@text, 'P2[notoc]' . $title);
        }
        else {
            $title = '{{B[family="Helvetica";size=14]' . $title . '}}';
            unshift(@text, '!block box; narrow; wide', $title, '!endblock', 'E:');
        }
    }

    # Prepend a logo, if necessary
    $logo = $var{'DOC_ADMIN_LOGO'} || $var{'DOC_LOGO'};
    $base = $var{'DOC_ADMIN_LOGO_BASE'} || $var{'DOC_LOGO_BASE'};
    if ($logo ne '') {
        unshift(@text, "!import '$logo'; wide; wrap_text; align=Right; base='$base'");
    }

    # Add a table of contents, if requested
    if ($param{'toc'}) {
        push(@text, "!default DOC_TOC $param{'toc'}");
        if ($target eq 'html') {
            push(@text,
                "!block inline; target='html'",
                "",
                "",
                "!endblock");
        }
    }

    # Output a line after the title block
    push(@text, "Line[wide]");
}

# box - put a box around text
@_box_FilterParams = (
    'Name           Type        Rule',
    'align          string',
    'listitem       integer',
    'narrow         boolean',
    'wide           boolean',
    'lines          boolean',
    'bgcolor        string',
    'fill           integer',
);
sub box_Filter {
    local(*text, %param) = @_;
#   local();
    local($line);
    local($params);

    # Set up the default parameters for formatting the table
    $params = 'noheadings; nocalcs; style="columns"; tmargin=6';

    # If requested, turn the lines into a paragraph
    if ($param{'lines'}) {
        for ($line = 0; $line < $#text; $line++) {
            $text[$line] .= "[[nl]]";
        }
        delete $param{'lines'};
        $params .= '; colaligns="C"';
    }

    # Turn the data into a single cell table
    if ($param{'fill'}) {
        unshift(@text, '[fill=' . $param{'fill'} . ']');
        delete $param{'fill'};
    }
    if (%param) {
        $params .= '; ' . &'SdfAttrJoin(*param);
    }
    @text = ("!block table; $params", 'Dummy', '<<', @text, '>>', '!endblock');
}

# namevalues - table of names & values
@_namevalues_FilterParams = (
    'Name           Type        Rule',
    'format         string',
);
@_namevalues_FilterModel = (
    'Field      Category    Rule',
    'Name       optional',
    'Value      optional',
    #'Name2      optional',
    #'Value2     optional',
    #'Name3      optional',
    #'Value3     optional',
);
sub namevalues_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($target);
    local($format);
    local($width);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    &_FilterValidate(*tbl, *_namevalues_FilterModel) if $validate;

    # Decide on the format
    if ($param{'format'}) {
        $format = $param{'format'};
    }
    else {
        # The first column must be at least 90 points in size and
        # is sized so that the second column is aligned with either
        # normal paragraphs or progressively indented list paragraphs
        $width = $var{'OPT_SIDEHEAD_WIDTH'} + $var{'OPT_SIDEHEAD_GAP'} - 2;
        if ($var{'OPT_LIST_INDENT'} > 0) {
            $width += $var{'OPT_LIST_INDENT'} while $width <= 90;
        }
        $format = $width . 'pt';
    }

    # Process the data
    $target = $var{'OPT_TARGET'};
    if ($target eq 'html' || $target eq 'hlp' ||
        $target eq 'txt' || $target eq 'pod') {
        unshift(@text, "!block table; noheadings; style='plain'; tags='B,,B,,B'; wide; format='$format'");
        push(@text, "!endblock");
    }
    else {
        @text = ();
        (@flds) = &'TableFields(shift @tbl);
        for $rec (@tbl) {
            %values = &'TableRecSplit(*flds, $rec);
            push(@text, "NV[label='$values{'Name'}\\t']$values{'Value'}");
        }
    }
}

# define - variable definitions
@_define_FilterParams = (
    'Name       Type        Rule',
    'family     string      <\w+>',
    'export     boolean',
);
@_define_FilterModel = (
    'Field      Category    Rule',
    'Name       key         <\w+>',
    'Value      optional',
);
sub define_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($family, $export, $name);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_define_FilterModel) if $validate;

    # Process the data
    $family = $param{'family'};
    $family .= '_' if $family ne '';
    $export = $param{'export'};
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);
        $name = $family . $values{'Name'};
        push(@text, "!define $name $values{'Value'}");
        push(@text, "!export $name") if $export;
    }
}

# default - variable defaulting
@_default_FilterParams = (
    'Name       Type        Rule',
    'family     string      <\w+>',
    'export     boolean',
);
@_default_FilterModel = (
    'Field      Category    Rule',
    'Name       key         <\w+>',
    'Value      optional',
);
sub default_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($family, $export, $name);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_default_FilterModel) if $validate;

    # Process the data
    $family = $param{'family'};
    $family .= '_' if $family ne '';
    $export = $param{'export'};
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);
        $name = $family . $values{'Name'};
        push(@text, "!default $name $values{'Value'}");
        push(@text, "!export $name") if $export && !$export{$name};
    }
}

# script - embedded Perl
@_script_FilterParams = ();
sub script_Filter {
    local(*text, %param) = @_;

    # execute the code
    eval join("\n", @text);
    if ($@) {
        &'AppMsg("error", "script failed: $@");
    }
    @text = ();
}

# pod - embedded Pod
@_pod_FilterParams = (
    'Name       Type        Rule',
    'main       boolean',
);
sub pod_Filter {
    local(*text, %param) = @_;

    use Pod::Sdf;
    @text = pod2sdf(\@text, \%param);
}

# get - get embedded documentation (sdfget format)
@_get_FilterParams = (
    'Name       Type        Rule',
    'report     string',
    'rule       string',
    'filename   string',
    'inverse    boolean',
);
sub get_Filter {
    local(*text, %param) = @_;

    # Guess the filename. We need to do this because sdfget is getting
    # it's input from stdin
    $param{'filename'} ||= $var{'FILE_PATH'};

    # Build the options
    my $opts = "-g$param{'rule'} -f$param{'filename'} ";
    $opts .= $param{'inverse'} ? "-i" : "-r$param{'report'}";

    # Get the documentation
    &CommandFilter(*text, "sdfget $opts -", "get");
}

# inline - embedded target code
@_inline_FilterParams = (
    'Name       Type        Rule',
    'target     string      <\w+>',
    'expand     boolean',
);
sub inline_Filter {
    local(*text, %param) = @_;
    local($line);

    # The default target is 'html'
    $target = $param{'target'} || 'html';

    # Prefix each line with the appropriate style
    for $line (@text) {
        if ($param{'expand'}) {
            next if $line =~ /^\s*\!/;
            $line = &main::_SdfParaExpand($line);
        }
        $line = "__inline[target='$target']$line";
    }
}

# end - prepend finalisation text
@_end_FilterParams = ();
sub end_Filter {
    local(*text, %param) = @_;

    # We prepend a blank line so that multiple end sections remain separate.
    unshift(@'sdf_end, '', @text);
    @text = ();
}

# comment - ignore text
@_comment_FilterParams = ('ANY');
sub comment_Filter {
    local(*text, %param) = @_;

    @text = ();
}

# toc_html - format the table of contents for html
@_toc_html_FilterParams = ();
sub toc_html_Filter {
    local(*text, %param) = @_;
#   local();
    local($toc_text, $toc_tag);

    # Prepend a section separator and a title
    $toc_text = $var{'DOC_TOC_TITLE'};
    $toc_text = 'Table of Contents' unless $toc_text;
    $toc_tag = $parastyles_to{'TOCT'};
    $toc_tag = "P2" unless $toc_tag;
    unshift(@text, "!HTML_PRE_SECTION", $toc_tag . "[noevents;notoc]$toc_text");
}

# offices - format a set of office locations
@_offices_FilterParams = (
    'Name       Type        Rule',
    'style      string',
);
sub offices_Filter {
    local(*text, %param) = @_;
    local(@result);
    local($line, $cell_count);

    # Init things
    $style = $param{'style'} || 'plain';
    @result = ("!table 2; format=55; wide; tmargin=12; bmargin=4; style='$style'");

    # Place each address into a cell, 2 cells per row
    $cell_count = 0;
    for $line (@text) {
        $line =~ s/\s+$//;

        # Skip blank lines and comments
        next if $line eq '';
        next if $line =~ /^\s*#/;

        # Handle group entries
        if ($line =~ /^GROUP:\s*/) {
            $cell_count = 0;
            push(@result,
                "!row 'Group'",
                "!cell cols=2; tmargin=14; bmargin=6; truling=Thin; bruling=Thin",
                "N[size='11pt';bold]$'");
        }

        # Handle office titles
        elsif ($line =~ /:$/) {
            push(@result, "!row") if $cell_count++ % 2 == 0;
            push(@result, "!cell");
            push(@result, "N[size='10pt']{{B:$line}}");
        }

        # Handle phone and fax numbers
        elsif ($line =~ /^Ph:\s*/) {
            push(@result, "N[size='10pt';tabs='36pt']Ph:[[tab]]$'");
        }
        elsif ($line =~ /^Fax:\s*/) {
            push(@result, "[[nl]]Fax:[[tab]]$'");
        }

        # Handle address lines
        else {
            push(@result, "[[nl]]$line");
        }
    }

    # Finalise things
    @text = (@result, "!endtable");
}

##### Help Filters #####

# hlp_header - table of jumps in the non-scrolling region
@_hlp_header_FilterParams = ();
@_hlp_header_FilterModel = (
    'Field      Category    Rule',
    'Text       key',
    'Kind       optional    '
);
sub hlp_header_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($item, @items,$thetext);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_hlp_header_FilterModel) if $validate;

    # Unless we're generating help, skip the rest
    return unless $var{'OPT_TARGET'} eq 'hlp';

    # Process the data
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);
        $thetext=$values{'Text'};
        if ($values{'Kind'} eq 'jump') {
            $item = "{{N[jump='#jump_${topic}_$thetext';size='8 pt'] $thetext}}";
        } else {
            $item = "{{N[hlp.popup='#jump_${topic}_$thetext';size='8 pt'] $thetext}}";
        }
        push(@items, $item);
    }

    # Format the output
    @text = ("[hlp.header]" . join("{{E:  }}", @items));
}

# hlp_window - contents of a popup window (by TJH)
@_hlp_window_FilterParams = ();
sub hlp_window_Filter {
    local(*text, %param) = @_;

    unshift(@text,'!on paragraph ; __window_filter; $attr{"hlp.window"} = "1"');
    push(@text,"!off paragraph __window_filter","[hlp.endwindow=1]");
}

##### Configuration Filters #####

# langdefs - load a set of (vgrind-like) language definitions
@_langdefs_FilterParams = ();
sub langdefs_Filter {
    local(*text, %param) = @_;
#   local();
    local($_, @language_definition);

    # append lines until each language definition is complete &
    # then process definition
    @language_definition = ();
    for $_ (@text) {
        next if (/^#/);
        push(@language_definition, $_);
#print "line:$_<\n";
        &_DefineLang(*language_definition) unless /\\$/;
    }    
    @text = ();
}

# docstyles - document style definitions
@_docstyles_FilterParams = ();
@_docstyles_FilterModel = (
    'Field      Category    Rule',
    'Name       key         <\w+>',
    'To         optional',
    'Variables  optional',
);
sub docstyles_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($name);
    local($to);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_docstyles_FilterModel) if $validate;

    # Process the data
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);

        # Update the declaration, if necessary
        $name = $values{'Name'};
        $docstyles_name{$name} = 1;

        # Update the definition, if any
        $to = $values{'To'};
        if ($to ne '') {
            $docstyles_to{$name} = $to;
            $docstyles_vars{$name} = $values{'Variables'};
        }
    }
}

# variables - variable declarations
@_variables_FilterParams = (
    'Name       Type        Rule',
    'family     string      <[\w,]+>',
    'export     boolean',
);
@_variables_FilterModel = (
    'Field      Category    Rule',
    'Name       key         <\w+>',
    'Type       mandatory   <\w+>',
    'Rule       optional',
);
sub variables_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local(@family, $export);
    local($name);
    local($type, $rule);
    local($family, @fullname);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_variables_FilterModel) if $validate;

    # Process the data
    @family = split(/,/, $param{'family'});
    $export = $param{'export'};
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);

        # Update the declaration
        $name = $values{'Name'};
        $type = $values{'Type'};
        $rule = $values{'Rule'};
        if (@family) {
            for $family (@family) {
                $fullname = "${family}_$name";
                $variables_name{$fullname} = 1;
                $variables_type{$fullname} = $type;
                $variables_rule{$fullname} = $rule if $rule ne '';

                # Mark the variable as exported, if requested
                push(@text, "!export $fullname") if $export;
            }
        }
        else {
            $variables_name{$name} = 1;
            $variables_type{$name} = $type;
            $variables_rule{$name} = $rule if $rule ne '';

            # Mark the variable as exported, if requested
            push(@text, "!export $name") if $export;
        }
    }
}

# parastyles - paragraph style definitions
@_parastyles_FilterParams = ();
@_parastyles_FilterModel = (
    'Field      Category    Rule',
    'Name       key         <[A-Z_0-9]\w*>',
    'Category   optional    ',
    'To         optional    <[\w ]+>',
    'Attributes optional',
);
sub parastyles_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($name, $category);
    local($to);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_parastyles_FilterModel) if $validate;

    # Process the data
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);

        # Update the declaration, if necessary
        $name = $values{'Name'};
        $category = $values{'Category'};
        $parastyles_name{$name} = 1;
        $parastyles_category{$name} = $category if $category ne '';

        # Update the definition, if any
        $to = $values{'To'};
        if ($to ne '') {
            $parastyles_to{$name} = $to;
            $parastyles_attrs{$name} = $values{'Attributes'};
        }
    }
}

# paraattrs - paragraph attribute definitions
@_paraattrs_FilterParams = (
    'Name       Type        Rule',
    'family     string      <\w+>',
);
@_paraattrs_FilterModel = (
    'Field      Category    Rule',
    'Name       key         <\w+>',
    'To         optional    <\w+>',
    'Map        optional    <[\%\&]\w+>',
    'Attributes optional',
    'Type       optional    <\w+>',
    'Rule       optional',
);
sub paraattrs_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($family);
    local($name);
    local($type, $rule);
    local($to, $map, $attrs);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_paraattrs_FilterModel) if $validate;

    # Process the data
    $family = $param{'family'} ne '' ? "$param{'family'}." : '';
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);

        # Update the declaration, if necessary
        $name = $family . $values{'Name'};
        $type = $values{'Type'};
        $rule = $values{'Rule'};
        $paraattrs_name{$name} = 1;
        $paraattrs_type{$name} = $type if $type ne '';
        $paraattrs_rule{$name} = $rule if $rule ne '';

        # Update the definition, if any
        $to = $values{'To'};
        $map = $values{'Map'};
        $attrs = $values{'Attributes'};
        if ($to || $map || $attrs) {
            $paraattrs_to{$name} = $to;
            $paraattrs_map{$name} = $map;
            $paraattrs_attrs{$name} = $attrs;
        }
    }
}

# phrasestyles - phrase style definitions
@_phrasestyles_FilterParams = ();
@_phrasestyles_FilterModel = (
    'Field      Category    Rule',
    'Name       key         <[A-Z_0-9]\w*>',
    'Category   optional    ',
    'To         optional    <\=?\w+>',
    'Attributes optional',
);
sub phrasestyles_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($name, $category);
    local($to);
    local($proxy);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_phrasestyles_FilterModel) if $validate;

    # Process the data
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);

        # Update the declaration, if necessary
        $name = $values{'Name'};
        $category = $values{'Category'};
        $phrasestyles_name{$name} = 1;
        $phrasestyles_category{$name} = $category if $category ne '';

        # Update the definition, if any
        $to = $values{'To'};
        if ($to ne '') {
            if ($to =~ /^\=/) {
                $proxy = $';
                if ($phrasestyles_name{$proxy}) {
                    $to = $phrasestyles_to{$proxy};
                }
                else {
                    &'AppMsg("warning", "unknown phrase style $proxy '$proxy");
                    $to = $proxy;
                }
            }
            $phrasestyles_to{$name} = $to;
            $phrasestyles_attrs{$name} = $values{'Attributes'};
        }
    }
}

# phraseattrs - phrase attribute definitions
@_phraseattrs_FilterParams = (
    'Name       Type        Rule',
    'family     string      <\w+>',
    'para       string',
);
@_phraseattrs_FilterModel = (
    'Field      Category    Rule',
    'Name       key         <\w+>',
    'To         optional    <\w+>',
    'Map        optional    <[\%\&]\w+>',
    'Attributes optional',
    'Type       optional    <\w+>',
    'Rule       optional',
);
sub phraseattrs_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($family, $para);
    local($name, $paraname);
    local($type, $rule);
    local($to, $map, $attrs);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_phraseattrs_FilterModel) if $validate;

    # Process the data
    $family = $param{'family'} ne '' ? "$param{'family'}." : '';
    $para = $param{'para'};
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);

        # Update the declaration, if necessary
        $name = $family . $values{'Name'};
        $paraname = $family . $para . $values{'Name'};
        $type = $values{'Type'};
        $rule = $values{'Rule'};
        $phraseattrs_name{$name} = 1;
        $phraseattrs_type{$name} = $type if $type ne '';
        $phraseattrs_rule{$name} = $rule if $rule ne '';
        $paraattrs_name{$paraname} = 1;
        $paraattrs_type{$paraname} = $type if $type ne '';
        $paraattrs_rule{$paraname} = $rule if $rule ne '';

        # Update the definition, if any
        $to = $values{'To'};
        $map = $values{'Map'};
        $attrs = $values{'Attributes'};
        if ($to || $map || $attrs) {
            $phraseattrs_to{$name} = $to;
            $phraseattrs_map{$name} = $map;
            $phraseattrs_attrs{$name} = $attrs;
            $paraattrs_to{$paraname} = $to;
            $paraattrs_map{$paraname} = $map;
            $paraattrs_attrs{$paraname} = $attrs;
        }
    }
}

# tablestyles - table style definitions
@_tablestyles_FilterParams = ();
@_tablestyles_FilterModel = (
    'Field      Category    Rule',
    'Name       key         <\w+>',
    'To         optional    <\w+>',
    'Parameters optional',
);
sub tablestyles_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($name);
    local($to);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_tablestyles_FilterModel) if $validate;

    # Process the data
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);

        # Update the declaration, if necessary
        $name = $values{'Name'};
        $tablestyles_name{$name} = 1;

        # Update the definition, if any
        $to = $values{'To'};
        if ($to ne '') {
            $tablestyles_to{$name} = $to;
            $tablestyles_params{$name} = $values{'Parameters'};
        }
    }
}

# tableparams - table parameter definitions
@_tableparams_FilterParams = (
    'Name       Type        Rule',
    'family     string      <\w+>',
);
@_tableparams_FilterModel = (
    'Field      Category    Rule',
    'Name       key         <\w+>',
    'To         optional    <\w+>',
    'Map        optional    <[\%\&]\w+>',
    'Parameters optional',
    'Type       optional    <\w+>',
    'Rule       optional',
);
sub tableparams_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($family);
    local($name);
    local($type, $rule);
    local($to, $map, $params);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_tableparams_FilterModel) if $validate;

    # Process the data
    $family = $param{'family'} ne '' ? "$param{'family'}." : '';
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);

        # Update the declaration, if necessary
        $name = $family . $values{'Name'};
        $type = $values{'Type'};
        $rule = $values{'Rule'};
        $tableparams_name{$name} = 1;
        $tableparams_type{$name} = $type if $type ne '';
        $tableparams_rule{$name} = $rule if $rule ne '';

        # Update the definition, if any
        $to = $values{'To'};
        $map = $values{'Map'};
        $params = $values{'Parameters'};
        if ($to || $map || $params) {
            $tableparams_to{$name} = $to;
            $tableparams_map{$name} = $map;
            $tableparams_params{$name} = $params;
        }
    }
}

# rowparams - row parameter definitions
@_rowparams_FilterParams = (
    'Name       Type        Rule',
    'family     string      <\w+>',
);
@_rowparams_FilterModel = (
    'Field      Category    Rule',
    'Name       key         <\w+>',
    'To         optional    <\w+>',
    'Map        optional    <[\%\&]\w+>',
    'Parameters optional',
    'Type       optional    <\w+>',
    'Rule       optional',
);
sub rowparams_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($family);
    local($name);
    local($type, $rule);
    local($to, $map, $params);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_rowparams_FilterModel) if $validate;

    # Process the data
    $family = $param{'family'} ne '' ? "$param{'family'}." : '';
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);

        # Update the declaration, if necessary
        $name = $family . $values{'Name'};
        $type = $values{'Type'};
        $rule = $values{'Rule'};
        $rowparams_name{$name} = 1;
        $rowparams_type{$name} = $type if $type ne '';
        $rowparams_rule{$name} = $rule if $rule ne '';

        # Export the definition, if any
        $to = $values{'To'};
        $map = $values{'Map'};
        $params = $values{'Parameters'};
        if ($to || $map || $params) {
            $rowparams_to{$name} = $to;
            $rowparams_map{$name} = $map;
            $rowparams_params{$name} = $params;
        }
    }
}

# cellparams - cell parameter definitions
@_cellparams_FilterParams = (
    'Name       Type        Rule',
    'family     string      <\w+>',
);
@_cellparams_FilterModel = (
    'Field      Category    Rule',
    'Name       key         <\w+>',
    'To         optional    <\w+>',
    'Map        optional    <[\%\&]\w+>',
    'Parameters optional',
    'Type       optional    <\w+>',
    'Rule       optional',
);
sub cellparams_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($family);
    local($name);
    local($type, $rule);
    local($to, $map, $params);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_cellparams_FilterModel) if $validate;

    # Process the data
    $family = $param{'family'} ne '' ? "$param{'family'}." : '';
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);

        # Update the declaration, if necessary
        $name = $family . $values{'Name'};
        $type = $values{'Type'};
        $rule = $values{'Rule'};
        $cellparams_name{$name} = 1;
        $cellparams_type{$name} = $type if $type ne '';
        $cellparams_rule{$name} = $rule if $rule ne '';

        # Update the definition, if any
        $to = $values{'To'};
        $map = $values{'Map'};
        $params = $values{'Parameters'};
        if ($to || $map || $params) {
            $cellparams_to{$name} = $to;
            $cellparams_map{$name} = $map;
            $cellparams_params{$name} = $params;
        }
    }
}

# targetobjects - define target objects
@_targetobjects_FilterParams = (
    'Name       Type        Rule',
    'type       string      <\w+>',
);
@_targetobjects_FilterModel = (
    'Field      Category    Rule',
    'Name       key',
    'Parent     optional',
    'Attributes optional',
);
sub targetobjects_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($type);
    local(%attrs);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_targetobjects_FilterModel) if $validate;

    # Process the data
    $type = $param{'type'};
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);
        %attrs = &'SdfAttrSplit($values{'Attributes'});
        $attrs{'Name'} = $values{'Name'};
        $attrs{'Parent'} = $values{'Parent'};
        push(@text, &'SdfJoin("__object", $type, %attrs));
    }
}

# datestrings - date strings for month, weekday, etc.
@_datestrings_FilterParams = (
);
@_datestrings_FilterModel = (
    'Field      Category    Rule',
    'Symbol     key         ',
    'Values     optional',
);
sub datestrings_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($strings);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_datestrings_FilterModel) if $validate;

    # Process the data
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);
        $strings = [ split(/\s+/, eval $values{'Values'}) ];
        $main::misc_date_strings{$values{'Symbol'}} = $strings;
    }
}

# meta - meta information about a document
@_meta_FilterParams = (
);
@_meta_FilterModel = (
    'Field      Category    Rule',
    'Name       key',
    'Content    optional',
);
sub meta_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_meta_FilterModel) if $validate;

    # Process the data
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);
        push(@text, &'SdfJoin("__object", "meta", %values));
    }
}

# links - links for a document
@_links_FilterParams = (
);
@_links_FilterModel = (
    'Field              Category    Rule',
    'Jump               key',
    'Type               optional',
    'Relationship       optional',
);
sub links_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &_FilterValidate(*tbl, *_links_FilterModel) if $validate;

    # Process the data
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);
        $values{'Type'} = 'text/css' if $values{'Type'} eq '';
        $values{'Relationship'} = 'stylesheet' if $values{'Relationship'} eq '';
        push(@text, &'SdfJoin("__object", "link", %values));
    }
}

# stylesheet - stylesheet rules for a document
@_stylesheet_FilterParams = (
);
@_stylesheet_FilterModel = (
);
sub stylesheet_Filter {
    local(*text, %param) = @_;

    # Process the data
    @text = (&'SdfJoin("__stylesheet", join("\n", @text), %param));
}

# package return value
1;
ds, $rec);

        # Update the declaration, if necessary
        $name = $family . $values{'Name'};
        $paraname = $family . $para . $values{'Namsdf-2.001/perllib/sdf/home/004075500042570001753000000000000672243774200152735ustar00iancmtr00000400000236sdf-2.001/perllib/sdf/home/images/004075500042570001753000000000000672243775200165415ustar00iancmtr00000400000236sdf-2.001/perllib/sdf/home/images/new3.bmp010064400042570001753000000007360613464277600201210ustar00iancmtr00000400000236BMÞv(-hÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿðsdf-2.001/perllib/sdf/home/images/sdf.gif010064400042570001753000000004240641770654200177760ustar00iancmtr00000400000236GIF89aãÿÿÿÿÌ3ÿ33Ìÿÿ™™™™f3fÌÿ333!þNThis art is in the public domain. Kevin Hughes, kevinh@eit.com, September 1995!ù,oðÈIç¸xÀ»ßGvm^I†ÙYq$€Žl4ûaçLrø@˜kW ŽH„ðPh6=„(A©a9ŸÐ(µUê¦Bo\5&Ï2WœÞöÎÉv˜-/sæ8GM/ñ;xpukt}{[R‹ŒQ?p‘H;sdf-2.001/perllib/sdf/home/images/arrow.bmp010064400042570001753000000002260613034304600203510ustar00iancmtr00000400000236BM–v(€€€€€€€€€ÀÀÀ€€€ÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿ
ÿ
 
ª
 ÿ
ÿÿÿsdf-2.001/perllib/sdf/home/images/rd_ball.bmp010064400042570001753000000025660613464300000206240ustar00iancmtr00000400000236BMv6(@ü ü4üDüTüÀÀÀ   ‚‚‚dddFFFÈüÜüìüüüøøøèøØøÈø´ø¤ø”ø„ütüdüTüDü0ü üüøè Ø4ÈD´T¤d”t„ˆt˜d¨T¸DÈ0Ü ìüøðèàØ$Ð,È4À<¸D°L¨T \˜hpˆx€€ÿøòìæàÚÓÍÇÁ»µ®¨¢œ–‰ƒ}wqkd^XRLF@ˆx„pŒ˜h” `œ¨X¤°P¬¸H´À@¼Ä8ÄÌ0ÌÔ(ÔÜ ÜääììŒ8ü`PüH\ü@`ü8dü0hü(lü pütüxü|ü|øxôtðpìlèhädà`Ü\ØXÔTÐPÌLÈHÄDÀ<¼8¸4´0°,¬(¨$¤  œ˜”Œˆ„€`XTLH d,p0x8|<„DˆLŒP”X˜\ d¤h¬p°t¸|¼„ÀˆÈ̔Ԝؠà¨ä¬ì´ð¸øÀüììôôüüää(ÔÔ0ÌÌ8ÄÄ@¼¼H´´P¬¬`œœh””pŒŒx„„Œpp”hhœ``¤XX¬PP´HH¼@@Ä88Ì00Ô((Ü  äììôôüüäÜ Ô(Ì0Ä8¼ @´$H¬(P¤,Xœ0`”4hŒ8p„y× R ý–Ø{Û§™gY§VkQ]Ä`cöšŠü±8âŠCå%_q3FãÄY§£H-ÚGáIAæøcHE¢×Þe¥%§dBÇuä]€Q2õœv":g%R,ÆèÚ–ô	HVwUZ©à^Ži	¦m8±&jî‡ß›h’˜aqt"egQZåÙQ…{ú‰Q™‚Æåa¡ƒ*R@;sdf-2.001/perllib/sdf/home/images/bg_ball.gif010064400042570001753000000017120603732437000205760ustar00iancmtr00000400000236GIF89a÷€€€€€€€€€€€€TŒŒŒ44ÌÜÜÜddœ4œœœÌ4ddœÌ4dÀÀÀddÌìììœÌÌtdœœœ4dÌÌÌü44œœœü44ddœüÄÄÄddüüüüœÌüÀÀÀÿÿÿÿÿÿÿÿÿÿÿÿ!ù,§%H° A	&(È0Áƒƒ74Ø `‚ņl È°!8ÜÐã„4H9pB„1j˜©Á¡À
&V„ÀA…*°”Ðá%E‹D¨T94ƒ’O:Ôð1¡À¢`Z¬êÐâÍ¢0;NðÄ85ª ªÅ
Þ\»‘bÛ¶jD¶n]¹1là{!B‡‰L@²ä#;sdf-2.001/perllib/sdf/home/images/key.gif010064400042570001753000000002020613502631000177650ustar00iancmtr00000400000236GIF89a³¿¿¿¿¿¿¿¿¿ÀÀÀ€€€ÿÿÿÿÿÿÿÿÿÿÿÿ,7ðDé»8ß2Òà,²]íÒfl7!ËVÜÈr’žr	”îl#DS‰¬^¡E#­»¥t‰á)Ùj9kÓÇäY¦òàßÎ:x®bfH_tR}~€‹ns†)]‹Š”’]f™”g”=”z}¢6ž“‹¡‹	xƒ}¢²€´€®–¸¯°Hµ	¿­º¹u©­”ÁµÃ­)xϳÌ×Õ	λa>ÕÖ¸ÛÑÙ	·ÜÔ­ÛÛà¸ÍÍåÒÝA—ãÆžîØÆ®­òAëé÷ò­Ófêž²´­3§O …ĺUP§PÛ3‹áô%ÐbÙÀÊPÕªH’ ?‰mŽZòOcI…Däõð’$Œ._jSž†b³lè,	L‹>5Ä¢3@Å¢å*&Íàì)ÔŠ!«ô‘Js"I$X÷DB@!Ê
/™ôèÓïÌY
NBz"¶›X ëÒUÛo-_nånÒÖ˾‚ç,èQ_uK¼Å@¨¯„È?‘ÁŠ2•îäTL½Œ¸1	(œ5+æBá3×!ft%
;†æAµW°Á”hŠ4»}Ç~\8ÎÆuOÂ4óçÐiD;sdf-2.001/perllib/sdf/home/images/mail1.bmp010064400042570001753000000041660613464277400202470ustar00iancmtr00000400000236BMv6("@€€€€€€€€€ÀÀÀÀÜÀðȤUªÕ++U+€+ª+Õ+ÿUUUU€UªUÕUÿ€U€ª€Õ€ÿªªUª€ªªªÕªÿÕÕUÕ€ÕªÕÕÕÿÿUÿ€ÿªÿÕUUUU€UªUÕUÿU+U+UU+€U+ªU+ÕU+ÿUUUUUUU€UUªUUÕUUÿU€U€UU€€U€ªU€ÕU€ÿUªUªUUª€UªªUªÕUªÿUÕUÕUUÕ€UÕªUÕÕUÕÿUÿUÿUUÿ€UÿªUÿÕUÿÿ€U€ª€Õ€ÿ€+€+U€+€€+ª€+Õ€+ÿ€U€UU€U€€Uª€UÕ€Uÿ€€U€€ª€€Õ€€ÿ€ª€ªU€ª€€ªª€ªÕ€ªÿ€Õ€ÕU€Õ€€Õª€ÕÕ€Õÿ€ÿ€ÿU€ÿ€€ÿª€ÿÕ€ÿÿªªUª€ªªªÕªÿª+ª+Uª+€ª+ªª+Õª+ÿªUªUUªU€ªUªªUÕªUÿª€ª€Uª€€ª€ªª€Õª€ÿªªªªUªª€ªªªªªÕªªÿªÕªÕUªÕ€ªÕªªÕÕ €ÿªÿªÿUªÿ€ªÿªªÿÕªÿÿÕÕUÕ€ÕªÕÕÕÿÕ+Õ+UÕ+€Õ+ªÕ+ÕÕ+ÿÕUÕUUÕU€ÕUªÕUÕÕUÿÕ€Õ€UÕ€€Õ€ªÕ€ÕÕ€ÿÕªÕªUÕª€ÕªªÕªÕÕªÿÕÕÕÕUÕÕ€ÕÕªÕÕÕÕÕÿÕÿÕÿUÕÿ€ÕÿªÕÿÕÕÿÿÿUÿ€ÿªÿÕÿ+ÿ+Uÿ+€ÿ+ªÿ+Õÿ+ÿÿUÿUUÿU€ÿUªÿUÕÿUÿÿ€ÿ€Uÿ€€ÿ€ªÿ€Õÿ€ÿÿªÿªUÿª€ÿªªÿªÕÿªÿÿÕÿÕUÿÕ€ÿÕªÿÕÕÿÕÿÿÿUÿÿ€ÿÿªðûÿ¤  €€€ÿÿÿÿÿÿÿÿÿÿÿÿøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøùøøøøÿøùùøøÿøøÿøùùøÿÿøøøùùøÿÿøøøøùøÿÿÿÿøøøÿÿÿÿÿÿÿøøøÿÿÿÿÿÿÿÿÿÿøøøÿÿÿÿÿÿÿÿÿÿÿÿøÿÿÿÿÿÿÿÿÿÿÿøøÿÿÿÿÿÿÿÿÿÿÿøøÿÿÿÿÿÿÿÿÿøøÿÿÿÿÿÿÿøøÿÿÿøøøÿøøøøsdf-2.001/perllib/sdf/home/images/next.bmp010064400042570001753000000017260613464277600202230ustar00iancmtr00000400000236BMÖv(=`ÿÿÿÀÀÀ}}}&&& """"""""""""""""""""""""""""" """"""""""""""""""""""""""""              31333131  3313311  3313311  331331  3133311  331331  31131  3113311  3133313331                  """""""""""""""""""""""""""""" sdf-2.001/perllib/sdf/home/images/bk_diam.bmp010064400042570001753000000026620613464276600206320ustar00iancmtr00000400000236BM²6(|ü ü4üDüTüÀÀÀ   ‚‚‚dddFFFÈüÜüìüüüøøøèøØøÈø´ø¤ø”ø„ütüdüTüDü0ü üüøè Ø4ÈD´T¤d”t„ˆt˜d¨T¸DÈ0Ü ìüøðèàØ$Ð,È4À<¸D°L¨T \˜hpˆx€€@@@===;;;999777555333111///---+++)))'''%%%###!!!


ˆx„pŒ˜h” `œ¨X¤°P¬¸H´À@¼Ä8ÄÌ0ÌÔ(ÔÜ ÜääììŒ8ü`PüH\ü@`ü8dü0hü(lü pütüxü|ü|øxôtðpìlèhädà`Ü\ØXÔTÐPÌLÈHÄDÀ<¼8¸4´0°,¬(¨$¤  œ˜”Œˆ„€`XTLH d,p0x8|<„DˆLŒP”X˜\ d¤h¬p°t¸|¼„ÀˆÈ̔Ԝؠà¨ä¬ì´ð¸øÀüììôôüüää(ÔÔ0ÌÌ8ÄÄ@¼¼H´´P¬¬`œœh””pŒŒx„„Œpp”hhœ``¤XX¬PP´HH¼@@Ä88Ì00Ô((Ü  äììôôüüäÜ Ô(Ì0Ä8¼ @´$H¬(P¤,Xœ0`”4hŒ8p„i.üÑÉÄŠB8… ¼rFìžÓñqKÉR‘D’ÚQ²£K”u\déқ͗;f’¬É.æÉœ)Þ8ÙóËO™Aƒü<ÊLˆNŒÿ¤e˜Jµê£ªX³R€ ;sdf-2.001/perllib/sdf/home/images/pdf.gif010064400042570001753000000002310621521432000177470ustar00iancmtr00000400000236GIF87a¢ÿÿÿîîîÝ,f8ºÜ® ÊI窘†žÔIb7 wBëj©xF¬KÇs[Öp˜{\DŒÄ¤o˜8•Iô	¦ÈªTiÌ*·Å¦3!Çg+w\$‹ÄÕèÛìKÙqùìÈÏïuy@„…†	;sdf-2.001/perllib/sdf/home/images/mail2.bmp010064400042570001753000000004660613464277400202470ustar00iancmtr00000400000236BM6v(À~f`×ëúÿÿÿÿ"""""""""""""#3333333333#13##11##11#31#31##13#11#33#3333333333"""""""""""""sdf-2.001/perllib/sdf/home/images/dir.gif010064400042570001753000000003410632211024200177530ustar00iancmtr00000400000236GIF89aÂÿÿÿÿÌ™Ìÿÿ™f3333!þNThis art is in the public domain. Kevin Hughes, kevinh@eit.com, September 1995!ù,T(ºÜþ0ÊIY¹øκïEÄ}d¦)Å@zj‰C,Ç+ŽõWž<œì
IEáqg<²‚N"4ÚIRaV˜VÅÝÂx‚Ôl<&€Ãæ´zÍ#,LðŒ;;sdf-2.001/perllib/sdf/home/images/exclam.bmp010064400042570001753000000041400613014635000204660ustar00iancmtr00000400000236BM`6(&€€€€€€€€€ÀÀÀÀÜÀðʦðûÿ¤  €€€ÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿöøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøööøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøööøööøööÿÿÿÿÿÿøööÿÿÿÿÿøööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿøööÿÿÿÿÿÿÿÿÿÿÿÿøÿÿÿÿÿÿÿÿÿÿøööÿÿÿÿÿÿÿÿÿÿÿøøøÿÿÿÿÿÿÿÿÿøööÿÿÿÿÿûÿûÿûøûÿûÿûÿÿÿÿøööÿÿÿÿÿÿÿûÿÿÿûÿÿÿûÿÿÿûÿÿÿøööÿÿÿÿÿûÿûÿûûÿûÿûÿÿÿÿøööÿÿÿÿÿÿûÿûÿøøøÿûÿûÿÿÿÿøööÿÿÿÿÿÿûÿûøøøûÿûÿÿÿÿÿøööÿÿÿÿÿÿûûÿøøøÿûûÿÿÿÿøööÿÿÿÿÿÿÿûøøøûÿÿÿÿÿÿøööÿÿÿÿÿÿÿûûøøøûûÿÿÿÿÿøööÿÿÿÿÿÿÿûûûûûÿÿÿÿÿÿøööÿÿÿÿÿÿÿÿûûûÿÿÿÿÿÿøööÿÿÿÿÿÿÿÿûûûÿÿÿÿÿÿÿøööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿøööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿööÿÿööööööööööööööööööööööööööööööööööööööösdf-2.001/perllib/sdf/home/images/greenbal.bmp010064400042570001753000000024260613464277200210160ustar00iancmtr00000400000236BM6(à0ÿ4ÿÿ"ÿ$ïçÀÀÀ'ÖÖuÎc)ÎÎÞ‡Æ{ƽ½µ­œ”?Œ1„„sskc	Z
Z	JJÕªÕÕÕÿÿÿUÿ€ÿªÿÕÿÿUUUU€UªUÕUÿU+U+UU+€U+ªU+ÕU+ÿUUUUUUU€UUªUUÕUUÿU€U€UU€€U€ªU€ÕU€ÿUªUœJUª€UªªUªÕUªÿUÕUÎBUÕ€UÕªUÕÕUÕÿ?ÿ!UÿUUÿ€UÿªUÿÕUÿÿ€€U€€€ª€Õ€ÿ€+€+U€+€€+ª€+Õ€+ÿ€U€UU€U€€Uª€UÕ€Uÿ€€€€U€€€€€ª€€Õ€€ÿ€ª€ªU€ª€€ªª€ªÕ€ªÿ€ÕqÎc„Æ{€Õª€ÕÕ€Õÿ€ÿ€ÿU€ÿ€€ÿª€ÿÕ€ÿÿªªUª€ªªªÕªÿª+ª+Uª+€ª+ªª+Õª+ÿªUªUUªU€ªUªªUÕªUÿª€ª€Uª€€ª€ªª€Õª€ÿªªªªUªª€ªªªªªÕªªÿªÕªÕUªÕ€ªÕªªÕÕªÕÿªÿªÿUªÿ€ªÿªªÿÕªÿÿÕÕUÕ€ÕªÕÕÕÿÕ+Õ+UÕ+€Õ+ªÕ+ÕÕ+ÿÕUÕUUÕU€ÕUªÕUÕÕUÿÕ€Õ€UÕ€€Õ€ªÕ€ÕÕ€ÿÕªÕªUÕª€ÕªªÕªÕÕªÿÕÕÕÕUÕÕ€ÕÕªÕÕÕÕÕÿÕÿÕÿUÕÿ€ÕÿªÕÿÕÕÿÿÿÿUÿ€ÿªÿÕÿÿÿ+ÿ+Uÿ+€ÿ+ªÿ+Õÿ+ÿÿUÿUUÿU€ÿUªÿUÕÿUÿÿ€ÿ€Uÿ€€ÿ€ªÿ€Õÿ€ÿÿªÿªUÿª€ÿªªÿªÕÿªÿÿÕÿÕUÿÕ€ÿÕªÿÕÕÿÕÿÿÿÿÿUÿÿ€ÿÿªÿÿÕ???kkk•••¿¿¿ÿÿÿtCst CI

ÿÿNIÿÿÿ	tÿÿt
	
IIsdf-2.001/perllib/sdf/home/images/mail1.gif010064400042570001753000000020420613456427600202250ustar00iancmtr00000400000236GIF89a"÷€€€€€€€€€ÀÀÀÀÜÀ¤ÈðUªÕ+U+€+ª+Õ+ÿ+UUU€UªUÕUÿUU€ª€Õ€ÿ€ªUª€ªªªÕªÿªÕUÕ€ÕªÕÕÕÿÕUÿ€ÿªÿÕÿUUU€UªUÕUÿU+UU+U€+Uª+UÕ+Uÿ+UUUUUU€UUªUUÕUUÿUU€UU€U€€Uª€UÕ€Uÿ€UªUUªU€ªUªªUÕªUÿªUÕUUÕU€ÕUªÕUÕÕUÿÕUÿUUÿU€ÿUªÿUÕÿUÿÿUU€ª€Õ€ÿ€+€U+€€+€ª+€Õ+€ÿ+€U€UU€€U€ªU€ÕU€ÿU€U€€ª€€Õ€€ÿ€€ª€Uª€€ª€ªª€Õª€ÿª€Õ€UÕ€€Õ€ªÕ€ÕÕ€ÿÕ€ÿ€Uÿ€€ÿ€ªÿ€Õÿ€ÿÿ€ªUª€ªªªÕªÿª+ªU+ª€+ªª+ªÕ+ªÿ+ªUªUUª€UªªUªÕUªÿUª€ªU€ª€€ªª€ªÕ€ªÿ€ªªªUªª€ªªªªªÕªªÿªªÕªUÕª€ÕªªÕªÕÕªÿ€ ÿªUÿª€ÿªªÿªÕÿªÿÿªÕUÕ€ÕªÕÕÕÿÕ+ÕU+Õ€+Õª+ÕÕ+Õÿ+ÕUÕUUÕ€UÕªUÕÕUÕÿUÕ€ÕU€Õ€€Õª€ÕÕ€Õÿ€ÕªÕUªÕ€ªÕªªÕÕªÕÿªÕÕÕUÕÕ€ÕÕªÕÕÕÕÕÿÕÕÿÕUÿÕ€ÿÕªÿÕÕÿÕÿÿÕUÿ€ÿªÿÕÿ+ÿU+ÿ€+ÿª+ÿÕ+ÿÿ+ÿUÿUUÿ€UÿªUÿÕUÿÿUÿ€ÿU€ÿ€€ÿª€ÿÕ€ÿÿ€ÿªÿUªÿ€ªÿªªÿÕªÿÿªÿÕÿUÕÿ€ÕÿªÕÿÕÕÿÿÕÿUÿÿ€ÿÿªÿÿÿûð  ¤€€€ÿÿÿÿÿÿÿÿÿÿÿÿ,"þH° Áƒ(Tˆ°aA†ñáƒè0!¾%R¬8Æ5à(Ðã¿“ 1Fœ8²¢I”(¨\¹ñáG˜1AÒlùP¦Oœ9C²´ùó'΢'ä)0%PŒðª´dɨ¢ÄJõÏ–ò)”ZäH©c½ZõšOlÚ¦>ÏzÕXlÛ…o?rm9T-[±SñJ…:5ð¿¾`Ãòd™–«×Ã!öˆ¸0Ú¨Lkf,Ùµ+Ó«.-[þÜ‘tÇÎ…M_5-׳j¯Ôt<!€Ø²)ÊÕœ÷X†˜_¼3cὋ'™\öĪ̗ú^]zñçÈÏ]»ºÀ똽'Ä*¾|Á€;sdf-2.001/perllib/sdf/home/images/back.bmp010064400042570001753000000017260613464276400201420ustar00iancmtr00000400000236BMÖv(=`ÿÿÿÀÀÀ}}}&&& """"""""""""""""""""""""""""" """"""""""""""""""""""""""""              331113131  1313333  133331133  1333131  3311133  1331133  13311131  1333333  33133131                  """""""""""""""""""""""""""""" sdf-2.001/perllib/sdf/home/images/next.gif010064400042570001753000000004270613456427400202030ustar00iancmtr00000400000236GIF89a=³ÿÿÿÀÀÀ}}}&&&,=ÌPÈI«½8ëºÿ`(Žd	
fª®¤Ôp,Ïtmßx0½yïÿ³H,Ú„Æd©4òϳIôÀ¬G×ZÄbiSØ`Æh²Y¬N“iÞh,|^›×²û›‹oeth|xyg3„5~AZ‡‚z5‚y{7ŠsŒ’†zi…=•0m4‘e“‰<_ —¦lm¤¯­”©r:¬|u±˜„ˆ2Ÿ€·u­nºx½W´‹(Ê\žÉ7tÎ}µÀÌÓÙËÖÚTÒÝÞÁàáÌæçèéìí;sdf-2.001/perllib/sdf/home/images/bk_diam.gif010064400042570001753000000016520604426732600206120ustar00iancmtr00000400000236GIF89a÷üü ü4üDüTÀÀÀ   ‚‚‚dddFFFüÈüÜüìüüøøèøØøÈø´ø¤ø”ø„øtüdüTüDü0ü üüüøèØ È4´D¤T”d„ttˆd˜T¨D¸0È Üìüøðèà$Ø,Ð4È<ÀD¸L°T¨\ h˜pxˆ€€@@@===;;;999777555333111///---+++)))'''%%%###!!!


„xˆŒp”h˜œ` ¤X¨¬P°´H¸¼@ÀÄ8ÄÌ0ÌÔ(ÔÜ Üääììü8ŒüP`ü\Hü`@üd8üh0ül(üp ütüxü|ø|ôxðtìpèlähàdÜ`Ø\ÔXÐTÌPÈLÄHÀD¼<¸8´4°0¬,¨(¤$  œ˜”Œˆ„€`XTLHd p,x0|8„<ˆDŒL”P˜X \¤d¬h°p¸t¼|À„ȈÌԔ؜à ä¨ì¬ð´ø¸üÀììôôüüääÔÔ(ÌÌ0ÄÄ8¼¼@´´H¬¬Pœœ`””hŒŒp„„xppŒhh”``œXX¤PP¬HH´@@¼88Ä00Ì((Ô  Üäììôôüüä Ü(Ô0Ì8Ä@ ¼H$´P(¬X,¤`0œh4”p8Œx<„„DxŒHp”LhœP`¤TX¬XP´\H¼`@Äd8Ìh0Ôl(Üp ätìxô|ü€ü€ü€üXPüDxüHpüTXÜÜ l$ÿÿÿ!ù,‡H° Aƒ_\ø,_lؤ	ˆ6„ÒäÈ‘$bIâqˆÇ‹:,	ÄdÅ)²Òò$/1±pîîîîîîîîîîîààîîîîîîîîîîîîîîîîîîîîîîîîîîãîîîîîîîîîîîàîîîîîîîîîîîîîàîîîîîîîîîîîà°îîîîîîîîîîî»îîîîîîîîîîîîîîîîîîîîîîîî]îîîîîîîîà¾îîîîîîîîîÞî~îîîîîîîîîâîîîîîîîîîàîîîîîîîîîàãîîîîîî¾î]àîîîîîî.îîàîîîîîîîàãîîîîîîâîàîÞîîîîîîîîîî.àîàîîîîîîîîîë^îîîîîîâ¾Wî^îîîîîîàîîîîîîîîîPà ã]îîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîîpîîîîîîîîîîîîîîîîîîîîîîîîîîîîîæîîîîîîîîîîîîîîîƒÎîîîîîîîîîîîîîîä¾îîîîîîîîîîîîîîãÎîîîîîDDNäDDNìFÎîîîîîîLîLäLæLîDÎîîîîîîîìLäLîDÎDîîîîîîîìdLäLîä¼DÌîîîîîîÄD¾ÄLîäÎDDÎîîîîîDÌîäLîäÎDÎîîîîîîLîÎäLìDÎDîîîîîîæLäLäNäLîDÎNîîîîîDDNäDDîîDDNîîîîîîîîîîîîîîîîîîîîsdf-2.001/perllib/sdf/home/images/bar1.bmp010064400042570001753000000114660613464276600200730ustar00iancmtr00000400000236BM66(€U€ªÕÿ++U+€+ª+Õ+ÿUUUU€UªUÕUÿ€€U€€€ª€Õ€ÿªªUª€ªªªÕªÿÕÕUÕ€ÕªÕÕÕÿÿÿUÿ€ÿªÿÕÿÿUUUU€UªUÕUÿU+U+UU+€U+ªU+ÕU+ÿUUUUUUU€UUªUUÕUUÿU€U€UU€€U€ªU€ÕU€ÿUªUªUUª€UªªUªÕUªÿUÕUÕUUÕ€UÕªUÕÕUÕÿUÿUÿUUÿ€UÿªUÿÕUÿÿ€€U€€€ª€Õ€ÿ€+€+U€+€€+ª€+Õ€+ÿ€U€UU€U€€Uª€UÕ€Uÿ€€€€U€€€€€ª€€Õ€€ÿ€ª€ªU€ª€€ªª€ªÕ€ªÿ€Õ€ÕU€Õ€€Õª€ÕÕ€Õÿ€ÿ€ÿU€ÿ€€ÿª€ÿÕ€ÿÿªªUª€ªªªÕªÿª+ª+Uª+€ª+ªª+Õª+ÿªUªUUªU€ªUªªUÕªUÿª€ª€Uª€€ª€ªª€Õª€ÿªªªªUªª€ªªªªªÕªªÿªÕªÕUªÕ€ªÕªªÕÕªÕÿªÿªÿUªÿ€ªÿªªÿÕªÿÿÕÕUÕ€ÕªÕÕÕÿÕ+Õ+UÕ+€Õ+ªÕ+ÕÕ+ÿÕUÕUUÕU€ÕUªÕUÕÕUÿÕ€Õ€UÕ€€Õ€ªÕ€ÕÕ€ÿÕªÕªUÕª€ÕªªÕªÕÕªÿÕÕÕÕUÕÕ€ÕÕªÕÕÕÕÕÿÕÿÕÿUÕÿ€ÕÿªÕÿÕÕÿÿÿÿUÿ€ÿªÿÕÿÿÿ+ÿ+Uÿ+€ÿ+ªÿ+Õÿ+ÿÿUÿUUÿU€ÿUªÿUÕÿUÿÿ€ÿ€Uÿ€€ÿ€ªÿ€Õÿ€ÿÿªÿªUÿª€ÿªªÿªÕÿªÿÿÕÿÕUÿÕ€ÿÕªÿÕÕÿÕÿÿÿÿÿUÿÿ€ÿÿªÿÿÕ???kkk•••ÃÃÃÿÿÿTTTTTTTTTTTTTTTTTZTTTZTTTZZZZ~ZZZ~ZZZ~ZZZ~ZZZ~ZZ„Z„Z„Z„Z„Z„Z„Z„„„Z„Z„„`„„„`„„„„Š„Š„Š„Š„ŠŠŠ„ŠŠŠ„ŠŠŠ„ŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠ´´´ºººººººººº–ººº–ººº–ººº–ººº–ºÀÀºÀÀÀºÀÀÀºÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÆÀÀÀÆÀÀÀÆÀÆÆÆêÆÆÆêÆÆÆðÆÆÆðÆÆÆðÆÆÆðÆÆÆðÆÆÆðÆðÆðððÆðÆðÌðððÌðððÌðöööÆöööÆöööööööðöööööööööööööööööðöööööööÆöööÆöööðÌðððÌðððÌðÆðÆðððÆðÆðÆÆÆðÆÆÆðÆÆÆðÆÆÆðÆÆÆðÆÆÆêÆÆÆêÆÆÆÀÆÀÀÀÆÀÀÀÆÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀºÀÀÀºÀÀÀºÀÀº–ººº–ººº–ººº–ººº–ºººººººººº´´´ŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠ„ŠŠŠ„ŠŠŠ„ŠŠŠ„Š„Š„Š„Š„„„„`„„„`„„Z„Z„„„Z„Z„Z„Z„Z„Z„Z„ZZ~ZZZ~ZZZ~ZZZ~ZZZ~ZZZZTTTZTTTZTTTTTTTTTTTTTTTTTTTTTTTTTZTZTZTTTZTZTZTZTZT~Z~Z~Z~Z~Z~Z~Z~Z~Z~Z~„Z„Z„Z„Z„Z„Z„Z„Z„Z„Z„„`„`„`„`„`Š„Š„Š„Š„Š„Š„Š„Š„Š„Š„ŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠ´´´´´ºººººººººººº–º–º–º–º–º–º–º–º–º–ÀºÀºÀºÀºÀºÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆêÆêÆêÆêÆêÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÌðÌðÌðÌðÌðÌÆöÆöÆöÆöÆöðöðöðöðöðöööööööööööðöðöðöðöðöÆöÆöÆöÆöÆÌðÌðÌðÌðÌðÌðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆêÆêÆêÆêÆêÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀºÀºÀºÀºÀºÀ–º–º–º–º–º–º–º–º–º–ºººººººººººº´´´´´ŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠ„Š„Š„Š„Š„Š„Š„Š„Š„Š„Š`„`„`„`„`„„Z„Z„Z„Z„Z„Z„Z„Z„Z„Z„~Z~Z~Z~Z~Z~Z~Z~Z~Z~Z~TZTZTZTZTZTTTZTZTZTTTTTTTTTTTTTTTTTTTTTTTTTTTZTTTZTZZ~ZZZ~Z~Z~ZZZZZZZZZZZZ„Z„Z„Z„Z„Z„Z„Z„Z„Z„Z„„„„„„„„„„„Š„Š„Š„Š„ŠŠŠŠŠ„ŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠ´ºººººººººººººººººººººº–º–º–ºººÀÀÀÀºÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÆÀÆÀÀÀÆÀÆÀÆêÆÆÆÆÆÆÆêÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðððððððÌðððöÆöööÆöÆöÆöööööööööööööööööööööööööööööÆöÆöÆöööÆöðððÌðððððððÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆêÆÆÆÆÆÆÆêÆÀÆÀÆÀÀÀÆÀÆÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀºÀÀÀÀººº–º–º–ºººººººººººººººººººººº´ŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠ„ŠŠŠŠŠ„Š„Š„Š„Š„„„„„„„„„„„Z„Z„Z„Z„Z„Z„Z„Z„Z„Z„ZZZZZZZZZZZZ~Z~Z~ZZZ~ZZTZTTTZTTTTTTTTTTTTTTTTTTTTTTTTTZTZTZTZTZTZTZTZTZTZT~Z~Z~Z~Z~Z~Z~Z~Z~Z~Z~„Z„Z„Z„Z„Z„Z„Z„Z„Z„Z„„`„`„`„`„`Š„Š„Š„Š„Š„Š„Š„Š„Š„Š„ŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠ´´´´´ºººººººººººº–º–º–º–º–º–º–º–º–º–ÀºÀºÀºÀºÀºÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆêÆêÆêÆêÆêÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÌðÌðÌðÌðÌðÌÆöÆöÆöÆöÆöðöðöðöðöðöööööööööööðöðöðöðöðöÆöÆöÆöÆöÆÌðÌðÌðÌðÌðÌðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆêÆêÆêÆêÆêÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀºÀºÀºÀºÀºÀ–º–º–º–º–º–º–º–º–º–ºººººººººººº´´´´´ŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠ„Š„Š„Š„Š„Š„Š„Š„Š„Š„Š`„`„`„`„`„„Z„Z„Z„Z„Z„Z„Z„Z„Z„Z„~Z~Z~Z~Z~Z~Z~Z~Z~Z~Z~TZTZTZTZTZTZTZTZTZTZTTTTTTTTTTTTTTTTTTTTTTTZTTTZTTTZZZZ~ZZZ~ZZZZZZZ~ZZZZZZZZ„Z„Z„ZZZ„„„Z„„„Z„„„„`„„„`„„„„Š„Š„Š„Š„ŠŠŠ„ŠŠŠ„ŠŠŠ„ŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠ´´´ººººººººººº–ººº–ººº–ººº–ººº–ºÀÀºÀÀÀºÀÀÀºÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÆÀÀÀÆÀÀÀÆÀÆÆÆêÆÆÆêÆÆÆðÆÆÆðÆÆÆðÆÆÆðÆðÆðÆÆÆðððÆðÆðÆðððÌðððÌðððÌðöööÆöööÆöööðöööööööðöööööööööðöööööööðöööÆöööÆöööðÌðððÌðððÌðððÆðÆðÆðððÆÆÆðÆðÆðÆÆÆðÆÆÆðÆÆÆðÆÆÆêÆÆÆêÆÆÆÀÆÀÀÀÆÀÀÀÆÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀºÀÀÀºÀÀÀºÀÀº–ººº–ººº–ººº–ººº–ººººººººººº´´´ŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠ„ŠŠŠ„ŠŠŠ„ŠŠŠ„Š„Š„Š„Š„„„„`„„„`„„„„Z„„„Z„„„ZZZ„Z„Z„ZZZZZZZZ~ZZZZZZZ~ZZZ~ZZZZTTTZTTTZTTTTTTTTTTTTTTTTTTTTTTTTTZTTTZTTTZTZTZTZTZT~Z~Z~Z~Z~Z~Z~Z~Z~Z~Z~„Z„Z„Z„Z„Z„Z„Z„Z„Z„Z„„`„`„`„`„`Š„Š„Š„Š„Š„Š„Š„Š„Š„Š„ŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠ´´´´´ºººººººººººº–º–º–º–º–º–º–º–º–º–ÀºÀºÀºÀºÀºÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆêÆêÆêÆêÆêÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÌðÌðÌðÌðÌðÌÆöÆöÆöÆöÆöðöðöðöðöðöööööööööööðöðöðöðöðöÆöÆöÆöÆöÆÌðÌðÌðÌðÌðÌðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆðÆêÆêÆêÆêÆêÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÆÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀÀºÀºÀºÀºÀºÀ–º–º–º–º–º–º–º–º–º–ºººººººººººº´´´´´ŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠŠ„Š„Š„Š„Š„Š„Š„Š„Š„Š„Š`„`„`„`„`„„Z„Z„Z„Z„Z„Z„Z„Z„Z„Z„~Z~Z~Z~Z~Z~Z~Z~Z~Z~Z~TZTZTZTZTZTTTZTTTZTTTTTTTTsdf-2.001/perllib/sdf/home/images/m0omo7eu.bmp010064400042570001753000000073360613464277400207160ustar00iancmtr00000400000236BMÞ6(X¨
ÿÿÿ÷÷÷ÆÆƽ½½œœœ111)))ss„ÖÖÿ)RRJ{s­¥R¥œ9cZŒ{)kZR99!ÎÆνµÖ„s÷µ­ÿsc÷Œ„ç9)÷”ŒÿZRïB9÷÷			

		

















		
sdf-2.001/perllib/sdf/home/images/exit1.bmp010064400042570001753000000055560613464277000202760ustar00iancmtr00000400000236BMn6(+*8€€€€€€€€€ÀÀÀÀÜÀðʦ³¬È§ ºŒˆ³§šBˆ~/g_<73f™Ì333f3™3Ì3ÿ3f3fff™fÌfÿf™3™f™™™Ì™ÿ™Ì3ÌfÌ™ÌÌÌÿÌ3ÿfÿ™ÿÌÿ333f3™3Ì3ÿ333333f33™33Ì33ÿ33f33f3ff3™f3Ìf3ÿf3™33™3f™3™™3Ì™3ÿ™3Ì33Ì3fÌ3™Ì3ÌÌ3ÿÌ3ÿ33ÿ3fÿ3™ÿ3Ìÿ3ÿÿ3f3fff™fÌfÿf3f33ff3f™3fÌ3fÿ3fff3fffff™ffÌffÿff™f3™ff™f™™fÌ™fÿ™fÌf3ÌffÌf™ÌfÌÌfÿÌfÿf3ÿffÿf™ÿfÌÿfÿÿf™3™f™™™Ì™ÿ™3™33™f3™™3™Ì3™ÿ3™f™3f™ff™™f™Ìf™ÿf™™™3™™f™™™™™Ì™™ÿ™™Ì™3Ì™fÌ™™Ì™ÌÌ™ÿÌ™ÿ™3ÿ™fÿ™™ÿ™Ìÿ™ÿÿ™Ì3ÌfÌ™ÌÌÌÿÌ3Ì33Ìf3Ì™3ÌÌ3Ìÿ3ÌfÌ3fÌffÌ™fÌÌfÌÿfÌ™Ì3™Ìf™Ì™™ÌÌ™Ìÿ™ÌÌÌ3ÌÌfÌÌ™ÌÌÌÌÌÿÌÌÿÌ3ÿÌfÿÌ™ÿÌÌÿÌÿÿÌ3ÿfÿ™ÿÌÿ3ÿ33ÿf3ÿ™3ÿÌ3ÿÿ3ÿfÿ3fÿffÿ™fÿÌfÿÿfÿ™ÿ3™ÿf™ÿ™™ÿÌ™ÿÿ™ÿÌÿ3ÌÿfÌÿ™ÌÿÌÌÿÿÌÿ3ÿÿfÿÿ™ÿÿÌÿÿ
 
( &5&

"
)
!
8#	ðûÿ¤  €€€ÿÿÿÿÿÿÿÿÿÿÿÿ³”¹¹¸³”¹”¸Ž¹Ž¹¹¹²¹•³cŽci³‡d¹¸¹¹c‡•Ž”cŽ¹³cŽ”¹cdþþ•¹‡c¹³¸ˆc¹ŽŽc”³Žc¹cþþ$ŽŽ¹¹ici¹¹cŽ¹ŽcŽ¸•³ccþþ$Ž‡•³¹³icŽcc¹•ˆc”c‡þþ$$ŽŽ”³cŽ¹²j‡¹cŽ³”þþ$$Ž”³”Žcþþ$$$ŽŽŽ¹cþþ$$ŽccŽ¹þþ$$$cˆcþþ$$ŽcŽccŽŽcŽcþþ$$$cŽŽŽccŽcŽþþ$$Žc$ccŽcŽcþþ$$$cd$ŽcŽŽcŽþþ$ŽcccdŽcþ$ŽccŽcþþŽ$cŽdŽcŽŽþþ$ŽŽcŽþþÿ$Žcþþþ$cŽcþþ$$Žc$$$$þþþþ$ŽŽþþ$$Žþþþþþþþþþþþþþ$cþþ$$$cdþþÿÿÿÿÿÿÿÿÿÿþþŽþþ$$Ž‡þþþþþþþþþþÿþþ$cŽþþ$$$ŽcþÿþþŽŽcþþ$$ŽŽþþþ$cŽcŽþþ$$$ccþþŽcŽccþþ$$Ž‡þ$cŽcŽcŽþþ$$$Žc$ŽcŽcŽcŽþþ$$cŽcŽcŽcŽcŽþþ$$ŽcŽcŽcŽcŽcŽþþŽicŽcŽcŽcŽcŽþþ$ŽcŽcŽcŽcŽcŽcŽþþˆsdf-2.001/perllib/sdf/home/images/mail2.gif010064400042570001753000000002270613456427600202310ustar00iancmtr00000400000236GIF89a³`f~úë×ÿÿÿÿ,LPÈI«¥#ëÍûÔA(Ž¤HC˜’l°§°º3›‰0Z¶µ÷40'ÛÑ^¥ßˆ[*U­%îÉ´©”Už•f~p8&˜Ïè´úÂn";sdf-2.001/perllib/sdf/home/images/images.sdm010064400042570001753000000010360613407514200204740ustar00iancmtr00000400000236# $Id$
#
# >>Title::     Images Module
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{MOD:images}} provides images commonly referenced in [[SDF]]
# documents.
#
# >>Description::
#
# >>Limitations::
#
sdf-2.001/perllib/sdf/home/images/folders.bmp010064400042570001753000000107020613014635000206540ustar00iancmtr00000400000236BMÂ6(A3Œ
€€€€€€€€€ÀÀÀÀÜÀðʦ³¬È§ ºŒˆ³§šBˆ~/g_<73f™Ì333f3™3Ì3ÿ3f3fff™fÌfÿf™3™f™™™Ì™ÿ™Ì3ÌfÌ™ÌÌÌÿÌ3ÿfÿ™ÿÌÿ333f3™3Ì3ÿ333333f33™33Ì33ÿ33f33f3ff3™f3Ìf3ÿf3™33™3f™3™™3Ì™3ÿ™3Ì33Ì3fÌ3™Ì3ÌÌ3ÿÌ3ÿ33ÿ3fÿ3™ÿ3Ìÿ3ÿÿ3f3fff™fÌfÿf3f33ff3f™3fÌ3fÿ3fff3fffff™ffÌffÿff™f3™ff™f™™fÌ™fÿ™fÌf3ÌffÌf™ÌfÌÌfÿÌfÿf3ÿffÿf™ÿfÌÿfÿÿf™3™f™™™Ì™ÿ™3™33™f3™™3™Ì3™ÿ3™f™3f™ff™™f™Ìf™ÿf™™™3™™f™™™™™Ì™™ÿ™™Ì™3Ì™fÌ™™Ì™ÌÌ™ÿÌ™ÿ™3ÿ™fÿ™™ÿ™Ìÿ™ÿÿ™Ì3ÌfÌ™ÌÌÌÿÌ3Ì33Ìf3Ì™3ÌÌ3Ìÿ3ÌfÌ3fÌffÌ™fÌÌfÌÿfÌ™Ì3™Ìf™Ì™™ÌÌ™Ìÿ™ÌÌÌ3ÌÌfÌÌ™ÌÌÌÌÌÿÌÌÿÌ3ÿÌfÿÌ™ÿÌÌÿÌÿÿÌ3ÿfÿ™ÿÌÿ3ÿ33ÿf3ÿ™3ÿÌ3ÿÿ3ÿfÿ3fÿffÿ™fÿÌfÿÿfÿ™ÿ3™ÿf™ÿ™™ÿÌ™ÿÿ™ÿÌÿ3ÌÿfÌÿ™ÌÿÌÌÿÿÌÿ3ÿÿfÿÿ™ÿÿÌÿÿðûÿ¤  €€€ÿÿÿÿÿÿÿÿÿÿÿÿöööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøøÿÿÿÿÿöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿøÿÿÿÿöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿøÿÿÿÿöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿøÿÿÿöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿûûûûûûûÿÿÿøÿÿÿöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿûÿÿÿøÿûûûÿÿøÿÿöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿûÿÿÿÿøÿÿÿÿûûÿÿøÿÿöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿûÿÿÿÿÿÿÿÿÿÿÿÿÿûÿÿøÿöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿûÿÿÿÿÿÿøøÿÿÿÿÿûÿÿøÿöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿûÿÿÿÿÿÿøøÿÿÿÿûÿøöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿûÿÿÿÿÿÿÿøøÿÿÿÿûÿÿøöööÿÿÿÿÿÿÿÿÿÿÿÿûÿÿÿÿøÿÿÿøøÿÿÿÿûÿÿøöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿûÿÿÿÿøÿÿÿÿûÿÿÿøÿöööøøøøøøøøøøøøøøøøøøÿÿÿÿÿÿÿûûÿÿøøÿÿÿûÿÿøÿöööÿÿÿÿÿÿÿÿÿÿûûÿÿÿÿÿÿÿÿÿøöööÿÿÿÿÿÿÿÿûûûûÿÿÿÿÿûûÿÿÿÿøöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿûûûûûÿÿÿÿÿøöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿöööÿÿÿÿÿÿÿÿÿÿøøÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿøÿÿöööÿÿÿÿÿÿÿÿÿøøÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿøÿÿÿöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿøÿÿÿÿÿÿÿöööÿÿÿÿÿÿÿÿÿÿøøÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿøÿÿÿÿÿÿÿöööÿÿÿÿÿÿÿÿÿÿÿÿøøÿÿÿÿÿÿÿÿøÿÿÿÿÿÿÿöööÿÿÿÿÿÿÿÿÿÿÿøøÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿøÿÿÿÿÿÿÿöööÿÿÿÿÿûÿÿÿÿÿÿÿÿøøÿÿÿÿûÿÿøÿÿÿÿÿÿÿÿÿÿøÿÿÿÿÿÿÿöööÿÿÿÿÿÿÿÿÿÿÿÿÿøøÿÿÿÿÿÿÿÿøÿÿÿÿÿÿøÿÿÿÿÿÿÿöööÿÿÿÿÿûÿÿÿÿÿøÿÿÿøøÿÿÿÿÿÿÿÿøÿÿÿÿÿÿÿÿÿÿøÿÿÿÿÿÿÿöööÿÿÿÿûÿÿÿÿÿøøÿÿÿÿÿÿÿøÿÿÿÿÿÿÿÿøÿÿÿÿÿÿÿÿöööÿÿÿÿÿÿûÿÿÿÿøøÿÿÿÿÿÿÿøÿøÿÿÿÿÿÿÿÿÿöööÿÿÿÿÿûÿÿÿÿÿÿÿÿÿÿÿÿøÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿöööÿÿÿÿÿÿûÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿøÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿöööÿÿÿÿÿÿûûÿÿÿÿÿÿÿÿÿÿÿÿÿÿøÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿöööÿÿÿÿÿÿÿûûÿÿÿÿÿÿÿÿÿÿøÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿöööÿÿÿÿÿÿÿÿûûûÿÿÿÿÿÿÿøÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿøøÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿöööÿÿøøøøøøøøøøøøÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿøÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿøÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿøÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿøÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿøÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿöööÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿøÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööööösdf-2.001/perllib/sdf/home/images/hot_dot.bmp010064400042570001753000000037660613464277200207070ustar00iancmtr00000400000236BMö6(À€€€€€€€€€ÀÀÀÀÜÀðʦ³¬È§ ºŒˆ³§šBˆ~/g_<73f™Ì333f3™3Ì3ÿ3f3fff™fÌfÿf™3™f™™™Ì™ÿ™Ì3ÌfÌ™ÌÌÌÿÌ3ÿfÿ™ÿÌÿ333f3™3Ì3ÿ333333f33™33Ì33ÿ33f33f3ff3™f3Ìf3ÿf3™33™3f™3™™3Ì™3ÿ™3Ì33Ì3fÌ3™Ì3ÌÌ3ÿÌ3ÿ33ÿ3fÿ3™ÿ3Ìÿ3ÿÿ3f3fff™fÌfÿf3f33ff3f™3fÌ3fÿ3fff3fffff™ffÌffÿff™f3™ff™f™™fÌ™fÿ™fÌf3ÌffÌf™ÌfÌÌfÿÌfÿf3ÿffÿf™ÿfÌÿfÿÿf™3™f™™™Ì™ÿ™3™33™f3™™3™Ì3™ÿ3™f™3f™ff™™f™Ìf™ÿf™™™3™™f™™™™™Ì™™ÿ™™Ì™3Ì™fÌ™™Ì™ÌÌ™ÿÌ™ÿ™3ÿ™fÿ™™ÿ™Ìÿ™ÿÿ™Ì3ÌfÌ™ÌÌÌÿÌ3Ì33Ìf3Ì™3ÌÌ3Ìÿ3ÌfÌ3fÌffÌ™fÌÌfÌÿfÌ™Ì3™Ìf™Ì™™ÌÌ™Ìÿ™ÌÌÌ3ÌÌfÌÌ™ÌÌÌÌÌÿÌÌÿÌ3ÿÌfÿÌ™ÿÌÌÿÌÿÿÌ3ÿfÿ™ÿÌÿ3ÿ33ÿf3ÿ™3ÿÌ3ÿÿ3ÿfÿ3fÿffÿ™fÿÌfÿÿfÿ™ÿ3™ÿf™ÿ™™ÿÌ™ÿÿ™ÿÌÿ3ÌÿfÌÿ™ÌÿÌÌÿÿÌÿ3ÿÿfÿÿ™ÿÿÌÿÿ			


ÅÔÿÈÖÿÌÜÿÐÞÿÀÿÿÆÿÿÉÿÿÍÿÿÕãÿØåÿÜêÿÐÿÿÖÿÿðûÿ¤  €€€ÿÿÿÿÿÿÿÿÿÿÿÿj‡8\8‡ic88cc1‡11118‡11UUy[UUUU1‡171U[…©…©…y[yUU11177a……©°°Œ°°©¤©©…[baaaa8b©¯Œ88†¯¤†babaa77‹b׌77°°Ò8a……[7¶†Ø>bb8ÒØ8>©€abaŒŒû1Œ¶8ÙÒ>1¯ˆca7a‹ŒØŒ°¶Ø8¯€b‹2‹‹Œ¼1Œ’ÓÒb7°©[b7‹…°×°Œ2¶Ø†Ò£€7Œ7Œ¶7Œ°1·Øb¶©y7Œ1°¼1Œ¶¶Øb7°Ì7‹°¶ŒŒ1¶Ùb1¶ª£[Œ8bbŒ×Œ°8·Øb°Ì†7‹1aµŒ¶7ŒŒ1·Ýb1د«c…=[‹ŒØ8°’8·Ø8Œªa†8µ†Ý7c†>·8°†…8°b݌ط…Œ†¯>8bØØŒ7‡Ý·788b†°Ú‡U©©°°·ÓÙرŒ†hŒ·ÞÙÙÙ¶ØØÒ·†U¤ªÒÌÍÍÔÙÙÙÙÙÚÔÔÔÓÓÓª±€y¤¥Æ«ÍÍÔÓÔÓÔÓÔÓÔÓÍLJ¤«ÍÍ«ÍÔÔÔÔÔÔÔÔÍ«€¤¤¤ÍÍÍÍÓÎÓÔÓÍͱ«¤ª¥ªÍÍÍÍÍÍÍ««««««sdf-2.001/perllib/sdf/home/images/exclam.gif010064400042570001753000000020350613502630200204550ustar00iancmtr00000400000236GIF89a&÷€€€€€€€€€ÀÀÀÀÜÀ¦Êðÿûð  ¤€€€ÿÿÿÿÿÿÿÿÿÿÿÿ,&þí	H° Áƒþ;À°¡Ã‡#Bü'ðÀ‹3büÇQ£ÇTì䀓S.<€o¤Jÿì›9à%È–ö,–„y@&M†;1²tt¡Ï™ûjÚ̈S§MŸø¢þ\:4gÐŒþí‹Šo_̆W›’LéóW­IÁ¦¬º4«×­Rµ~šRlI£oÍF•›ö%Û»=óîëy@°Òv?f•ËÑkcŽZ{üK–¯V–…-+­;Ò$äÏg?sÜ,T,ÌÅ¢âÓ™š4ÓÎQ§ž
YòJÓBOêÞÍ›·CŒ‰…Jþ;dSâÈ“³UÎ<"N®Ð£KŸN«ÀêسK·G»»÷ïàÇ;sdf-2.001/perllib/sdf/home/images/greenbal.gif010064400042570001753000000016320604426733400210000ustar00iancmtr00000400000236GIF89a÷ÿ0ÿ4ÿÿ"ï$çÀÀÀÖ'ÖcÎuÎ)ÎÞ{Ƈƽ½µ­œ”1Œ?„„sskcZ	Z
J	JªÕÕÕÿÕÿUÿ€ÿªÿÕÿÿÿUUU€UªUÕUÿU+UU+U€+Uª+UÕ+Uÿ+UUUUUU€UUªUUÕUUÿUU€UU€U€€Uª€UÕ€Uÿ€UªUJœU€ªUªªUÕªUÿªUÕUBÎU€ÕUªÕUÕÕUÿÕU!ÿ?UÿU€ÿUªÿUÕÿUÿÿU€U€€€ª€Õ€ÿ€+€U+€€+€ª+€Õ+€ÿ+€U€UU€€U€ªU€ÕU€ÿU€€€U€€€€€ª€€Õ€€ÿ€€ª€Uª€€ª€ªª€Õª€ÿª€Õ€cÎq{Æ„ªÕ€ÕÕ€ÿÕ€ÿ€Uÿ€€ÿ€ªÿ€Õÿ€ÿÿ€ªUª€ªªªÕªÿª+ªU+ª€+ªª+ªÕ+ªÿ+ªUªUUª€UªªUªÕUªÿUª€ªU€ª€€ªª€ªÕ€ªÿ€ªªªUªª€ªªªªªÕªªÿªªÕªUÕª€ÕªªÕªÕÕªÿÕªÿªUÿª€ÿªªÿªÕÿªÿÿªÕUÕ€ÕªÕÕÕÿÕ+ÕU+Õ€+Õª+ÕÕ+Õÿ+ÕUÕUUÕ€UÕªUÕÕUÕÿUÕ€ÕU€Õ€€Õª€ÕÕ€Õÿ€ÕªÕUªÕ€ªÕªªÕÕªÕÿªÕÕÕUÕÕ€ÕÕªÕÕÕÕÕÿÕÕÿÕUÿÕ€ÿÕªÿÕÕÿÕÿÿÕÿUÿ€ÿªÿÕÿÿÿ+ÿU+ÿ€+ÿª+ÿÕ+ÿÿ+ÿUÿUUÿ€UÿªUÿÕUÿÿUÿ€ÿU€ÿ€€ÿª€ÿÕ€ÿÿ€ÿªÿUªÿ€ªÿªªÿÕªÿÿªÿÕÿUÕÿ€ÕÿªÕÿÕÕÿÿÕÿÿÿUÿÿ€ÿÿªÿÿÕÿÿ???kkk•••¿¿¿ÿÿÿ!ù,wH° Áƒ$Y° ‰ƒƒ
@ Àé0àß?(Ð!˜d€Ç@¨pà €@ƒ—
4` ¡&‡›“@€aBÍ2¤SB8€ø0¤àœ
<|Øjá (

(ÿÿÿÿÿÀÿÀÿÀÿÀÿÀÿÀÿÀÿÀÿÀsdf-2.001/perllib/sdf/home/images/camera1.bmp010064400042570001753000000015320613464277000205430ustar00iancmtr00000400000236BMZv(%%äÿÿÿšèÿ}}}""""""""""""""""""""""""""""""""""" 331 031 3331 333331 03333331 030331 030331 33330331 333333332 03033032 00333330 30303333 30330333330 3330333330 303333333330 30333333300 30303333300 3003333303 333333333 30033330 30330 333333 33333330 33033 333333 333303 3333033 3333332 33133302 33333 33333 332 32   sdf-2.001/perllib/sdf/home/images/ftp1.bmp010064400042570001753000000005460613464277200201120ustar00iancmtr00000400000236BMfv(ð€€€€€€€€€€€€ÀÀÀÿÿÿÿÿÿÿÿÿÿÿÿ™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™›»¹™™»»™»»™™™™™»™™™›¹™›¹™™™™™»™™™›¹™›¹™™™™™»›™™›¹™›¹™™™™™»»™™›¹™›»»™™™™»›™™›¹™›¹›¹™™™»™™™›¹™›¹›¹™™™»™›¹›¹››¹›¹™™›»»»»»»»»»»™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™™sdf-2.001/perllib/sdf/home/images/mailto.gif010064400042570001753000000004140613462772400205060ustar00iancmtr00000400000236GIF89a 　€€€€€€€€€€ÀÀÀÿÿÿÿÿÿÿÿÿÿÿÿ!ù, @¹ÐI«½xÊu‘O(Ž$5Nª®êq€‹ÀÁÜ‚,ï÷ÀŸp0xX+Œc„œ'"!³!¯I«»Éx¿€Wxdç4ó–…(oHF‚BcT
7¥1Ÿ$5{X}5 ƒH BAŒˆ;Ž•Da‚;n`E'bœffi¨mg¢›D¯'s3uaGW}1³Q€		‚„¹¼Æ4V„ÄM#‰ÊY0t!ÏÐHJ./ÉÖÜX;sdf-2.001/perllib/sdf/home/images/sdflogo.gif010064400042570001753000000025360632066200600206520ustar00iancmtr00000400000236GIF89a(=÷3f™Ìÿ3333f3™3Ì3ÿff3fff™fÌfÿ™™3™f™™™Ì™ÿÌÌ3ÌfÌ™ÌÌÌÿÿÿ3ÿfÿ™ÿÌÿÿ3333f3™3Ì3ÿ3333333f33™33Ì33ÿf3f33f3ff3™f3Ìf3ÿ™3™33™3f™3™™3Ì™3ÿÌ3Ì33Ì3fÌ3™Ì3ÌÌ3ÿÿ3ÿ33ÿ3fÿ3™ÿ3Ìÿ3ÿff3fff™fÌfÿ3f3f33ff3f™3fÌ3fÿffff3fffff™ffÌffÿ™f™f3™ff™f™™fÌ™fÿÌfÌf3ÌffÌf™ÌfÌÌfÿÿfÿf3ÿffÿf™ÿfÌÿfÿ™™3™f™™™Ì™ÿ3™3™33™f3™™3™Ì3™ÿf™f™3f™ff™™f™Ìf™ÿ™™™™3™™f™™™™™Ì™™ÿ̙̙3Ì™fÌ™™Ì™ÌÌ™ÿÿ™ÿ™3ÿ™fÿ™™ÿ™Ìÿ™ÿÌÌ3ÌfÌ™ÌÌÌÿ3Ì3Ì33Ìf3Ì™3ÌÌ3ÌÿfÌfÌ3fÌffÌ™fÌÌfÌÿ™Ì™Ì3™Ìf™Ì™™ÌÌ™ÌÿÌÌÌÌ3ÌÌfÌÌ™ÌÌÌÌÌÿÿÌÿÌ3ÿÌfÿÌ™ÿÌÌÿÌÿÿÿ3ÿfÿ™ÿÌÿÿ3ÿ3ÿ33ÿf3ÿ™3ÿÌ3ÿÿfÿfÿ3fÿffÿ™fÿÌfÿÿ™ÿ™ÿ3™ÿf™ÿ™™ÿÌ™ÿÿÌÿÌÿ3ÌÿfÌÿ™ÌÿÌÌÿÿÿÿÿÿ3ÿÿfÿÿ™ÿÿÌÿÿÿ,(=ÿ¯]SE¥ ª\XP C…#^D…•ÀU9depcÁ„ÿttHŠH!=éðŠŠ)6|xÍ H‡€V­œ¹ófɃ4Z|¨Ò!K£=jü²ìw
~èž@ê57Fï!ˆ‡Ø_ƒÃÉà5¦M"7!zõÉ’¡~׈7T‡ÃÝçÞ!¢¹WŸŠè‘8܃¨‰'Ðîá€Z‡8Ò+6èŠñá¸"Šzˆ^ð!‚_}îéG£pF¦'+^ƒÈ(#pBy Tn,^#i’ˆ%âGžo4ÒWšœZ.ù¥pè¥ùà‡ÔŸ…î͇‹²lé b9&u0öiŸzUúw݃k
šç”’aчªá~H>º‘¬°) †+²òCŸ¬Cé5¦) ,A_?X¤ë©£Vº§wŠã°Úýºªƒ1:h¦€*æÐ¥©Ë
9jµÌ¦‡ì~‘R ¶ü-i«C];sdf-2.001/perllib/sdf/home/images/htx.gif010064400042570001753000000002740632211164200200120ustar00iancmtr00000400000236GIF87aóÿÿÿÌÿÿ™™™fff333,qÈIg¸8À»ßDvmEi–À–Šäi¦]ˆ©3à¾Ñÿ#Ý® t=HŽ`)(‘‡‡éÔ¢Xl²Ìf·Uš'
~&ËÖ¨Š@FrÓÞö4<–žïM\ÞÉ_k|Jtwhb…ƒ#LŒK>C’N!;sdf-2.001/perllib/sdf/home/images/new1.bmp010064400042570001753000000022560613464277400201140ustar00iancmtr00000400000236BM®v(F8&V:F\02 P‘¥¬¬¹

ÕëBWÛ®®ÎÕÜãöýýÊÊÎînîîîîîænnîfîîîfînfîîînîîæîîîîîîîîîîîîîîîæc6næfVfc5næ5nîffnîîæîffnîînîîææîîîæc3fcV353ff36næîæc36îîffnîæfnîne"130"1326îfS34CVfS36îîæ36fd""#"$"""!!!!#5S34Gw”534Cfîæ™S14r"""""'"r"""!""3GwwˆC3DwCnîî§wyD#4w"r'"rrw""""""DG'xwˆˆGx‡„Vîîîêxwˆwwwwwwwwwwr'""""''ww‡‡ˆˆ‡ˆufîîîæ—ˆxx‡‡‡xww‡wwr"""""wwww‡ˆ‡ˆˆ‡Fnîîîîjxˆˆˆx €ÿÿÿð!ÿð"ÿÿ'ðxwˆˆˆt3fîîînê—ˆˆˆ‹Í¼ÕÝÝÝPÍÝ¿-ÝÓ'Ýß(ˆˆˆˆ„fîîîæ©xˆˆŒÝÍÕ=ÝÝ_½ÜßÝÓÝßw‡ˆˆˆ‡Cfîææc—ˆˆˆÝßÍÛÝݱ½ÝÕÝÝ÷½×w‡ˆˆˆˆ‡D3fîf34HˆˆˆÝßÝÝÝñ½ÝÕÝÝwÿ'ˆˆˆˆˆˆ‡–îîªIx‡ˆˆˆÍÐÝÝÝ?/½ÜÝ
ÝÝPMÕ÷wxˆˆˆ„–®îå—ˆˆˆˆˆˆ¼ÓÝÝ»Ýßÿ¼ÝÍ»ÜÝ¿}Ý÷wˆˆˆ„CVnîæ©wˆˆˆˆˆÓÝÝ»ÝÝß\ݽ»ÛÍÏ-Ýwxˆˆ„@fîîîi—ˆxˆxÓÛݵÝÝÛݼ»Û½ÛüÝ2wxxˆˆsfîîîîi—ˆˆˆÝÛ½°ÝÝÛ,ÝÝÛ¼ÛûÍ0wwˆˆˆtA5îîîîæi—‡ˆÝѽÑÝÑÝ=ÝÛýÝÝßww‡—ww•VnîîæfDˆ‡xŒÝ߼ѽÛÿýÝÝÜûÝÝÐ'x„#Y™™nnîîæTˆwˆˆxÝß¼Ó]ÝÝÝ3ÝÝûݳÜÓ‡wA6fjnîîæTHxˆ‡ˆwÝßMÝ]ÝÝ;Ý0ÝÝóÝÐÝÕwˆBnîîîîe—ˆˆxˆˆ‡Ý×|Ý-ÝÝÛÍ0½ÝÿÝÔÝÜxxwsnîîîê™xwyx‡ˆˆywww! ÿÿðððw'w‡‡wwfînî榦ªª—‡ˆyi—w‡""ÿÿð'$Dwwwt!>îîîîîînê˜wyfêxwIB"30'$5iGwwCnîîîîîîæw™jîix™f”"#Vanc2'#6îfTGJfnîîîîîîi™nîî©™fê”sFæã6nædDsVîîîe•®îîîîîîîæ®îîîîi–nîæ3nîîæTFnîîîîæîîîîsdf-2.001/perllib/sdf/home/images/bar1.gif010064400042570001753000000033120613456427200200440ustar00iancmtr00000400000236GIF89a€÷U€ªÕÿ+U+€+ª+Õ+ÿ+UUU€UªUÕUÿU€U€€€ª€Õ€ÿ€ªUª€ªªªÕªÿªÕUÕ€ÕªÕÕÕÿÕÿUÿ€ÿªÿÕÿÿÿUUU€UªUÕUÿU+UU+U€+Uª+UÕ+Uÿ+UUUUUU€UUªUUÕUUÿUU€UU€U€€Uª€UÕ€Uÿ€UªUUªU€ªUªªUÕªUÿªUÕUUÕU€ÕUªÕUÕÕUÿÕUÿUUÿU€ÿUªÿUÕÿUÿÿU€U€€€ª€Õ€ÿ€+€U+€€+€ª+€Õ+€ÿ+€U€UU€€U€ªU€ÕU€ÿU€€€U€€€€€ª€€Õ€€ÿ€€ª€Uª€€ª€ªª€Õª€ÿª€Õ€UÕ€€Õ€ªÕ€ÕÕ€ÿÕ€ÿ€Uÿ€€ÿ€ªÿ€Õÿ€ÿÿ€ªUª€ªªªÕªÿª+ªU+ª€+ªª+ªÕ+ªÿ+ªUªUUª€UªªUªÕUªÿUª€ªU€ª€€ªª€ªÕ€ªÿ€ªªªUªª€ªªªªªÕªªÿªªÕªUÕª€ÕªªÕªÕÕªÿÕªÿªUÿª€ÿªªÿªÕÿªÿÿªÕUÕ€ÕªÕÕÕÿÕ+ÕU+Õ€+Õª+ÕÕ+Õÿ+ÕUÕUUÕ€UÕªUÕÕUÕÿUÕ€ÕU€Õ€€Õª€ÕÕ€Õÿ€ÕªÕUªÕ€ªÕªªÕÕªÕÿªÕÕÕUÕÕ€ÕÕªÕÕÕÕÕÿÕÕÿÕUÿÕ€ÿÕªÿÕÕÿÕÿÿÕÿUÿ€ÿªÿÕÿÿÿ+ÿU+ÿ€+ÿª+ÿÕ+ÿÿ+ÿUÿUUÿ€UÿªUÿÕUÿÿUÿ€ÿU€ÿ€€ÿª€ÿÕ€ÿÿ€ÿªÿUªÿ€ªÿªªÿÕªÿÿªÿÕÿUÕÿ€ÕÿªÕÿÕÕÿÿÕÿÿÿUÿÿ€ÿÿªÿÿÕÿÿ???kkk•••ÃÃÃÿÿÿ,€þ©(PË@ƒ©\¨Š-#Bœ(±"!-3bܨ±#!0C‚£ˆPÉ“&S¢\©¨¥Ë—0aBR4³&Í›6sÒ‚´³'OHº€

Jt¨Q]º,%]ª´)S¦ÀtE*U*°«X³jÕjXׯ^«ÎXÙ³fÁSËv­Û¶pßÊUË^Ý»ví³··/_{ðØžáÈ	ì·1ÞÇyãJžK.ÚËcÅjÎÜu«gÏU©NuJúi風ªöÉ:'Î×®gÆœ=[¥í•·GŠÙ‘£ïÞ„*R.ÜOC†*'(ðóçÏ6,¨¥úCëÕ³cמ½wuBà1þ†dyò·U¶4¹Þ%{Úð_Ê–ér~Í~æÇ/4P ©!EÔRH)U €.u•US-øÙƒfÕYXW}eLZ–uáZ^ÈV‡ome#ÖUâˆy¶—a+
†˜a…½£Œ.þÅâay¨#‰JÖáb($…DNá‘Z1¨ä‚	6‰à“øßýégåN7µdßlóÅß{`º‡[Iä™ÇÛxh^ôoÜmÇÝuewÐœÐÕI…sÌ!wÜžzGÜŸ~÷Û çé6Ò˜éé%|±ÁæèO­í jR–f©i¢…Æ ’\mæ)g˜¡UÙ¨“ÅÙcýµ—b¬Ò˜ØbþŠ¥ÚשyÕU*©¸¦*gŸzÊéVšŠvé°RjlQ‘þôè²6-J[¢Ðždèn‚VË‘ŸØRÄç¶zJ7žvÖ)ÝBqþÙ&wÖ¦‹ÞºÑ¾ôž³ðrÉl~ôZ9é½C	¨¯¾§mºé¯WX¤Xz˜á­ãŠ"Š&Öbª®F,±ª6þÅðÂ(&¬ñ\\–f0ÀþèÔ¾(«ò~õÒËl¼0Çô.¢d²K¡8kt®vÂm7ÝÏá>nž{&Ô­C€&Qº9ïf(ÍÑÎs£T㔬¤*ßkÚÖ–f*ÚÈöÊ«®d—•ëÙ¦Öª63²Zk®¶+ų®­öÆx¯µë²Çc÷
6VÁ†F,±øéáXV]uÌbF=æ´º1]m¶”sû³žÐ
ôrãfç瞇žóoã‰g¦™ížÔÞêŒË«e}°_I/©ùw,¸;y ƒ¼7ø÷ƒïÕÁÄÙãñ"ïÖˆm5ì|ŒÓãÄ8Ò=ŒÏŸØó!Ÿü÷@\ðÀÿþà’¼ç¥ú†Û^Ëð+»åëô·.³˜¬C[æþI¾Q¹ sœÆE§Í}+ ;sdf-2.001/perllib/sdf/home/images/qsd.gif010064400042570001753000000011630620155423200177760ustar00iancmtr00000400000236GIF87acd€ÿýýÿ,cdÿŒ©Ëí£œ´Ú‹³Þ¼û†âH–扦êʶîÇòL×öçúÎ÷þ
‡Ä¢ñhÜÄòÙÔ˜C'ôºÄ	[+«íņ¯ùO½æk-YÎ"ÚgÚ4-WÓÁ²l3¯·5#WÄ%X÷B–x€HÆ÷ô	¨RåtˆT‰¹¶Âè`y	šy2JgzŠJbáøéŠKÊÚZk[¢»:É«*2(ŒëĭLùá¦0êüÂ7GI]Ýñ%©½Í‘hê
žÌm‰×Kkþœ1¸{ÙÙ>ŒÝ*ß\Š‰O;oÓDþöU
¸APÂkcÊ…¸·®B7YÅ	<ôn⃊þeòËÕåÕÆq
"ºXò¢šm(¤ ²ÑIc÷R¦e2fÃ]:A’ÔëÜHFÅ\¶´©ª¿E}-—óÎ̦<ÃÑÔø,æLžN•¤éÔ­,(ü$VÏ=‡‚W•R¶Ý&ª²ŽP™C3Fûsç«CÇÈvôËtoÕÛDZYø/ž-©¥¬J¨{¹&¹Å`,oô 9_?®f1Ã|	u™^¯L¬¡Nk–gl—Ù]¤Z±4b¶Åâ¾Ùö1ïÙº'ÑÍI™åâÆ	³>¬ÜjRœ[B÷EU­í“›x­õ7åÈ;Sõ>t
^ÐÍ÷ïæ©ãÚÕf;Ö4}êƒaSÚãÂEõ	ÜO)ƒ
D)òM‚
C‚ÊöV„&ùç!úÑó†QÚØ0‡ v•!‰ˆ†oÈ(1!/JЃÜ2ÎHc6ÞˆcŽ:îÈc3;sdf-2.001/perllib/sdf/home/images/m0omo7eu.gif010064400042570001753000000021570613262731400206700ustar00iancmtr00000400000236GIF87aXÄÿÿÿ÷÷÷ÆÆƽ½½œœœ111)))„ssÿÖÖ)JRRs{R¥­9œ¥Zc){ŒZk9R!9ÎÆÎÖµ½÷s„ÿ­µ÷csç„Œ÷)9ÿŒ”ïRZ÷9B÷,Xÿ  Ždižhª®lúµp,Ïë÷ÂïzÏÿ¾ p(,ÆžM4h:ŸÐ¨tJ­Z¯Ñ%@7™H¾à°XÒõv‘èdz­¼5Çð±—,ÁÚïwVïÓçul‚j„@Z9a‹pŒb9“•›™œ:M—9Ÿž—œ™Q‡naÁ»½a:±›­°ÎЖ˜9ӨחÑÕ­ç:¶
nÁÂ¾ïÃb’Ÿýׯ¼
Õã´n=° ¤£ŸR—ÖÊÐÁ¢€Ù&‚ÂÆ¡‰pÙªÿ1«dí\¨Ö8Q›-â‡
ìÈVN [;ìð®(€óìY¯i2OߪiB˜Mç7O¤N‚*Às’ªO=Pº–¨
ÛcÀ–-p´eà@äÆ`’vy’7ˆt€Mæ-Ë­‡ÃCÙBP,„rÙÖË]¾z%ñ5™³Í’Ô5œVŶ7†à²ÇH)3ðœ£B†
O*pȤ³_Î/âÄùÏ€Q£yý)p©Ð¡9…¾tºèR¨DuUJ5#Í`ÂäÉŸÙ³f¹v½h’èÚeß²ˆu%T‹ûö
Ð{Ӯߡ=ß$Z—¨Þ}è[X­`ºWþË;Rqa»ø<>¶GØï䘋#w̬¹ëàÈÿöb‹qñe²MCöüù©â´­§„­Y¬ÇÀ^!×U-4tÜ‹®“¾yWªã’³ï"^ÝÓlâÆËwKθªp¿FþG®›·gÅè“·xÚót›¸/òel¾¯Í©O‡ÿ*íϱdnaŸoÆö~Áq&ZxY'Ú„b烑A…VÈ t6¦¡EÖ•×ባÅ& †…øO‰ÊÅ›J3}×¢‹ÚÕµ[‚<"X#‹¢ Øj¨™XX^Hö>ƒõØQzbå8!’ïᵑLÒ夂ž™e;Ò˜”r„Ö™hž¦—8)$>·‰y%}!Y5¦]öžÆÁ‰Ñœ~eö£M<®)%TUªÕßdJÂf§L
ê	WY·™GÆÄå‘ðÁYir[-—)J½•w@•$
ú'¨+e7êIs¥Š†ªHó1æjSWmd¢ªZÉ*`¥½J›)÷R›y	¹©yƒú×è_{Q™¬e›¾XZ³AéZ!Ÿèú,³Øú´å¸ae7—=N‘«nŠb†[SšðÆ+oZºKÕº[6(ךøFÙ E,ðÀlðÁ;;sdf-2.001/perllib/sdf/home/images/hot_dot.gif010064400042570001753000000025160604426734000206600ustar00iancmtr00000400000236GIF89a÷€€€€€€€€€ÀÀÀÀÜÀ¦ÊðȬ³º §³ˆŒBš§/~ˆ_g7<3f™Ì3333f3™3Ì3ÿff3fff™fÌfÿ™™3™f™™™Ì™ÿÌÌ3ÌfÌ™ÌÌÌÿÿ3ÿfÿ™ÿÌ3333f3™3Ì3ÿ3333333f33™33Ì33ÿ3f3f33ff3f™3fÌ3fÿ3™3™33™f3™™3™Ì3™ÿ3Ì3Ì33Ìf3Ì™3ÌÌ3Ìÿ3ÿ3ÿ33ÿf3ÿ™3ÿÌ3ÿÿff3fff™fÌfÿf3f33f3ff3™f3Ìf3ÿffff3fffff™ffÌffÿf™f™3f™ff™™f™Ìf™ÿfÌfÌ3fÌffÌ™fÌÌfÌÿfÿfÿ3fÿffÿ™fÿÌfÿÿ™™3™f™™™Ì™ÿ™3™33™3f™3™™3Ì™3ÿ™f™f3™ff™f™™fÌ™fÿ™™™™3™™f™™™™™Ì™™ÿ™Ì™Ì3™Ìf™Ì™™ÌÌ™Ìÿ™ÿ™ÿ3™ÿf™ÿ™™ÿÌ™ÿÿÌÌ3ÌfÌ™ÌÌÌÿÌ3Ì33Ì3fÌ3™Ì3ÌÌ3ÿÌfÌf3ÌffÌf™ÌfÌÌfÿ̙̙3Ì™fÌ™™Ì™ÌÌ™ÿÌÌÌÌ3ÌÌfÌÌ™ÌÌÌÌÌÿÌÿÌÿ3ÌÿfÌÿ™ÌÿÌÌÿÿÿ3ÿfÿ™ÿÌÿ3ÿ33ÿ3fÿ3™ÿ3Ìÿ3ÿÿfÿf3ÿffÿf™ÿfÌÿfÿÿ™ÿ™3ÿ™fÿ™™ÿ™Ìÿ™ÿÿÌÿÌ3ÿÌfÿÌ™ÿÌÌÿÌÿÿÿ3ÿÿfÿÿ™ÿÿÌ			


ÿÔÅÿÖÈÿÜÌÿÞÐÿÿÀÿÿÆÿÿÉÿÿÍÿãÕÿåØÿêÜÿÿÐÿÿÖÿûð  ¤€€€ÿÿÿÿÿÿÿÿÿÿÿÿ!ù,ÿHðÀªƒ*\(p)U¥T5›H±Ã…€Hi¬8ÍÙ4jÓ&ƺ8ðÐR«&¦¤Æ²%Ëf«HÊCª”±”Í@êüȳÙ1††ª<”Æl"µlH‘jk9­©ª‘UI•
¬[Ó²a‹ÅÈF·¼%µ…
›´[u}凘²Œ,˜àÆ¡n·nàpk–6†
á¨k®˜nè*ÀÛbh„1G­¹†ºÝ ;†ò\·p,†u`L¡¶,šÛXô\X’è⸅ÍuFªÜX@˜ËŒmmf͈nŒ[ÝÄÌíÕª-ŒD‹QÎøZºŒ
Ï:af†vWÿmk¤ˆ@AÞ°›a×0 ]üÁ"kaÒÈ@b„agn¥òJtŠá`È+¤R§„QPfÆYÈTK#Ù½H
£TM©PbVpCUlñG!©€ZHƒyTQE10tÈc¨šÚ ©¦Æ+0Þ!$=¶œʇIaŸ­tÑÊë@c¸f+c»‡àÀ‡¤Ák@;sdf-2.001/perllib/sdf/home/images/new2.bmp010064400042570001753000000117660613464277600201250ustar00iancmtr00000400000236BMö6(=?ÀÀÀÀ@@ÿsdf-2.001/perllib/sdf/home/images/bg_ball.bmp010064400042570001753000000026120613464276600206210ustar00iancmtr00000400000236BMŠ6(T€€€€€€€€€€€€TŒŒŒÌ44ÜÜÜœddœ4Ìœœd4Ìœdd4ÀÀÀÌddìììÌÌœtdœœœÌd4üÌÌœ44üœœd44üœdÄÄÄüddüüüüÌœÀÀÀÿÿÿÿÿÿÿÿÿÿÿÿ	









 


"

!





sdf-2.001/perllib/sdf/home/images/sdfbig.gif010064400042570001753000000011510632062617200204470ustar00iancmtr00000400000236GIF89aBkóÿÿÿffÌÌ3™f,BkÿÈI«½8ëÍ»ÿ`(ŽdižhšlËNåÎôFß7üê®UW½Õì2´ˆG_¸T&‘±§ºsV™RëUIaŠØmX,óŽ5M¹œvÑm0ŒÝžkáYc|œöéfrzZuwx[ƒb8jo€j]9_†Ž|?“ƒ—ˆ`–zŒ~‰ik˜‹ ¡¥Y‰¤y›a‡2n¯«·²gµ:³£œp6° u±XxÀSÊPÉ¿ºÏT•¹¸Ó¾Ã¦k”’¶Ôv¸Œ™Ó8*æçèéêíëéíñïçñîóæõ÷øòú)ùý(þ4!pàˆz–@¨Æ"
@qD
+j´x‘]Â	ÿ+väRãH
%Ež4	2%Ç‹)%¸|	1¦Ì’#gÞÙ’b:–=q
ô„͉.75*éR:™}
5©Ô¦T+D5±u'M§4»’{ajÓ«E3˜å™biÑ®iÛªôÊ’¬A›vêÜ÷ªV«xÏ–X+40[´sá&¶:˜qÖ¿?ð\–ñXË`«ú$ºq_ÍéÎåJáÏ!ÜŽ{8ó¹·X1ßù^ÔÉ›m;.\úõn¶µå>š×\pѨUÝúñ³Åu7?¾Nqód“ë‹žó÷׎†CwÞ»ásê5e›Í]zèöóN¯Vx»|?ëß×£×o%ôù0ñv]€¹±àIœižz¨ ý'^ƒÌH¡W@";UW½Õì2´ˆG_¸T&‘±§ºsV™RëUIaŠØmX,óŽ5M¹œvÑm0ŒÝžkáYc|œöéfrzZuwx[ƒb8jo€j]9_†Ž|?“ƒ—ˆ`–zŒ~‰ik˜‹ ¡¥Y‰¤y›a‡2n¯«·²gµ:³£œp6° u±XxÀSÊPÉ¿ºÏT•¹¸Ó¾Ã¦k”’¶Ôv¸Œ™Ó8*æçèéêíëéíñïçñîóæõ÷øòú)ùý(þ4!pàˆz–@¨Æ"
@qD
+j´x‘]Â	ÿ+väRãH
%Ež4	2%Ç‹)%¸|	1¦Ì’#gÞÙ’b:–=q
ô„͉.75*éR:™}
5©Ô¦T+D5±u'M§4»’{ajÓ«E3˜å™biÑ®iÛªôÊ’¬A›vêÜ÷ªV«xÏ–X+40[´sá&¶:˜qÖ¿?ð\–ñXË`«ú$ºq_ÍéÎåJáÏ!ÜŽ{8ó¹·X1ßù^ÔÉ›m;.\úõn¶µå>sdf-2.001/perllib/sdf/home/images/square_b.gif010064400042570001753000000000510613463001000207750ustar00iancmtr00000400000236GIF87a

€ÿÿÿ,

Œ©Ëíc+;sdf-2.001/perllib/sdf/home/images/key.bmp010064400042570001753000000003260613034305400200070ustar00iancmtr00000400000236BMÖv(¿¿¿¿¿¿¿¿¿ÀÀÀ€€€ÿÿÿÿÿÿÿÿÿÿÿÿ÷÷÷÷ÿÿðp33pppÿÿ𳻀ð0»333330ð0»»»»»»»€¸¿ˆˆˆˆˆˆ€pÿÿÿÿÿÿÿð÷ˆˆÿÿÿÿÿðsdf-2.001/perllib/sdf/home/images/camera1.gif010064400042570001753000000004650613456427000205340ustar00iancmtr00000400000236GIF89a%%³ÿÿÿÿèš}}},%%êÈI«½XàͳA(Ždi†C*|gëi¼J/·qÌ 7R.5áሓ m˜4–~–¡.©b=1R(ðçF³Š¶;
S§i…,23¿ÈµU¨Çå´'¸òÆ÷èDw|ZEs(Pqj[f]oHva„;,S’n‘—~„–™iŒ”Ÿ ˆ™˜¤©žw*¸ÒºÓÔåÔÛ
áúÛ´ù» Ö¦.(±s#/ZqÝôáÛ@[‰üô œ2þsäĘ³BZ×èEÑ”6!æð0±Áª“]ؘácäZ'Pœùr‘Åm¼¬ù 'WM’Бð3h4¤áÔ¶@@ÊŠ\#&øÍi4<+„ˆâ	´Ôf¬ImXndm™
²³;È(´€ÅêY-q±æ{P å^¼
<ÈFí¦a++drù0YÅôJEŒÌ-œã¦â>^†Ž†?'/§Üj³ïd™Ôfç+À^¦ªWƒxBõw‡ÅQ×·¶w©‰™RêØáëz^„ð,—8Çѹ±Ü}ñ~¯£u4¤R÷M_¤,¼ók¢—M­é0 A´þד™\·’ÑEPJÜL¶_â ÞAA€Ø!@È( L0ªÀbÊ(ş$ã{
pKèx$£1¡Ô
/SÀ££.,L%†9ւ㑤acj¸‚‹a±Iåy’4ªqŒ‘IZydFdiP.:ĆY(|@€d” Ã–6Z©¥ƒ„"„šJb–H+ŽLuÆœsH(ê„ògƒ*,k q¦šaRáÈ¢¬µèôóEi&’æ¥8g	k´±èq­¥È:#ˆ	™Î¡NŠ¨UÂ2®²ADÆ¡Z¥ìàjë®RmUÃî*é€}6óB¯-Ðp,3“F!m¯.D;sdf-2.001/perllib/sdf/home/images/printer.gif010064400042570001753000000016150621072063600206770ustar00iancmtr00000400000236GIF89a÷ÿÿÿÿÿÌÿÿ™ÿÿfÿÿ3ÿÿÿÌÿÿÌÌÿÌ™ÿÌfÿÌ3ÿÌÿ™ÿÿ™Ìÿ™™ÿ™fÿ™3ÿ™ÿfÿÿfÌÿf™ÿffÿf3ÿfÿ3ÿÿ3Ìÿ3™ÿ3fÿ33ÿ3ÿÿÿÌÿ™ÿfÿ3ÿÌÿÿÌÿÌÌÿ™ÌÿfÌÿ3ÌÿÌÌÿÌÌÌÌÌ™ÌÌfÌÌ3ÌÌÌ™ÿÌ™ÌÌ™™Ì™fÌ™3Ì™ÌfÿÌfÌÌf™ÌffÌf3ÌfÌ3ÿÌ3ÌÌ3™Ì3fÌ33Ì3ÌÿÌÌÌ™ÌfÌ3Ì™ÿÿ™ÿÌ™ÿ™™ÿf™ÿ3™ÿ™Ìÿ™Ì̙̙™Ìf™Ì3™Ì™™ÿ™™Ì™™™™™f™™3™™™fÿ™fÌ™f™™ff™f3™f™3ÿ™3Ì™3™™3f™33™3™ÿ™Ì™™™f™3™fÿÿfÿÌfÿ™fÿffÿ3fÿfÌÿfÌÌfÌ™fÌffÌ3fÌf™ÿf™Ìf™™f™ff™3f™ffÿffÌff™fffff3fff3ÿf3Ìf3™f3ff33f3fÿfÌf™fff3f3ÿÿ3ÿÌ3ÿ™3ÿf3ÿ33ÿ3Ìÿ3ÌÌ3Ì™3Ìf3Ì33Ì3™ÿ3™Ì3™™3™f3™33™3fÿ3fÌ3f™3ff3f33f33ÿ33Ì33™33f333333ÿ3Ì3™3f333ÿÿÿÌÿ™ÿfÿ3ÿÌÿÌÌÌ™ÌfÌ3Ì™ÿ™Ì™™™f™3™fÿfÌf™fff3f3ÿ3Ì3™3f333ÿÌ™f3îÝ»ªˆwUD"îÝ»ªˆwUD"îÝ»ªˆwUD"îîîÝÝÝ»»»ªªªˆˆˆwwwUUUDDD"""!ù+,jWH° ÁƒÖ[¸ÀŸ„6tQ Äz2>„x1_¾z6*¼¸0$G’ ED™¡Ç—0aÌ·¯¦Í›ûþ©H§Íp9MìéÓ¦Îÿ’*]ªT(ÁP£J=(µªÓŠX³¸" ;sdf-2.001/perllib/sdf/home/images/sqbull.gif010064400042570001753000000014740621521432000205120ustar00iancmtr00000400000236GIF89a÷¿¿¿¿¿¿¿¿¿ÀÀÀÀÜÀ¤Èð¼¼¼¼¼¼¼¼¼€€€€€€€€€<\<\\<|\<œ\<¼\<Ü\<ü\<<|<\|<||<œ|<¼|<Ü|<ü|<<œ<\œ<|œ<œœ<¼œ<Üœ<üœ<<¼<\¼<|¼<œ¼<¼¼<ܼ<ü¼<<Ü<\Ü<|Ü<œÜ<¼Ü<ÜÜ<üÜ<<ü<\ü<|ü<œü<¼ü<Üü<üü<<<\\<\|<\œ<\¼<\Ü<\ü<\<\\\\\|\\œ\\¼\\Ü\\ü\\<|\\|\||\œ|\¼|\Ü|\ü|\<œ\\œ\|œ\œœ\¼œ\Üœ\üœ\<¼\\¼\|¼\œ¼\¼¼\ܼ\ü¼\<Ü\\Ü\|Ü\œÜ\¼Ü\ÜÜ\üÜ\<ü\\ü\|ü\œü\¼ü\Üü\üü\<<|\<||<|œ<|¼<|Ü<|ü<|<\|\\||\|œ\|¼\|Ü\|ü\|<||\|||||œ||¼||Ü||ü||<œ|\œ||œ|œœ|¼œ|Üœ|üœ|<¼|\¼||¼|œ¼|¼¼|ܼ|ü¼|<Ü|\Ü||Ü|œÜ|¼Ü|ÜÜ|üÜ|<ü|\ü||ü|œü|¼ü|Üü|üü|<<œ\<œ|<œœ<œ¼<œÜ<œü<œ<\œ\\œ|\œœ\œ¼\œÜ\œü\œ<|œ\|œ||œœ|œ¼|œÜ|œü|œ<œœ\œœ|œœœœœ¼œœÜœœüœœ<¼œ\¼œ|¼œœ¼œ¼¼œÜ¼œü¼œ<Üœ\Üœ|ÜœœÜœ¼ÜœÜÜœüÜœ<üœ\üœ|üœœüœ¼üœÜüœüüœ<<¼\<¼|<¼œ<¼¼<¼Ü<¼ü<¼<\¼\\¼|\¼œ\¼¼\¼Ü\¼ü\¼<|¼\|¼||¼œ|¼¼|¼Ü|¼ü|¼<œ¼\œ¼|œ¼œœ¼¼œ¼Üœ¼üœ¼<¼¼\¼¼|¼¼Ðåдý˜åå˜{{˜ÿûð  ¤€€€ÿÿÿÿÿÿÿÿÿÿÿÿ,!ñ	H°`ÚjKpŸÂ…
2D¨p">†fÄ;|Ü\œÜ\¼Ü\ÜÜ\üÜ\<ü\\ü\|ü\œü\¼ü\Üü\üü\<<|\<||<|œ<|¼<|Ü<|ü<|<\|\\||\|œ\|¼\|Ü\|ü\|<||\|||||œ||¼||Ü||ü||<œ|\œ||œ|œœ|¼œ|Üœ|üœ|<¼|\¼||¼|œ¼|¼¼|ܼ|ü¼|<Ü|\Ü||Ü|œÜ|¼Ü|ÜÜ|üÜ|<ü|\ü||ü|œü|¼ü|Üü|üü|<<œ\<œ|<œœ<œ¼sdf-2.001/perllib/sdf/home/locale/004075500042570001753000000000000672243774700165375ustar00iancmtr00000400000236sdf-2.001/perllib/sdf/home/locale/de_de.sdl010064400042570001753000000023220661500625400202610ustar00iancmtr00000400000236# $Id$
#
# >>Title::     Deutsch
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 23-Oct-98 ianc    Added date strings
# 12.Nov 97 alo
# 19-Aug-97 ianc
# -----------------------------------------------------------------------
#

# Generated list titles
!define DOC_TOC_TITLE           "Inhaltsverzeichnis"
!define DOC_LOF_TITLE           "Abbildungsverzeichnis"
!define DOC_LOT_TITLE           "Verzeichnis der Tabellen"

# Navigation strings
!define HTML_TEXT_CONTENTS      "Inhalt"
!define HTML_TEXT_PARENT        "Zurück"
!define HTML_TEXT_PREVIOUS      "Voriger Eintrag"
!define HTML_TEXT_NEXT          "Nächster Eintrag"
!define HTML_TEXT_HOME          "Home"
!define HTML_TEXT_CATALOG       "Katalog"
!define HTML_TEXT_SEARCH        "Suchen"

# Date string values
!block datestrings
Symbol   Values
month    "Januar Februar Marz April Mai Juni Juli August September Oktober November Dezember"
smonth   "Jan    Feb     Mar  Apr   Mai Jun  Jul  Aug    Sep       Okt     Nov      Dez"
weekday  "Montag Dienstag Mittwoch Donnerstag Freitag Samstag Sonntag"
sweekday "Montag Dienstag Mittwoch Donnerstag Freitag Samstag Sonntag"
ampm     ""
AMPM     ""
!endblock
sdf-2.001/perllib/sdf/home/locale/ru_ru.sdl010064400042570001753000000023120671075014700203570ustar00iancmtr00000400000236# $Id$
#
# >>Title::     Russian (Russia) Locale
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 18-Nov-98 alp     áreated from scratch (CP-866)
# -----------------------------------------------------------------------
#

# Generated list titles
!define DOC_TOC_TITLE           "Ž£« ¢«¥­¨¥"	
!define DOC_LOF_TITLE           "¥à¥ç¥­ì ˆ««îáâà æ¨©"
!define DOC_LOT_TITLE           "¥à¥ç¥­ì ’ ¡«¨æ"

# Navigation strings
!define HTML_TEXT_CONTENTS      "Ž£« ¢«¥­¨¥"
!define HTML_TEXT_PARENT        " ç «®  §¤¥« "
!define HTML_TEXT_PREVIOUS      "।ë¤ãé ï ƒ« ¢ "
!define HTML_TEXT_NEXT          "‘«¥¤ãîé ï ƒ« ¢ "
!define HTML_TEXT_HOME          " ç «®"
!define HTML_TEXT_CATALOG       "Š â «®£"
!define HTML_TEXT_SEARCH        "®¨áª"

# Date string values
!block datestrings
Symbol   Values
month    "Ÿ­¢ àì ”¥¢à «ì Œ àâ €¯à¥«ì Œ © ˆî­ì ˆî«ì €¢£ãáâ ‘¥­âï¡àì Žªâï¡àì ®ï¡àì „¥ª ¡àì"
smonth   "Ÿ­¢    ”¥¢     Œ à  €¯à    Œ © ˆî­  ˆî«  €¢£    ‘¥­      Žªâ     ®ï    „¥ª"
weekday  "®­¥¤¥«ì­¨ª ‚â®à­¨ª ‘।  —¥â¢¥à£ ïâ­¨æ  ‘ã¡¡®â  ‚®áªà¥á¥­ì¥"
sweekday "­          ‚â      ‘à    —â      â      ‘ã¡     ‚᪠"
ampm     "am pm"
AMPM     "AM PM"
!endblock
sdf-2.001/perllib/sdf/home/locale/en_ca.sdl010064400042570001753000000023130661401430700202630ustar00iancmtr00000400000236# $Id$
#
# >>Title::     English (Canadian) Locale
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 23-Oct-98 ianc    Added date strings
# 19-Aug-97 ianc
# -----------------------------------------------------------------------
#

# Generated list titles
!define DOC_TOC_TITLE           "Table of Contents"
!define DOC_LOF_TITLE           "List of Figures"
!define DOC_LOT_TITLE           "List of Tables"

# Navigation strings
!define HTML_TEXT_CONTENTS      "Contents"
!define HTML_TEXT_PARENT        "Parent Topic"
!define HTML_TEXT_PREVIOUS      "Previous Topic"
!define HTML_TEXT_NEXT          "Next Topic"
!define HTML_TEXT_HOME          "Home"
!define HTML_TEXT_CATALOG       "Catalog"
!define HTML_TEXT_SEARCH        "Search"

# Date string values
!block datestrings
Symbol   Values
month    "January February March April May June July August September October November December"
smonth   "Jan     Feb      Mar   Apr   May Jun  Jul  Aug    Sep       Oct     Nov      Dec"
weekday  "Monday Tuesday Wednesday Thursday Friday Saturday Sunday"
sweekday "Mon    Tue     Wed       Thu      Fri    Sat      Sun"
ampm     "am pm"
AMPM     "AM PM"
!endblock
sdf-2.001/perllib/sdf/home/locale/en_uk.sdl010064400042570001753000000023210661401430700203160ustar00iancmtr00000400000236# $Id$
#
# >>Title::     English (United Kingdom) Locale
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 23-Oct-98 ianc    Added date strings
# 19-Aug-97 ianc
# -----------------------------------------------------------------------
#

# Generated list titles
!define DOC_TOC_TITLE           "Table of Contents"
!define DOC_LOF_TITLE           "List of Figures"
!define DOC_LOT_TITLE           "List of Tables"

# Navigation strings
!define HTML_TEXT_CONTENTS      "Contents"
!define HTML_TEXT_PARENT        "Parent Topic"
!define HTML_TEXT_PREVIOUS      "Previous Topic"
!define HTML_TEXT_NEXT          "Next Topic"
!define HTML_TEXT_HOME          "Home"
!define HTML_TEXT_CATALOG       "Catalog"
!define HTML_TEXT_SEARCH        "Search"

# Date string values
!block datestrings
Symbol   Values
month    "January February March April May June July August September October November December"
smonth   "Jan     Feb      Mar   Apr   May Jun  Jul  Aug    Sep       Oct     Nov      Dec"
weekday  "Monday Tuesday Wednesday Thursday Friday Saturday Sunday"
sweekday "Mon    Tue     Wed       Thu      Fri    Sat      Sun"
ampm     "am pm"
AMPM     "AM PM"
!endblock
sdf-2.001/perllib/sdf/home/locale/en_us.sdl010064400042570001753000000023200661401430700203250ustar00iancmtr00000400000236# $Id$
#
# >>Title::     English (United States) Locale
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 23-Oct-98 ianc    Added date strings
# 19-Aug-97 ianc
# -----------------------------------------------------------------------
#

# Generated list titles
!define DOC_TOC_TITLE           "Table of Contents"
!define DOC_LOF_TITLE           "List of Figures"
!define DOC_LOT_TITLE           "List of Tables"

# Navigation strings
!define HTML_TEXT_CONTENTS      "Contents"
!define HTML_TEXT_PARENT        "Parent Topic"
!define HTML_TEXT_PREVIOUS      "Previous Topic"
!define HTML_TEXT_NEXT          "Next Topic"
!define HTML_TEXT_HOME          "Home"
!define HTML_TEXT_CATALOG       "Catalog"
!define HTML_TEXT_SEARCH        "Search"

# Date string values
!block datestrings
Symbol   Values
month    "January February March April May June July August September October November December"
smonth   "Jan     Feb      Mar   Apr   May Jun  Jul  Aug    Sep       Oct     Nov      Dec"
weekday  "Monday Tuesday Wednesday Thursday Friday Saturday Sunday"
sweekday "Mon    Tue     Wed       Thu      Fri    Sat      Sun"
ampm     "am pm"
AMPM     "AM PM"
!endblock
sdf-2.001/perllib/sdf/home/locale/en_au.sdl010064400042570001753000000023150661401431000203010ustar00iancmtr00000400000236# $Id$
#
# >>Title::     English (Australian) Locale
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 23-Oct-98 ianc    Added date strings
# 19-Aug-97 ianc
# -----------------------------------------------------------------------
#

# Generated list titles
!define DOC_TOC_TITLE           "Table of Contents"
!define DOC_LOF_TITLE           "List of Figures"
!define DOC_LOT_TITLE           "List of Tables"

# Navigation strings
!define HTML_TEXT_CONTENTS      "Contents"
!define HTML_TEXT_PARENT        "Parent Topic"
!define HTML_TEXT_PREVIOUS      "Previous Topic"
!define HTML_TEXT_NEXT          "Next Topic"
!define HTML_TEXT_HOME          "Home"
!define HTML_TEXT_CATALOG       "Catalog"
!define HTML_TEXT_SEARCH        "Search"

# Date string values
!block datestrings
Symbol   Values
month    "January February March April May June July August September October November December"
smonth   "Jan     Feb      Mar   Apr   May Jun  Jul  Aug    Sep       Oct     Nov      Dec"
weekday  "Monday Tuesday Wednesday Thursday Friday Saturday Sunday"
sweekday "Mon    Tue     Wed       Thu      Fri    Sat      Sun"
ampm     "am pm"
AMPM     "AM PM"
!endblock
sdf-2.001/perllib/sdf/home/locale/cz_cz.sdl010064400042570001753000000014020653464105400203320ustar00iancmtr00000400000236# $Id$
#
# >>Title::     Czech (CP1250) Locale
#
# >>History::
# -----------------------------------------------------------------------
# Date       Who         Change
# 02-June-97 Jan Tomasek
# -----------------------------------------------------------------------
#

# Generated list titles
!define DOC_TOC_TITLE           "Obsah"
!define DOC_LOF_TITLE           "Seznam obrázkù"
!define DOC_LOT_TITLE           "Seznam tabulek"

# Navigation strings
!define HTML_TEXT_CONTENTS      "Obsah"
!define HTML_TEXT_PARENT        "Nadøazené téma"
!define HTML_TEXT_PREVIOUS      "Pøedcházející téma"
!define HTML_TEXT_NEXT          "Následující téma"
!define HTML_TEXT_HOME          "Úvod"
!define HTML_TEXT_CATALOG       "Katalog"
!define HTML_TEXT_SEARCH        "Hledat"
sdf-2.001/perllib/sdf/home/perl/004075500042570001753000000000000672243774100162345ustar00iancmtr00000400000236sdf-2.001/perllib/sdf/home/perl/oracamel.gif010064400042570001753000000022170636252633200205000ustar00iancmtr00000400000236GIF87aIV³€€€€€€€€€ÀÀÀ€€€ÿÿÿÿÿÿÿÿÿÿÿÿ,IVþðÉI«½8ëÍ»ÿ`(ŽdižhÚìÓª°v<R#;Ǽ{Ø¿Ú-çê±pSP˜³Ýt;˜pM¹ çƒÝ„¿èŠŠ;›¶4V:>9ÎÖL…sÜIlŸ÷tXMx[qyzauCHKfxo‹†yƒjŠMdaicT…C¤@iIe:§S¨v¢²³|X{šio¬‚¹S±³¥O4p@ psq>¹žÁ–®:|LmG¨zO°—ÌÓ˧B%¦­wu†ÓLLeIçT“àÚÈÞÓ¹ØY3zpòœ1a!ê_[œ˜qçÊÝþø+Xì_˜	²Šýx“(Éš‹þ>>9Òt¦!.o
ÖXƒ
KÈ~/¸ !BÂv®Vº€¶ª… –Ò² ZÓ"[¾v¼JeãÉ•'ù1TÆ«í"&sÔSd¾¨
vˆÖ®žiÁð¤Á~9j¤[Èà¥*ßµ„ÂßqYÌÐíI´rNˆyŠÌ!»Ì ¬ì)Ÿsh4ÞñУ®Ø tL9ƒ7-Òâ8*¨Å£µ¹ö[;ã³+FK{	µõE§µÐ 5i:0ª°AŠiVIŽ¥)âË™Õh5„3ÊtØ*™fIB‡2„¸ÖÆË-‹´ü‰(|ɘº
*"jw¹jïY3ŽÛ}þhú™²¨7L-éY/˜×päS[iä5SQtÄ‚ÍU„††æÃ
%¢üDÛ‡ÈÈ{&ù’94à—\J¬õáKIídž*ÿPdÖkÔgŒ8•q^%Oü$‡,Î%F‰5JfG%¾BË„Y¼Ä”RÎÅŠ¦¹ç–Á@(Ní¢•[¬ Î}_ÖÅáL_‰â#6BâA”½Ñ2ä”4±8˲SmT¸>–`"o´`Ô"¢d† FIyõfИE¡ø)$‘ñ¼3#‡ü#r'Ü ¥mže뉀ÔwV
ÞÔ«JÃû«¥¹X3Ø	‚þ6µ~¶^ ’`0,t袣 ÔÚ±¸–XT"§\<‹rÁ8=øZˆ¨3rÛ[rP¦;$7½ù9,(ÞÊC^ÎË«¬PÓC´‚’¥bÌhºj\c"¾!ëpN¤[ã!<ªš´#aP1ÃDÂÊÖ$ªMl“¾1\s¬½¦"üÇTî‹ñ°™HÛÁéJ3ZˇÐ<É›È=ÚÔr~¡·È²!Ël2ÂÓÇÁÎ1€d—Бd±fLg¸£’©„­7xtÀk£õÖV´ÍlÏËÒf|;B„|q·iS§0ÓXIÜUÔ‘= ]•B·É08ª=1´ž«HâH¯	4Vrö²
]9œ®øÖ
JX›–\Ma}‚-z“@K쀓-·	¥n²5ð5}˜½»dµýþ5„Æ'¯üòÌ7ïü;sdf-2.001/perllib/sdf/home/perl/perl.sdm010064400042570001753000000100110640512353600176610ustar00iancmtr00000400000236# $Id$
#
# >>Title::     Perl Module
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 25-Jun-97 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{perl}} is the [[SDF]] library module for building
# the [[Perl]] documentation suite.
#
# >>Description::
#
# >>Limitations::
# 

# Set the default html root location
!if $var{'PERL_DIR_DEPTH'} ne ''
    !default PERL_HTML_ROOT "../" x $var{'PERL_DIR_DEPTH'}
    !script $var{'PERL_HTML_ROOT'} =~ s/\/$//
!else
    !default PERL_HTML_ROOT "/perl"
!endif

# Title page details
!define DOC_DISTRIBUTION    "UNLIMITED CIRCULATION"
!define DOC_PROJECT         "Perl 5.004_03"
!define DOC_PRODUCT         "User Contributed Perl Documentation"

# HTML configuration variables
!define HTML_BG_COLOR       COLOR_WHITE
!define HTML_URL_CATALOG    "$var{'PERL_HTML_ROOT'}/catalog.html"

# Add a logo
!define DOC_LOGO            "oracamel"
!define DOC_LOGO_BASE       "$var{'PERL_HTML_ROOT'}/"

# Define a footer
!macro HTML_FOOTER
Line:
[align=Center;size=9]
The Perl camel is a trademark of
{{A[jump="http://www.ora.com"] O'Reilly and Associates}}.[[nl]]
This document was generated using
{{A[jump="http://www.mincom.com/mtr/sdf/"] SDF [[SDF_VERSION]]}}.
!endmacro

# Copyright stuff
!macro DOC_COPYRIGHT
    Copyright [[c]] [[_DOC_YEAR]], [[DOC_OWNER]]

    This manual may be distributed under Perl's Artistic License.
!endmacro


################# Link Generation Stuff #####################

# Give each top level enumerated list item a hypertext id based on
# its first "word"
!on paragraph 'LI1';; \
    unless ($attr{'noid'} || $attr{'id'} ne '') { \
        $text =~ /^\S+/; \
        $attr{'id'} = "item_" . &TextToId($&); \
    }

# Generate hypertext links for Perl things
!on phrase 'PERLDOC';; $style = 'A'; \
    $attr{'jump'} = "$var{'PERL_HTML_ROOT'}/pod/$text.html"

# Detect other perl documents in the main perl document
!if $var{'FILE_BASE'} eq 'perl'
!on paragraph 'E';; \
    if ($attr{'verbatim'}) {$text = &Escape($text); delete $attr{'verbatim'}} \
    $text =~ s/ (perl\w+)/ {{PERLDOC:$1}}/g
!endif

# This routine provides the Perl-specific URL generation rules for L phrases.
!block script
sub BuildLinkUrl {
    my($page, $sect, $entry) = @_;
    my($url);
    my($dir);

    # Get the html root directory
    my $html_root = $var{'PERL_HTML_ROOT'};

    # If the page looks like standard documentation, assume it is
    if ($page =~ /^perl/) {
        $url = "$html_root/pod/$page.html";
    }

    # If the page looks like a library, assume it is
    elsif ($page =~ /^[A-Z]/ || $page =~ /^[a-z]+$/) {
        $page =~ s,::,/,g;
        if ($perl_ext_docs{$page}) {
            $dir = "ext";
        }
        else {
            $dir = $perl_vms_docs{$page} ? "vms" : "lib";
        }
        $url = "$html_root/$dir/$page.html";
    }

    # Otherwise, assume its in the current directory
    else {
        $url = $page ne '' ? "$page.html" : '';
    }

    # Add the section/entry, if any
    if ($entry ne '') {
        $entry =~ s/\(\)$//;
        $url .= "#item_" . &TextToId($entry);
    }
    else {
        $url .= "#$sect" if $sect ne '';
    }
    return $url;
}

# Build the list of extension & vms docs
# Note: this will only work when relative URLs are being created. Oh well ...
use File::Find;
%perl_ext_docs = ();
%perl_vms_docs = ();
find(\&perl_wanted, "$var{'PERL_HTML_ROOT'}/ext", "$var{'PERL_HTML_ROOT'}/vms");
sub perl_wanted {
    if ($File::Find::name =~ m#/ext/(.*)\.(pod|pm)$#) {
        $perl_ext_docs{$1}++;
    }
    elsif ($File::Find::name =~ m#/vms/(.*)\.(pod|pm)$#) {
        $perl_vms_docs{$1}++;
    }
}
!endblock

################# Index Generation Stuff #####################

# A poor man's index :-)
!on phrase ''       ;; if (length($text) < 50) {$attr{'index'} = $text}
!on phrase '[HAP]\d';; $attr{'index'} = $text
OC_YEAR]], [[DOC_OWNER]]

    This manual may be distributed under Perl's Artistic License.
!endmacro


################# Link Generation Stuff #####################

# Give each top level enumerated list item a hypertext id based on
# its first "word"
!on paragraph 'LI1';; \
    unless ($attr{'noid'} || $attr{'id'} ne '') { \
        $text =~ /^\S+/; \
        $attr{'id'} = "item_" . &TextToId($&); \
    }

# Generate hypertext links for Perl things
!on phrase 'PERLDOC';; $style = 'A'; \
    $attrsdf-2.001/perllib/sdf/home/perl/catalog.sdf010064400042570001753000000214300640514732000203260ustar00iancmtr00000400000236!init OPT_CONFIG='perl'; PERL_HTML_ROOT="./"
# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 08-Sep-97 ianc    2.000beta12 release
# -----------------------------------------------------------------------
#

# Setup the header/footer: as this is the catalog page, remove the
# jump to it.
!define HTML_URL_CATALOG ''

# Build the title
!define DOC_NAME "Perl Document Catalog"
!define DOC_TOC  0
!build_title

!subsections "Core Documentation,Pragmas,Libraries,Extensions,Utilities,," . \
             "VMS Stuff"; "noprefix"; "center"

This page provides a catalog of the supporting documentation supplied with
{{B:[[DOC_PROJECT]]}}.

The latest version of the documentation can be downloaded from
{{ftp://ftp.mincom.com/pub/mtr/sdf/perl/}}.
# Alternatively, you can generate it yourself using SDF.


P1: Core Documentation

!block references; root="pod/"; columns='REF:Reference'; wrap=6
Reference               Jump
perl                    perl.html
perlapio                perlapio.html
perlbook                perlbook.html
perlbot                 perlbot.html
perlcall                perlcall.html
perldata                perldata.html
perldebug               perldebug.html
perldelta               perldelta.html
perldiag                perldiag.html
perldsc                 perldsc.html
perlop                  perlop.html
perlembed               perlembed.html
perlfaq                 perlfaq.html
perlfaq1                perlfaq1.html
perlfaq2                perlfaq2.html
perlfaq3                perlfaq3.html
perlfaq4                perlfaq4.html
perlfaq5                perlfaq5.html
perlfaq6                perlfaq6.html
perlfaq7                perlfaq7.html
perlfaq8                perlfaq8.html
perlfaq9                perlfaq9.html
perlform                perlform.html
perlfunc                perlfunc.html
perlguts                perlguts.html
perlipc                 perlipc.html
perllocale              perllocale.html
perllol                 perllol.html
perlmod                 perlmod.html
perlmodlib              perlmodlib.html
perlobj                 perlobj.html
perlpod                 perlpod.html
perlre                  perlre.html
perlref                 perlref.html
perlrun                 perlrun.html
perlsec                 perlsec.html
perlstyle               perlstyle.html
perlsub                 perlsub.html
perlsyn                 perlsyn.html
perltie                 perltie.html
perltoc                 perltoc.html
perltoot                perltoot.html
perltrap                perltrap.html
perlvar                 perlvar.html
perlxs                  perlxs.html
perlxstut               perlxstut.html
!endblock

P1: Pragmas

!block references; root="lib/"; columns='REF:Reference'; wrap=6
Reference               Jump
autouse                 autouse.html
blib                    blib.html
constant                constant.html
diagnostics             diagnostics.html
integer                 integer.html
less                    less.html
lib                     lib.html
locale                  locale.html
overload                overload.html
sigtrap                 sigtrap.html
strict                  strict.html
subs                    subs.html
vars                    vars.html
!endblock

P1: Libraries

!block references; root="lib/"; columns='REF:Reference'; wrap=4; sort=Reference
Reference               Jump
Bundle::CPAN            Bundle/CPAN.html
CGI::Apache             CGI/Apache.html
CGI::Carp               CGI/Carp.html
CGI::Fast               CGI/Fast.html
CGI::Push               CGI/Push.html
CGI::Switch             CGI/Switch.html
CPAN::FirstTime         CPAN/FirstTime.html
CPAN::Nox               CPAN/Nox.html
Class::Struct           Class/Struct.html
Devel::SelfStubber      Devel/SelfStubber.html
ExtUtils::Command       ExtUtils/Command.html
ExtUtils::Embed         ExtUtils/Embed.html
ExtUtils::Install       ExtUtils/Install.html
ExtUtils::Liblist       ExtUtils/Liblist.html
ExtUtils::MM_OS2        ExtUtils/MM_OS2.html
ExtUtils::MM_Unix       ExtUtils/MM_Unix.html
ExtUtils::MM_VMS        ExtUtils/MM_VMS.html
ExtUtils::MM_Win32      ExtUtils/MM_Win32.html
ExtUtils::MakeMaker     ExtUtils/MakeMaker.html
ExtUtils::Manifest      ExtUtils/Manifest.html
ExtUtils::Mkbootstrap   ExtUtils/Mkbootstrap.html
ExtUtils::Mksymlists    ExtUtils/Mksymlists.html
ExtUtils::testlib       ExtUtils/testlib.html
File::Basename          File/Basename.html
File::CheckTree         File/CheckTree.html
File::Compare           File/Compare.html
File::Copy              File/Copy.html
File::DosGlob           File/DosGlob.html
File::Find              File/Find.html
File::Path              File/Path.html
File::stat              File/stat.html
Getopt::Long            Getopt/Long.html
Getopt::Std             Getopt/Std.html
I18N::Collate           I18N/Collate.html
IPC::Open2              IPC/Open2.html
IPC::Open3              IPC/Open3.html
Math::BigFloat          Math/BigFloat.html
Math::BigInt            Math/BigInt.html
Math::Complex           Math/Complex.html
Math::Trig              Math/Trig.html
Net::Ping               Net/Ping.html
Net::hostent            Net/hostent.html
Net::netent             Net/netent.html
Net::protoent           Net/protoent.html
Net::servent            Net/servent.html
Pod::Functions          Pod/Functions.html
Pod::Html               Pod/Html.html
Pod::Text               Pod/Text.html
Search::Dict            Search/Dict.html
Sys::Hostname           Sys/Hostname.html
Sys::Syslog             Sys/Syslog.html
Term::Cap               Term/Cap.html
Term::Complete          Term/Complete.html
Term::ReadLine          Term/ReadLine.html
Test::Harness           Test/Harness.html
Text::Abbrev            Text/Abbrev.html
Text::ParseWords        Text/ParseWords.html
Text::Soundex           Text/Soundex.html
Text::Tabs              Text/Tabs.html
Text::Wrap              Text/Wrap.html
Tie::Hash               Tie/Hash.html
Tie::RefHash            Tie/RefHash.html
Tie::Scalar             Tie/Scalar.html
Tie::SubstrHash         Tie/SubstrHash.html
Time::Local             Time/Local.html
Time::gmtime            Time/gmtime.html
Time::localtime         Time/localtime.html
Time::tm                Time/tm.html
User::grent             User/grent.html
User::pwent             User/pwent.html
AnyDBM_File             AnyDBM_File.html
AutoLoader              AutoLoader.html
AutoSplit               AutoSplit.html
Benchmark               Benchmark.html
CGI                     CGI.html
CPAN                    CPAN.html
Carp                    Carp.html
Cwd                     Cwd.html
DirHandle               DirHandle.html
English                 English.html
Env                     Env.html
Exporter                Exporter.html
FileCache               FileCache.html
FileHandle              FileHandle.html
FindBin                 FindBin.html
SelectSaver             SelectSaver.html
SelfLoader              SelfLoader.html
Shell                   Shell.html
Symbol                  Symbol.html
UNIVERSAL               UNIVERSAL.html
!endblock

P1: Extensions

!block references; root="ext/"; columns='REF:Reference'; wrap=4; sort=Reference
Reference              Jump
DB_File                DB_File/DB_File.html
DynaLoader             DynaLoader/DynaLoader.html
Fcntl                  Fcntl/Fcntl.html
GDBM_File              GDBM_File/GDBM_File.html
IO::File               IO/lib/IO/File.html
IO::Handle             IO/lib/IO/Handle.html
IO::Pipe               IO/lib/IO/Pipe.html
IO::Seekable           IO/lib/IO/Seekable.html
IO::Select             IO/lib/IO/Select.html
IO::Socket             IO/lib/IO/Socket.html
IO                     IO/IO.html
NDBM_File              NDBM_File/NDBM_File.html
ODBM_File              ODBM_File/ODBM_File.html
Opcode                 Opcode/Opcode.html
Opcode::Safe           Opcode/Safe.html
Opcode::ops            Opcode/ops.html
POSIX                  POSIX/POSIX.html
SDBM_File              SDBM_File/SDBM_File.html
Socket                 Socket/Socket.html
!endblock

P1: Utilities

!block references; root="utils/"; columns='REF:Reference'; wrap=4
Reference               Jump
c2ph                    c2ph.html
h2ph                    h2ph.html
h2xs                    h2xs.html
perlbug                 perlbug.html
perldoc                 perldoc.html
pl2pm                   pl2pm.html
splain                  splain.html
!endblock

P1: VMS Stuff

!block references; root="vms/"; columns='REF:Reference'; wrap=4
Reference               Jump
perlvms                 perlvms.html
ext/vmsish              ext/vmsish.html
ext/DCLsym              ext/DCLsym/DCLsym.html
ext/Filespec            ext/Filespec.html
ext/Stdio               ext/Stdio/Stdio.html
ext/XSSymSet            ext/XSSymSet.html
!endblock
           perlcall.html
perldata                perldata.html
perldebug               perldebug.html
perldelta               perldelta.html
perldiag                perldiag.html
perldsc                 perldsc.html
perlop          sdf-2.001/perllib/sdf/home/stdlib/004075500042570001753000000000000672243775100165545ustar00iancmtr00000400000236sdf-2.001/perllib/sdf/home/stdlib/rtf.sdn010064400042570001753000000011010636603141000200250ustar00iancmtr00000400000236# $Id$
#
# >>Title::     RTF Tuning
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 21-Feb-97 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# The {{stdlib/rtf.sdn}} module defines [[SDF]] configuration details for
# generating RTF files.
#
# >>Description::
#
# >>Limitations::
#

# Empty for now
sdf-2.001/perllib/sdf/home/stdlib/macros.sdm010064400042570001753000000123000672240132700205240ustar00iancmtr00000400000236# $Id$
#
# >>Title::     Macros Module
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{MOD:macros}} is the [[SDF]] module containing the built-in macros
# implemented in SDF.
# This module is {{2:always}} implicitly loaded (via {{FILE:kernel.sdm}}).
#
# >>Description::
#
# >>Limitations::
#

# build_title - build the title page and headers/footers for a document/manual
#
# The variables below are used.
#
# !block table
# Variable          Comments
# DOC_NAME          e.g. "SDF 1.003"
# DOC_TYPE          e.g. "User's Guide"
# DOC_STATUS        e.g. "Draft"
# DOC_AUTHOR        e.g. "Bill Bloggs"
# DOC_AUTHOR2
# DOC_AUTHOR3
# DOC_CODE          e.g. "MTR-SDF-0099"
# DOC_VERSION       e.g. "001"
# DOC_DISTRIBUTION  e.g. "MINCOM INTERNAL USE ONLY"
# DOC_PROJECT       e.g. "SIMPLE DOCUMENT FORMAT"
# DOC_APPROVE       e.g. "Project Leader"
# DOC_APPROVE2
# DOC_APPROVE3
# DOC_URL           e.g. "http://mtr.mincom.oz.au/sdf/doc/0002"
# DOC_OWNER         the person or company owning the copyright
# DOC_ID_SEP        the string within DOC_ID separating DOC_CODE & DOC_VERSION
# !endblock
#
# It also uses the macros below.
#
# !block table
# Macro             Comments
# DOC_RECIPIENTS    only used in project documents - a macro variable
#                   specifying a table of controlled copy recipients
# DOC_TRADEMARKS    only used in manuals & usually a macro variable
# !endblock
#

# Build a title page
!macro build_title

# If the code is set, but the name isn't, lookup the name
!if $var{'DOC_CODE'} ne '' && $var{'DOC_NAME'} eq ''
!define DOC_NAME $obj_short{'references',&Var('DOC_CODE'),'Document'}
!endif

# Build the document title
!if DOC_TYPE
!define DOC_TITLE join(' ', &Var('DOC_NAME'), &Var('DOC_TYPE'))
!else
!define DOC_TYPE  ''
!define DOC_TITLE DOC_NAME
!endif

# If not already set, lookup the document properties, if possible
!default DOC_CODE     $obj_long{'references',&Var('DOC_TITLE'),'Reference'}
!default DOC_VERSION  $obj_long{'references',&Var('DOC_TITLE'),'Version'} ||\
                      $obj_short{'references',&Var('DOC_CODE'),'Version'}
!default DOC_STATUS   $obj_long{'references',&Var('DOC_TITLE'),'Status'} ||\
                      $obj_short{'references',&Var('DOC_CODE'),'Status'}
!if !DOC_URL
!default DOC_URL      $obj_long{'references',&Var('DOC_TITLE'),'Jump'} ||\
                      $obj_short{'references',&Var('DOC_CODE'),'Jump'}
#!message "DOC_URL is $var{'DOC_URL'}."
!endif

# Provide defaults for key variables (to eliminate warnings)
!default DOC_DISTRIBUTION ''
!default DOC_PROJECT      ''
!default DOC_STATUS       ''
!default DOC_CODE         ''
!default DOC_OWNER        'The author'
!default DOC_ID_SEP       '.'

# Build the document identifier
!if DOC_VERSION
!define DOC_ID join($var{'DOC_ID_SEP'}, &Var('DOC_CODE'), &Var('DOC_VERSION'))
!else
!define DOC_ID DOC_CODE
!endif

# Format the copyright year
!define _DOC_YEAR &FormatTime('$year', 'DOC_START')

# include the cover (unless using this file as a book config. file)
!if !DOC_INBOOK
    !on paragraph '[HAP]1'; noevents_in_title; $attr{'noevents'} = 1
    !if   $macro{"build_" . $var{'OPT_DRIVER'} . "_cover"}
        !insert "build_" . $var{'OPT_DRIVER'} . "_cover"
    !elsif   $macro{"build_" . $var{'DOC_COVER'} . "_cover"}
        !insert "build_" . $var{'DOC_COVER'} . "_cover"
    !elsif DOC_COVER
        !message "unable to build cover '$var{'DOC_COVER'}'"; "warning"
    !endif
    !off paragraph noevents_in_title
!endif
!endmacro

# If we're building sub-topics for HTML, do nothing for build_title
!if HTML_SUBTOPICS_MODE
!macro build_title
!endmacro
!endif


# slide_down & slide_up - adjust heading levels
!macro slide_down
!on paragraph '[HAP]\-?\d';SLIDE_DOWN; $style =~ /^(\w)/; $style = $1 . ($' + 1)
!endmacro
!macro slide_up
!on paragraph '[HAP]\-?\d';SLIDE_UP; $style =~ /^(\w)/; $style = $1 . ($' - 1)
!endmacro

# end_topic - mark the end of a topic
!macro end_topic
!endmacro

######## COMPONENTS & COVERS #########

# Init the component macros (these can be used to initialise
# and/or finalise things on a per component basis)
!macro DOC_COMPONENT_BEGIN
!endmacro
!macro DOC_COMPONENT_END
!endmacro

# This macro is used to initialise a component cover page
!macro DOC_COMPONENT_COVER_BEGIN
!default DOC_COMPONENT_LOGO $var{'DOC_LOGO'}
!if DOC_COMPONENT_LOGO
    N[top=Right;wide;sp_after=100]
    {{IMPORT[align=Left;wrap_text][[DOC_COMPONENT_LOGO]]}}
!else
    N[top=Right;wide;sp_after=100]
!endif
!endmacro

# This macro is used to finalise a component cover page
!macro DOC_COMPONENT_COVER_END
PB:
!endmacro

######## Backwards compatibility stuff #########

# Old macros
!define BUILD_TITLE "build_title"
!define SLIDE_UP    "slide_up"
!define SLIDE_DOWN  "slide_down"
!define END_TOPIC   "end_topic"

!macro SDF_DEFAULT_END
!use sdgmacs
!SDG_END
!endmacro
!macro SDF_DESCRIPTION_PRE
!use sdgmacs
!SDG_DESCRIPTION_PRE
!endmacro
!macro SDF_DESCRIPTION_POST
!use sdgmacs
!SDG_DESCRIPTION_POST
!endmacro
sdf-2.001/perllib/sdf/home/stdlib/module.sdp010064400042570001753000000051610632217707600205460ustar00iancmtr00000400000236# $Id$
#
# >>Title::     Module Filter Plug-In
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 14-May-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# This plug-in provides an [[SDF]] filter called {{module}} which
# generates reference documentation for an [[SDF]] module.
#
# >>Description::
#
# >>Limitations::

# >>Resources::
#
# >>Implementation::
#


# This is the filter which does the work
@_module_FilterParams = ();
sub module_Filter {
    local(*text, %param) = @_;
#   local();

    # Build the document after the module has been loaded
    push(@text, "!build_module_reference");
}


# This macro gets called at the end of the module
sub build_module_reference_Macro {
    return (split("\n", <>Title::     HLP Tuning
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# The {{stdlib/hlp.sdn}} module defines [[SDF]] configuration details for
# generating [[Windows]] help files.
#
# >>Description::
#
# >>Limitations::
#

# This is needed for building HPJ files on Unix
!default SDF_DOSHOME        SDF_HOME
!define  HLP_OPTIONS_ROOT   "."
!block end
!export HLP_OPTIONS_ROOT
!endblock

# Controlling options
!block variables; family="HLP_OPTIONS"; export
Name            Type        Rule
BMROOT          string
BUILD           string
CITATION        string
COMPRESS        string
CONTENTS        string
COPYRIGHT       string
ERRORLOG        boolean
FORCEFONT       boolean
ICON            string
LANGUAGE        string
MAPFONTSIZE     string
MULTIKEY        string
OLDKEYPHRASE    string
OPTCDROM        string
REPORT          string
ROOT            string
TITLE           string
WARNING         string
!endblock

# Things at the paragraph level for doing help ...
!block paraattrs; family="hlp"
Name:Type:Rule
context:integer:
header:boolean:
topic:string:
window:boolean:
endwindow:boolean:
!endblock

# Things at the phrase level for doing help ...
!block phraseattrs; family="hlp"
Name:Type:Rule
popup:string:
!endblock

# Default build_title output
!macro build_hlp_cover
        !default DOC_TOC 2
        !default DOC_TOC_TITLE DOC_TITLE
        !if DOC_LOGO
            !define DOC_TOC_GRAPHIC $var{'DOC_LOGO'} . ".bmp"
        !endif
!endmacro
sdf-2.001/perllib/sdf/home/stdlib/misc.sdm010064400042570001753000000067640613735546400202260ustar00iancmtr00000400000236# $Id$
#
# >>Title::     Miscellaneous Module
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 02-Apr-96 tjh     SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
#
# >>Description::
#
# >>Limitations::
#

!define TEST "0"

# backwards compatible stuff to get things going quickly!
!define SQUISH_ON  "squish on"
!define SQUISH_OFF "squish off"
!define KEEP_ON    "keep on"
!define KEEP_OFF   "keep off"
!define HYPHEN_ON  "hyphen on"
!define HYPHEN_OFF "hyphen off"

!block script

@_squish_MacroArgs = (
    'Name       Type        Default     Rule',
    'state      symbol      toggle      ',
    'params     rest        _NULL_          ',
);
sub squish_Macro {
    local(%arg) = @_;
    local($state,$paratags);
    local(@text);

    $state=$arg{'state'};
    $paratags='';

    # Ian is certainly going to change the following code --tjh

    # I want to support the following (and probably allow nesting!)
    # !squish on       <= default of just lists
    # !squish on ; H1  <= just H1
    # !squish on ;     <= all paragraphs

    if ($arg{'params'}) {
      if ( $arg{'params'} =~ /;/ ) {
	  ($crap,$paratags) = split(/\s*;\s*/,$arg{'params'});
      } else {
	  $paratags = 'LU\d|L\d';
      }
    } else {
      $paratags = 'LU\d|L\d';
    }

    #print STDERR "SQUISH STATE=\"$state\" PARA=\"$paratags\" ARGS" . $arg{'params'} . "\n";

    # add in the macro stuff here ...
    if ($state eq 'on') {
	push(@text,"!on paragraph '$paratags' ; __squish_filter; \$attr{'mif.SpAfter'} = '0 pt'; \$attr{'mif.SpBefore'} = '0 pt'");
    } elsif ($state eq 'off') {
	push(@text,'!off paragraph __squish_filter');
    } else {
	&'AppMsg("error", "squish \"$state\" not yet implemented");
	return ();
    }

    #print STDERR "Squish:\n" . join("\n",@text) . "\n";

    return (@text);
}

@_keep_MacroArgs = (
    'Name       Type        Default     Rule',
    'state      symbol      toggle      '
);
sub keep_Macro {
    local(%arg) = @_;
    local($state);
    local(@text);

    $state=$arg{'state'};

    # add in the macro stuff here ...
    if ($state eq 'on') {
	push(@text,'!on paragraph ; __keep_filter; $attr{"mif.WithNext"}="1"');
    } elsif ($state eq 'off') {
	push(@text,'!off paragraph __keep_filter');
    } else {
	&'AppMsg("error", "keep \"$state\" not yet implemented");
	return ();
    }
    return (@text);
}

@_hyphen_MacroArgs = (
    'Name       Type        Default     Rule',
    'state      symbol      toggle      '
);
sub hyphen_Macro {
    local(%arg) = @_;
    local($state);
    local(@text);

    $state=$arg{'state'};

    # add in the macro stuff here ...
    if ($state eq 'off') {
        push(@text,'!on paragraph ; __hyphen_filter; $attr{"mif.Hyphenate"}="0"; ');
    } elsif ($state eq 'on') {
	push(@text,'!off paragraph __hyphen_filter');
    } else {
	&'AppMsg("error", "hyphen \"$state\" not yet implemented");
	return ();
    }
    return (@text);
}

!endblock


!if TEST

H1: hi there

* asd as dasd
* asd as d asd

!squish on 
Bulletted list
* alkasjdklasjdla
* asldkjaslkdjasd
!squish off

!squish on ; H1
H1: JUST H1's squished

H2: not squished
!squish off

!squish on ; 
H1: squished
Everything squished

* asdasd
* asdasdasdasd
!squish off


!endif

sdf-2.001/perllib/sdf/home/stdlib/A4.fm4010064400042570001753000000240000613013434600174040ustar00iancmtr00000400000236
	

AaÿSxåæææççèèéX±X±X±X±«V@SF…Iã¼vê,XFݺFݺFݺFݺX±ÌÌÌÌÌÌff@d'!Footnote
TableFootnoted* à* à.\t.\t/ - Ð Ñ:;,.É!?,	^(	)	^*TOCHeading1Heading2		EquationVariables	vQ%=]R=<$lastpagenum>><$daynum> <$monthname> <$year>?"<$daynum>/<$monthnum>/<$shortyear>@:<$daynum> <$monthname> <$year> <$hour>:<$minute00> <$ampm>A"<$daynum>/<$monthnum>/<$shortyear>B<$daynum> <$monthname> <$year>C"<$daynum>/<$monthnum>/<$shortyear>D	<$fullfilename>E
<$filename>F<$paratext[Title]>G<$paratext[Heading1]>H
<$curpagenum>0K>I

<$marker1>J
<$marker2>K (Continued)L+ (Sheet <$tblsheetnum> of <$tblsheetcount>)MHeading & Page Ò<$paratext>Ó on page<$pagenum>ÌÌNPagepage<$pagenum>dOSee Heading & Page%See Ò<$paratext>Ó on page<$pagenum>. P	Table All7Table<$paranumonly>, Ò<$paratext>,Ó on page<$pagenum>QTable Number & Page'Table<$paranumonly> on page<$pagenum>É	ÉlÊ
[
[AlË
\
\AlÌ
]
]lÍ
^
^lÎ
_
_=lÏ
`
`num<$lÐ
a
a$daAm-m-A.†rC/†:E0ˆtG1‡<I2ˆ0K3‡M4†$
I
™
YSF…Iã¼qÁ
I
­<
`
[åum<$SF…Iã¼qÂ
J
­a
^
\æ>SF…Iã¼qÃ
K
­H
L
WçagFݺD‹3Rë`@qÄ
L
®
M
KrFݺD‹3Rë`@Fݺ"Fݺ"àFootnoteheFݺq$I@`@qÅ
M
®
L
N
K Fݺq$I@`@FݺyãÅFݺyãÅàSingle LineeFݺ'¯^µjÓ,XqÆ
N
¯
M
P
Ke
O
OeFootnote. û÷»uÅ
O
°
Npû÷»ue<agû÷–.\t. ,Xæf™E,X.æf 	Numbered1.\tNumbered. X±,X,Xæf™€
™X±. 
TableFootnote. æf™T	
TableTitleT:Table : . æf™‚P	TitleBody. æf™ƒÜT	
TableTitleT:Table : . æf™„ÙCellHeading. æf™…ÙCellBody. æf™†ÙBody. À@‡Ú
âňÅ‹Header. À@ˆÚ
âňÅ‹Footer. ÙéÛzÙVÓÙ
zÙVÓÚîãøÜ	€Þ	Emphasis€ß	 EquationVariables©­à	
­
½
³
­
®
¯ €
°f€
±Ù
²¡±¦€¡Thin¢Medium€£Double¤Thick@¥	Very ThinAQA¡¡¡¡¡¡¡¡¡£ƒFݺ„…„Fݺ„…„Fݺ„…„Fݺ„…„Fݺ„…„Format A	¡¢¡¡¡¡¡¢ƒFݺ„…„Fݺ„…„Fݺ„…„Fݺ„…„Fݺ„…„éFormat By‰yÝíÝeufeComment!d BlackT!€WhiteddARedddGreen dd	BluedCyandMagentad	YellowTimes-Roman
Times-BoldHelvetica-BoldTimes	Helvetica	Regular¦Regular	BoldRegular¢ItalicDâ#µÙÞ‰
ï…owaÑ.×CR8"GiÝÏ)º3næ
sdf-2.001/perllib/sdf/home/stdlib/A4.fm5010064400042570001753000000540000614327656400174250ustar00iancmtr00000400000236
	

AaÿZ©-../59::HH	$	SKÆIå` SKÆIå`^)U×HHÌÌÌÌÌÌff@€€€ÿö
ø
ø
øÿÿÿ

øÿÿÿÿd'Y	ÿfn_Footnote
TableFootnote* à* à.  .  - Ð Ñ:;,.É!?:`x	`~LOT
TableTitleLOFFigureTOC1Heading2Heading3Heading		EquationVariables3mím:£™¤€™¦š§‚š©ƒ›ª„›¬…œ­†œ°‡±ˆ³‰ž´Šž¶‹Ÿ·ŒŸº 0—»Ž üqŒ½¡VIÙ¾¡Ð6ƒÀ‘¢RÁ’¢£ÁÄ“£	q-Å”£Ç•¤e 5È–¤	
Ê—¥Ë˜¥©Ï™¦-.К¦::Ò›§Óœ§	Õ¨Öž¨ ØŸ©Ù ©Ü¡ª^)Ý¢ªHߣ«ÌÌफ@⥬㦬槭稭驮ꪮø쫯ÿí¬¯øð­°ÿñ®°dó¯±Yô°±ö±²	ÿ÷²²notû³³Fooü´³ àþµ´ÿ¶´  ·µÐ Ѹµ	É	5uR5™“`6š©7›Ta8œ¬9ŸFi:žž;Ÿ­1Hdi< ªing3H=¡¥>¢£?£«@¤¦A¥¤B¦¬C§D¨“uaE©©bleFª­G«ž3H¬Ÿ£™I­£€™J®¥§K¯ª©›L°¤„›M±¦­N²«°O³ ˆP´¡´Qµ¢¶ý	ý…µ³.…
COMPANY_ADDR1 'Corner Wyandra Street & Skyring Terrace†
COMPANY_ADDR2-Teneriffe QLD 4005 5‡
COMPANY_ADDR3¥	Australia¥©ˆ
COMPANY_ADDR4¦‰
COMPANY_ADDR5§P.O. Box 72Š
COMPANY_ADDR6©Stones Corner QLD 4120)‹COMPANY_CODEA.C.N. 010 087 608ŒCOMPANY_FAX+61 7 3303 3232ç­COMPANY_NAMEMincom Pty LtdŽ
COMPANY_PHONEð+61 7 3303 3333<$daynum> <$monthname> <$year>"<$daynum>/<$monthnum>/<$shortyear>‘<$daynum> <$monthname> <$year>’"<$daynum>/<$monthnum>/<$shortyear>“
<$curpagenum>¬”DOC_LOGOsdf1s•Pagepage <$pagenum>Hdi–Heading & Page Ò<$paratext>Ó on page<$pagenum>—Section & Page%section<$paranum> on page<$pagenum>§˜See Heading & Page%See Ò<$paratext>Ó on page<$pagenum>.™Table & Page7Table<$paranumonly>, Ò<$paratext>,Ó on page<$pagenum>›š	DOC_TITLESDF Getting StartedO›	<$fullfilename>´œ
<$filename>ý…Footer1
Copyright 1996, Mincom Pty LtdžFooter2 acŸFooter3PMTR-SDF-0001.001 (Draft)05 FooterAPAD¡FooterBi26 April 1996, 14:10.46¦¢FooterC_5§£Header1SIMPLE DOCUMENT FORMAT¤Header2L20¥Header3PCO¦Header40 6§5<$daynum> <$monthname> <$year> <$hour24>:<$minute00> E¨<$daynum> <$monthname> <$year>©<$lastpagenum>ªSDF$nt«Getting Started"da¬
26 April 1996, 14:10.46­	gs_sdf.pso® (Continued)"¯+ (Sheet <$tblsheetnum> of <$tblsheetcount>)gum°
Figure & Page8Figure<$paranumonly>, Ò<$paratext>,Ó on page<$pagenum>±TOCt'<$paranumonly>\t<$paratext>\t<$pagenum> ge²HELPTOCa<$paratext>eÑÙ
ÑÈÈ‘ArexÒËËÓÍÍÔÑÑ‘ApenÕÔÔÖÖÖ×ÛÛ‘Aý…ØÝÝåCC‘TOCæGGIXDrçKKLOFèOOLOTéSS‘Ar¥¥ D£Ö@MfØAîÙ?ûÚ@ÛAmntÜBaou$ÝCt5êHa<$;ëK<EìRanuIíSntHð?tarªñ@
 ApòA16ó@	.pôAin6ISh7Je o<	Lt)g=
Mi P>Nean?O$xt@
PnuAQOpa%ùBt‘Ñ“9$pSKÆIå`A‘õÈÏ-ÈSKÆIå`ç’õÑØ.Æ?EKƹ»¸þžõQÆ?EKƹ»¸SÛ`ù$Æ^)EKÆ•å`ÇÇ÷‘TOÆ^)EKÆ•å`GÈeð$H^)ÃKÆ•å`wÈøÉ‘¥¥H^)ÃKÆ•å`l	ÇÇÑIKÆÀ¡Ë	ÉùÈË‘BIKÆÀ¡ËÝCt	í‘IKÆIKÆÂËÊ÷‘aIKÆÂÿþntñ@
ËAªªUUmÖ3YPage #€ of 1‚ƒCopyright 1996, Mincom Pty Ltd„…Running H/F 3†
MªªUUmñ3N@‡MTR-SDF-0001.001 (Draft)ˆ‰Š‹Running H/F 4ŒIKÆÂxËøÉÍ‘Æå`IKÆÂl	ÊÊÒÈIKÆ-ÂÎÌ÷‘IKÆ-ÂÿþþͪªUUmØRBRunning H/F 1Ž3‘SIMPLE DOCUMENT FORMAT’
ªªUUmò3(“Running H/F 2”•–—˜TOIKÆ-ÂyÍøËΑIKÆ-Âl	ÌÌÓ^)IKÆ$À¡ËÎùÍÏ‘)IKÆ$À¡Ël		í‘$IKÆ$H›M*®À¡ËÏùΑùËH›M*®À¡ËIKƦfM*®H›M*®Æ^)EKÆ•å`ÓÐ÷’÷Æ^)EKÆ•å`Ñ
`Ù$ªH^)ÃKÆ•å`zÑøÒ’CoH^)ÃKÆ•å`l	ÐÐÔªªI^5À¡ËÒùÑÔ’I^5À¡Ëng F I^5
HÂ×Ó÷’ÆHÂÿþ	ÒÈÔªªªªUUlÚ3Y™Running H/F 3š›Copyright 1996, Mincom Pty LtdœPage #ž of Ÿ1 
ªª©ªªUUló3Ru@¡Running H/F 4¢£¤¥MTR-SDF-0001.001 (Draft)¦ªªHÂ{ÔøÒÖ’—HÂl	ÓÓÕH-ÂÚÕ÷’ÌH-Âÿþ)ÖªªªªUUhÛ3›B§SIMPLE DOCUMENT FORMAT¨©ªR«Running H/F 1¬
ª©ªªUUhô3(­®¯°±Running H/F 2²H-Â|ÖøÔ×’H-Âl	ÕÕÖ^)I^5$À¡Ë×ùÖØ’)I^5$À¡Ël	I^5$
$J¥`M*®À¡ËØù×’ùÔJ¥`M*®À¡ËI^5J¥`M*®G+M*®SKÆIå`Ùõ÷ÛÝ/Æ?EKƹ»¸àÚ÷ÙÆ?EKƹ»¸ªªg H/F 3Ûgh`Ü$P H?ÃKƹ»¸}ÛøÝÙuH?ÃKƹ»¸l	ÚÚתªHŸÀ¡ÊÒñãÜ÷Ù—HŸÀ¡ÊÒñ	ÿÿÓÓݪªªªUUhÝS:³´3Rµ26 April 1996, 14:10.46¶·¸HŸÀ¡ÊÒñ~ÝøÛÙUÛHŸÀ¡ÊÒñl	ÜÜØ H/SKÆIå`%4õ5@5H$bN/™&5ø64H$bN/™H-H-QFootnoteÕH1ÿë¶

'6ø58477Footnoteƒÿð›7ù6ƒÿðÀ¡ËƒÿðJ´NrÁ¸KV™)8ÿ694J´NrÁ¸KV™J´N{_jJ´N{_jQ
TableFootnoteÆHé¶
ÿõ*9ø8;4KÆ::
TableFootnoteÿð€~Ÿ:ù9P ÿð€~}ÿð€ƒÿð€H·ø,;ú9=4<<	TableLineñ$
 
¢<;ÊÒñ$
 
$
Ä

H£.ÂÏ
,Ì.=;>4H£.ÂÏ
,ÌH«H«*	TableLineFULéÕlø/>ú=@4??CorrLine	ÿÿª©
ÄUa¦?>Æå`ÿÿª©
ÄUaÿÿª©
Ä

EÿõÕ*,ˆ
,Ì1@>4&EÿõÕ*,ˆ
,ÌEÿõÜÿëEÿõÜÿë*CorrLineSKÆIå`2Aõ'CD6l °Ø‹CøDAðl °Øl	~~ålâÑ–³,
,Ì4DøCAlâÑ–³,
,ÌlÈ´lÈ´*Table of Contents Specification¶
SKÆIå`8Eõ:GH7tnel Œu[F÷EP l ŒuV}øG=eëV<	Level2IX
e	V	Level1IX
e
V 1, 2Ð3
ÒñeV$<$symbols><$numerics><$alphabetics>
eWLSymbols[\ ];Numerics[0];A;B;C;D;E;F;G;H;I;J;K;L;M;N;O;P;Q;R;S;T;U;V;W;X;Y;Z
/e
V<$pagenum>
??e$Coil ŒuŒGøHEÆl Œul	FFælÕ[þ1
,Ì:HøGEÌÿõlÕ[þ1
,Ìlv¸lv¸*Index SpecificationSKÆIå`BIõKL8øDl °Ø`J÷I	l °Ø~4Keì$"<$paranum><$paratext><$pagenum>l °ØKøLIõl °Øl	JJçulâц3
,ÌDLøKIlâц3
,ÌlÈ´lÈ´*List of Figures SpecificationSKÆIå`FMõ	OP9
l °ØeN÷M>nul °Ømbols[\ OA;eí$O;"<$paranum><$paratext><$pagenum>l °ØŽOøPMoil °Øl	NNèulâÑK=
,ÌHPøOMlâÑK=
,ÌlÈ´lÈ´*List of Tables SpecificationSKÆIå`‹QõSS:H?ÃKƹ»¸SøQH?ÃKƹ»¸l	žžé~l °Ø‡~õAl °Ø)ÿüìext><$pCeê'"<$paranum><$paratext><$pagenum>
UTªªe*"<$paranum><$paratext><$pagenum>
UTªªe*"<$paranum><$paratext><$pagenum>-M0	SKÆIå`-‘ifLeftSKÆIå`./’RightSKÆIå`/.ÙblanklSKÆIå`564	ReferenceSKÆIå`657ATOCSKÆIå`768EIXSKÆIå`879I<$LOF>$pSKÆIå`98MLOTSKÆIå`:Qiblank½m½æf™ÈYb0_Bodye. À@ï
Y»¸Ø  Footer. À@
YØ $Â> pHeader. æf™7(Y	‘l t´Æ `ü D Œ ÆCellHeading/. anæf™8*YlI $´> pü` D8 MŒ CellBody. Q2ff33æf™9#TY	
TableTitleT:TABLE . . æf™:J
Y	CellHeading. æf™;2
YCellBody. Vff+33æf™<#TY	
TableTitleT:TABLE . . Vff+33æf™=KT
Y	
TableTitleT:TABLE . . æf™?$Yf0_FirstBody. À@@3
YØA  Â  Footer. À@A3
YØ Â Header. æf™B$YBody. À@C3
Y. Ø3 À¡Ê Footer. æf™H'Y	$ Âf. 
h1_HeadingTOC. æf™I*Y@6 Â. 
h2_HeadingTOC. æf™J*YH Â. 
h3_HeadingTOC. 	À@KV	YLevel2IX. $À@LV	YLevel1IX. À@MV	YSpecIX. À@NV	Y
SortSpecIX. æf
À@OW	Y	
GroupTitlesIX. À@PV	YIndexIX. À@Q$Y	Paragraph. $R$YH °.ft_FigureTitleLOF. $S$YH °.tt_TableTitleLOT. !a!)ÕÞ#Y	úÚÜ$Yž['Y	ž[(Y	yc–>*Y
úÚÜ2Y
úÚÜ3Y
ž[JY	
)ÕÞKY	yc–>QY
)ÕÞRY	
)ÕÞSY	Bold	úÚÜVY	)ÕÞWY	õöõ÷øY@ùY€úY@ÿY33Y33Yéùî€éY ThinêYleLMedium€ëYDoubleìYThick@íY	Very ThinAQAM]M
$Nííííííí9YYY787H787Ø787Shadel‹Oé<YYY6:;:6:;:6:;:Format Al‹P<YYY6:;:6:;:6:;:Format B'™™Qéêéêéííê=YYY6:;:Ñœ:;:
Format IC1$Rííííííí9YYY787H787Ø787Shade1Y$S9YYYY787H787LØ787PlainY$Tííííííí9YYYM787H787Ø787Columnsí$Uééééééé9YYY787‹H787Ø787Shade2$Vííííííííë9YYYt787‹H787Ø787Grid$Wííííé9YYYo787H787Ø787Rowsy‰yÝýݱÁ²±[Comment™ù¶±™5€´š6‚˜›7ƒ„훜8…†9}9‡ˆ¨ž:‰Š8½Ÿ;‹Œu <ŽShe1a¡=~¢>‘’‡£?“”k¤@•–9Yv¥A—˜Yð¦B™šó§C›œö¨DžYù©EŸ ýªF¡¢«G£¤ííq¬H¥¦Y­I§¨M®J©ª
¯K«¬8°L­®±M¯°²N±²³O³´é´Pµ¶"µQ·¸Yib	‹d YBlackT!ZWhiteddA[íRedíídd\Greentdd	]8Blued^Cyand_Magentaíd	`Yellowda	WPGColor0%Times-RomanHelvetica-Bold	Helvetica
Times-BoldTimes„	Helveticaœ
RegularRegular	BoldRegularGýHd›Æ¹6<’”{ŽDÿ–4ª<žüqŒÞš£mv—SVIÙ΄BÀ…psÐ6ƒ`½¸Il¼GRpmw’põ]:fðe–L˜eîÄzc°sdf-2.001/perllib/sdf/home/stdlib/homepage.sdm010064400042570001753000000016370670452660000210420ustar00iancmtr00000400000236# This module provides some useful things for building home pages

# The homepage_table filter formats the main body of the page
!on filter 'homepage_table';; $name='table'; \
       $params='noheadings; style="plain"; cellpadding=0; cellspacing=0;' . \
       'colaligns="RLL"; coltags="B"; colvaligns="Top"' . \
       $params

# The homepage_title macro builds a nice looking title
!block script
@_homepage_title_MacroArgs = (
    'Name       Type        Default     Rule',
    'title      string      _NULL_',
);
sub homepage_title_Macro {
    local(%arg) = @_;
    local(@text);

    # Get the title
    my $title = $arg{'title'} || $var{'HTML_TITLE'};

    # Generate the text and return it
    @text = ("{{INLINE:\n");
    for $word (split(/\s+/, $title)) {
        $word =~ s/(.)/$1 /g;
        push(@text, "$word
      \n");
    }
    push(@text, '      }}');
    return @text;
}
!endblock
sdf-2.001/perllib/sdf/home/stdlib/settings.sdm010064400042570001753000000011270614603514200211030ustar00iancmtr00000400000236# $Id$
#
# >>Title::     Settings Module
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 09-May-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{MOD:settings}} is a dummy module which users can override to
# tune [[HTML]] colours, page headers, footers, etc.
#
# >>Description::
#
# >>Limitations::
#

# do nothing
sdf-2.001/perllib/sdf/home/stdlib/all.sdg010075500042570001753000000017650672210172500200210ustar00iancmtr00000400000236# $Id$
#
# >>Title::     All Documentation SDG Report
#
# >>Copyright::
# Copyright (c) 1992-1999, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 13-May-99 ianc    Initial creation
# -----------------------------------------------------------------------
#
# >>Purpose::
# This report is used to extract and format all sections
# of SDF-style embedded documentation.
#
# >>Description::
# 
# >>Limitations::
#
Key             Format
-               "!use 'sdgmacs'\n!SDG_BEGIN\n"
Title           "H1[id=\"$short\"] $short - $data\n\n"
Purpose         "H2: $key\n\n$data\n\n"
Interface       "H2: $key\n\n$data\n\n"
-               "!SDG_DESCRIPTION_PRE\n"
Description     "H2: $key\n\n$data\n\n"
-               "!SDG_DESCRIPTION_POST\n"
*               "H2: $key\n\n$data\n\n"
-               "!SDG_END\n"
sdf-2.001/perllib/sdf/home/stdlib/sgml.sdn010064400042570001753000000056560637532536000202310ustar00iancmtr00000400000236# $Id$
#
# >>Title::     SGML Tuning
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 14-Aug-97 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# The {{stdlib/sgml.sdn}} module defines [[SDF]] configuration details for
# generating [[SGML]] files.
#
# >>Description::
#
# >>Limitations::
#

# Make SGML a restricted family of variables
!restrict 'SGML'

# Declare SGML document variables
!block variables; family="SGML"; export
Name                        Type            Rule
DTD                         string          
!endblock

# Declare SGML paragraph attributes
!block paraattrs; family="sgml"
Name                Type            Rule
!endblock

# Declare SGML phrase attributes
!block phraseattrs; family="sgml"
Name            Type            Rule
!endblock

# Declare SGML table parameters
!block tableparams; family="sgml"
Name            Type            Rule
!endblock

# Declare SGML row parameters
!block rowparams; family="sgml"
Name            Type            Rule
!endblock

# Declare SGML cell parameters
!block cellparams; family="sgml"
Name                Type            Rule
!endblock

# Define paragraph styles (default is P if not known and not below)
!block parastyles
Name        To                      Attributes
Line        HR
PB          HR
Addr        ADDRESS
Sign        ADDRESS
TITLE       title
AUTHOR      author
DATE        date
!endblock

# Mapping of phrase styles (default is Name if not below)
# The SDF_* one will be ignored - this seems better than "UNKNOWN"
!block phrasestyles
Name    To
A       SDF_ASIS
B       bf
I       em
N       SDF_NORMAL
U       u
EX      tt
1       =I
2       =B
3       =U
SUB     sub
SUP     sup
ST      bf
Y       =ST
!endblock


# Mapping tables for attribute/parameter values
!block script
!endblock

# Mapping of paragraph attributes
!block paraattrs
Name        To          Map         Attributes
align       align
!endblock

# Mapping of phrase attributes
!block phraseattrs
Name        To          Map         Attributes
family
size
bold
italics
underline
changed
color
!endblock

# Mapping of cell parameters
!block cellparams
Name        To          Map         Parameters
!endblock

# ignore Page-breaks in sgml
!on paragraph 'PB';; $style = 'N'

# Default build_title output
!macro build_sgml_cover
    !default DOC_TOC 2
    TITLE: [[DOC_TITLE]]
    !if DOC_AUTHOR
        AUTHOR: [[join(", ", grep(/\w/, &Var('DOC_AUTHOR'), &Var('DOC_AUTHOR2'), &Var('DOC_AUTHOR3')))]]
    !endif
    DATE: [[DATE:DOC_MODIFIED]]

    # Add the table of contents
    !block inline; target='sgml'; expand

    !if DOC_TOC

    !endif
    !if DOC_LOF

    !endif
    !if DOC_LOT

    !endif

    !endblock
!endmacro
tdlib/sgml.sdn}} module defines [[SDF]] configuration details for
# generating [[Ssdf-2.001/perllib/sdf/home/stdlib/simple.sdp010064400042570001753000000056770633202241400205500ustar00iancmtr00000400000236# $Id$
#
# >>Title::     Simple Filter Plug-In
#
# >>Copyright::
# Copyright (c) 1996-1997, Tim Hudson (tjh@mincom.com)
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 04-Jan-97 tjh		exec param of simple now returns modified $line
# 01-Jan-97 tjh		tidied up a lot of things and added "exec" option
# 19-Jun-96 tjh		original coding
# -----------------------------------------------------------------------
#
# >>Purpose::
#
# >>Description::
# This adds the "simple" filter with parameters:
#
# * pre - inserted {{before}} the block
# * post - inserted {{after}} the block
# * exec - executed for each line with $line containing the text line.
#
# >>Limitations::
#

$simple_debug=0;

# simple filter ... filter that allows simple prepending and
#                   appending of text to a block using the
#                   event processing mechanism
#
#!on filter "testsimple";; \
#    $name='simple'; \
#    $params.='pre="Hi there#Tim";post="post"';
#
#!block testsimple
#This is normal text
#!endblock
#
#!on filter "product_defines";; \
#        $name='simple'; \
#        $params.=';pre="!block products data#Name:Jump"'; \
#        $params.=';exec="&AddProduct(\$line)"'; \
#        $params.=';post="!endblock#!DefineProducts"'
#

@_simple_FilterParams = (
    'Name       Type        Rule',
    'pre        string',
    'post       string',
    'exec       string',
);

push(@_simple_FilterParams,@_table_FilterParams);

sub simple_Filter {
    local(*text, %param) = @_;
    local($style, $line, $pre, $post, $other_params);

    if ($simple_debug) {
	for $key (keys %param) {
	    print STDERR "SIMPLE: param{$key}=\"$param{$key}\"\n";
	}
    }

    $pre=$param{"pre"};
    $post=$param{"post"};

    # allow for being able to process lines of text if the
    # user has chosen to have an exec routine
    if (defined $param{"exec"}) {
	print STDERR "EXEC:$param{'exec'}\n" if ($simple_debug);
	for $line (@text) {
	    print STDERR "LINE-IN:$line\n" if ($simple_debug);
	    $line = eval $param{'exec'};
	    print STDERR "LINE-OUT:$line\n" if ($simple_debug);
	}
    }

    delete $param{"pre"};
    delete $param{"post"};
    delete $param{"exec"};

    if ($simple_debug) {
	for $key (keys %param) {
	    print STDERR "SIMPLE: param{$key}=\"$param{$key}\"\n";
	}
    }

    $other_params='';
    for $key (keys %param) {
    	$other_params .= "$key=\"" . $param{$key} . "\"";
    }

    if ($simple_debug) {
    	print STDERR "other_params=$other_params\n";
    }

    $pre =~ s//;/g;
    $pre =~ s//$other_params/g;
    $post =~ s//;/g;
    $post =~ s//$other_params/g;

    # slip some text at the beginning 
    unshift(@text,split(/#/,$pre));

    # slip some text at the end
    push(@text,split(/#/,$post));

    print STDERR join("\n",@text) . "\n" if ($simple_debug);
}

# package return value
1;
sdf-2.001/perllib/sdf/home/stdlib/html.sdn010064400042570001753000000225000672240155300202110ustar00iancmtr00000400000236# $Id$
#
# >>Title::     HTML Tuning
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 26-Apr-99 ianc    Added HTML_OLD_FOOTERS
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# The {{stdlib/html.sdn}} module defines [[SDF]] configuration details for
# generating [[HTML]] files.
#
# >>Description::
#
# >>Limitations::
#

# Make HTML a restricted family of variables
!restrict 'HTML'

# Declare HTML document variables
!block variables; family="HTML"; export
Name                        Type            Rule
TITLE                       string
BG_IMAGE                    string
BG_FIXED                    boolean
BG_COLOR                    string
TEXT_COLOR                  string
LINK_COLOR                  string
VLINK_COLOR                 string
CHANGED_COLOR               string
PRE_HEADER                  string
POST_FOOTER                 string

# Section separator stuff
SECTION_LEVEL               integer
PRE_SECTION                 string

# header/footer URLs
URL_HOME                    string
URL_CATALOG                 string
URL_SEARCH                  string

# Navigation text
TEXT_CONTENTS               string
TEXT_PARENT                 string
TEXT_PREVIOUS               string
TEXT_NEXT                   string
TEXT_HOME                   string
TEXT_CATALOG                string
TEXT_SEARCH                 string

# Stuff for building topics
TOPIC                       string
SDT                         string
TOPIC_PATTERN               string

# For now, this is the way to tune table unit widths
TABLE_UNIT                  number
!endblock

# Declare HTML paragraph attributes
!block paraattrs; family="html"
Name                Type            Rule
!endblock

# Declare HTML phrase attributes
!block phraseattrs; family="html"
Name            Type            Rule
!endblock

# Declare HTML table parameters
!block tableparams; family="html"
Name            Type            Rule
!endblock

# Declare HTML row parameters
!block rowparams; family="html"
Name            Type            Rule
!endblock

# Declare HTML cell parameters
!block cellparams; family="html"
Name                Type            Rule
!endblock

# Define paragraph styles (default is P if not known and not below)
!block parastyles
Name        To                      Attributes
Line        HR
PB          HR
Addr        ADDRESS
Sign        ADDRESS
TITLE       TITLE
!endblock

# Mapping of phrase styles (default is Name if not below)
# The SDF_* one will be ignored - this seems better than "UNKNOWN"
!block phrasestyles
Name    To
A       SDF_ASIS
B       B
I       I
N       SDF_NORMAL
U       U
EX      TT
FILE    TT
#JUMP    A
1       EM
2       STRONG
3       =U
SUB     SUB
SUP     SUP
S       SDF_ASIS
ST      STRONG
Y       =ST
!endblock


# Mapping tables for attribute/parameter values
!block script
%html_align = (
    '1',    'Justify',
    'Full', 'Justify',
);
!endblock

# Mapping of paragraph attributes
!block paraattrs
Name        To          Map         Attributes
align       align       %html_align
!endblock

# Mapping of phrase attributes
!block phraseattrs
Name        To          Map         Attributes
family
size
bold
italics
underline
changed
color
!endblock

# Mapping of cell parameters
!block cellparams
Name        To          Map         Parameters
!endblock

## Set the default navigation text strings
#!define HTML_TEXT_CONTENTS      "Contents"
#!define HTML_TEXT_PARENT        "Parent Topic"
#!define HTML_TEXT_PREVIOUS      "Previous Topic"
#!define HTML_TEXT_NEXT          "Next Topic"
#!define HTML_TEXT_HOME          "Home"
#!define HTML_TEXT_CATALOG       "Catalog"
#!define HTML_TEXT_SEARCH        "Search"

## Set the default color for changed text
!default HTML_CHANGED_COLOR "teal"

# Setup the default section separator stuff
!default HTML_SECTION_LEVEL $var{'HTML_SUBTOPICS_MODE'} ? 2 : 1
!if HTMLDOC
    !macro HTML_PRE_SECTION
    !endmacro
!else
    !macro HTML_PRE_SECTION
    Line:
    !endmacro
!endif

# Prepend a separator before each section (the notoc stuff ensures
# that this rule isn't applied to the H1 generated by build_title)
!on paragraph '[HAP]\d';; \
    $my_style = $var{'HTML_SUBTOPICS_MODE'} ? $attr{'orig_style'} : $style; \
    if ($var{'DOC_TOC'} && substr($my_style, 1) <= $var{'HTML_SECTION_LEVEL'}) { \
        &PrependText('!HTML_PRE_SECTION') unless $attr{'notoc'}; \
    }

# In topics mode, special processing is needed on headings
!if $var{'HTML_TOPICS_MODE'} || $var{'HTML_SUBTOPICS_MODE'}
    !on paragraph '[HAP]\d';; &HtmlTopicsModeHeading
!endif

# ignore Page-breaks in html
!on paragraph 'PB';; $style = 'N'

# Default build_title output
!macro build_html_cover
!if $var{'OPT_DRIVER'} eq 'html'
        !div title
        !default DOC_TOC 2
        !default DOC_HTML_LOGO  $var{'DOC_LOGO'}
        !if DOC_HTML_LOGO
            !default DOC_HTML_LOGO_BASE  $var{'DOC_LOGO_BASE'}
            !import DOC_HTML_LOGO; align=Right; base=$var{'DOC_HTML_LOGO_BASE'}
            P1[notoc; class='doc-title'] [[DOC_TITLE]]
        !else
            P1[notoc; class='doc-title'] [[DOC_TITLE]]
        !endif
        !if $var{'OPT_STYLE'} eq 'paper'
            #Sign: [[DOC_STATUS]]
        !elsif DOC_STATUS
            Sign: {{A[class='doc-id'][[DOC_ID]]}} {{A[class='doc-status']([[DOC_STATUS]])}}
        !elsif DOC_ID
            Sign: {{A[class='doc-id'][[DOC_ID]]}}
        !endif
        Sign[class='doc-author'] [[join(", ", grep(/\w/, &Var('DOC_AUTHOR'), &Var('DOC_AUTHOR2'), &Var('DOC_AUTHOR3')))]]
        Sign[class='doc-modified'] [[DATE:DOC_MODIFIED]]
        !clear
        !enddiv

        # Setup the HTML title
        !HTML_BUILD_TITLE

        # This is no longer required now that the title is put in it's own div
        ## Mark the contents so we know where it is in topics mode
        #!block inline; target='html'
#
#
        #!endblock
!else
    # This is used for HTML documents generated via Frame
	dName: [[DOC_TITLE]]
	dStat: [[DOC_ID]] ([[DOC_STATUS]])
	dAuth: [[join(", ", grep(/\w/, @variable{'DOC_AUTHOR', 'DOC_AUTHOR2', 'DOC_AUTHOR3'}))]]
!endif
!endmacro

# Macro for building the title of the document and/or topic
!macro HTML_BUILD_TITLE
    !if HTML_SUBTOPICS_MODE
        !if DOC_PROJECT
            !define HTML_TITLE "$var{'DOC_PROJECT'}: $var{'HTML_MAIN_TITLE'}: $var{'DOC_TITLE'}"
        !else
            !define HTML_TITLE "$var{'HTML_MAIN_TITLE'}: $var{'DOC_TITLE'}"
        !endif
    !elsif DOC_PROJECT
        !define HTML_TITLE "$var{'DOC_PROJECT'}: $var{'DOC_TITLE'}"
    !else
        !define HTML_TITLE DOC_TITLE
    !endif
!endmacro


# Subroutine to build the main document navigation line
!block script
sub _html_mdnav {
    local($mdn);

    $mdn .= '{{A[jump=HTML_URL_HOME] [[HTML_TEXT_HOME]]}} | ' if $var{'HTML_URL_HOME'};
    $mdn .= '{{A[jump=HTML_URL_CATALOG] [[HTML_TEXT_CATALOG]]}} | ' if $var{'HTML_URL_CATALOG'};
    $mdn .= '{{A[jump=HTML_URL_SEARCH] [[HTML_TEXT_SEARCH]]}} | ' if $var{'HTML_URL_SEARCH'};
    $mdn =~ s/ \| $//;
    return $mdn;
}
!endblock

# Build the default header and footer for the main document
!macro HTML_HEADER
    !HTML_NAVIGATE
!endmacro
!macro HTML_FOOTER
    !HTML_NAVIGATE
!endmacro
!macro HTML_NAVIGATE
    !if HTML_TOPICS_MODE
        !HTML_TOPIC_NAVIGATE
    !else
        !div navigate
        !define _HTML_NAV &_html_mdnav
        !if _HTML_NAV
            [align='Center'] [[_HTML_NAV]]
        !endif
        !enddiv
    !endif
!endmacro

# Build the default header and footer for topics
!macro HTML_TOPIC_HEADER
    !default DOC_TOPIC_LOGO $var{'DOC_LOGO'}
    !if DOC_TOPIC_LOGO
        !default DOC_TOPIC_LOGO_BASE  $var{'DOC_LOGO_BASE'}
        !import DOC_TOPIC_LOGO; align="Right"; base=$var{'DOC_TOPIC_LOGO_BASE'}
        !HTML_TOPIC_NAVIGATE
        !clear "Right"
    !else
        !HTML_TOPIC_NAVIGATE
    !endif
!endmacro
!macro HTML_TOPIC_FOOTER
    !HTML_TOPIC_NAVIGATE
!endmacro
!macro HTML_TOPIC_NAVIGATE
!div navigate
    !block script
    if ($var{'HTML_TOPICS_MODE'}) {
        $_next = $topics[0] . ".html";
        $_prev = $topics[$#topics] . ".html";
    }
    else {
        $_base = $var{'HTML_TOPIC'};
        $_next = $topic_next{$_base} ? $topic_next{$_base} . ".html" : '';
        $_prev = $topic_prev{$_base} ? $topic_prev{$_base} . ".html" : '';
        $_up   = $topic_up{$_base} ? $topic_up{$_base} . ".html" : '';
    }

    # Build the second navigation line, if any
    $_nav2 = &_html_mdnav;
    if ($_nav2) {
        $_nav2 = "{{CHAR:nl}}" . $_nav2;
    }
    !endblock
    
    !if HTML_TOPICS_MODE
        [align='Center']
        {{A[jump=$_prev] [[HTML_TEXT_PREVIOUS]]}}
        | {{A[jump=$_next] [[HTML_TEXT_NEXT]]}}
        [[$_nav2]]
    !else
        [align='Center']
        {{A[jump=HTML_URL_CONTENTS] [[HTML_TEXT_CONTENTS]]}}
        | {{A[jump=$_up] [[HTML_TEXT_PARENT]]}}
        | {{A[jump=$_prev] [[HTML_TEXT_PREVIOUS]]}}
        | {{A[jump=$_next] [[HTML_TEXT_NEXT]]}}
        [[$_nav2]]
    !endif
!enddiv
!endmacro

# Use old footers, if requested
!if HTML_OLD_FOOTERS
    !macro HTML_FOOTER
        !HTML_PRE_SECTION
        !HTML_NAVIGATE
    !endmacro
    !macro HTML_TOPIC_FOOTER
        !HTML_PRE_SECTION
        !HTML_TOPIC_NAVIGATE
    !endmacro
!endif
log"
#!define HTML_TEXT_SEARCH        "Search"

## Set the default color for changed text
!default HTML_CHANGED_COLOR "teal"

# Setup the default section separator stuff
!default HTML_SECTION_sdf-2.001/perllib/sdf/home/stdlib/mif.sdn010064400042570001753000000257410645165135200200350ustar00iancmtr00000400000236# $Id$
#
# >>Title::     MIF Tuning
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# The {{stdlib/mif.sdn}} module defines [[SDF]] configuration details for
# generating [[MIF]] files.
#
# >>Description::
#
# >>Limitations::
#

# Make MIF a restricted family of variables
!restrict 'MIF'

# Declare Frame document variables
!block variables; family="MIF"; export
Name                        Type            Rule
COVER                       string
PAGE_SIZE                   pagesize
START_PAGE                  integer
PAGE_NUM_STYLE              keyword         
PAGE_POINT_STYLE            keyword         
TWO_SIDES                   boolean
PARITY                      keyword         
PAGE_ROUNDING               keyword         
FROZEN_PAGES                boolean
SMART_QUOTES_ON             boolean
SMART_SPACES_ON             boolean
LINEBREAK_CHARS             string
PUNCTUATION_CHARS           string
MAX_INTER_LINE              dimension
MAX_INTER_PGF               dimension
F_NOTE_TAG                  string
F_NOTE_MAX_H                dimension
F_NOTE_RESTART              keyword         
F_NOTE_START_NUM            integer
F_NOTE_NUM_STYLE            keyword         
F_NOTE_LABELS               string
F_NOTE_ANCHOR_POS           keyword         
F_NOTE_ANCHOR_PREFIX        string
F_NOTE_ANCHOR_SUFFIX        string
F_NOTE_NUMBER_POS           keyword         
F_NOTE_NUMBER_PREFIX        string
F_NOTE_NUMBER_SUFFIX        string
TBL_F_NOTE_TAG              string
TBL_F_NOTE_NUM_STYLE        keyword         
TBL_F_NOTE_LABELS           string
TBL_F_NOTE_ANCHOR_POS       keyword         
TBL_F_NOTE_ANCHOR_PREFIX    string
TBL_F_NOTE_ANCHOR_SUFFIX    string
TBL_F_NOTE_NUMBER_POS       keyword         
TBL_F_NOTE_NUMBER_PREFIX    string
TBL_F_NOTE_NUMBER_SUFFIX    string
CH_BAR_GAP                  dimension
CH_BAR_WIDTH                dimension
CH_BAR_POSITION             keyword         
CH_BAR_COLOR                string
VIEW_ONLY_X_REF             keyword         
VIEW_ONLY_SELECT            keyword         
VIEW_ONLY_WIN_BORDERS       boolean
VIEW_ONLY_WIN_MENUBAR       boolean
VIEW_ONLY_WIN_POPUP         boolean
VIEW_ONLY_WIN_PALETTE       boolean
LANGUAGE                    keyword
SUPERSCRIPT_SIZE            number
SUBSCRIPT_SIZE              number
SMALL_CAPS_SIZE             number
SUPERSCRIPT_SHIFT           number
SUBSCRIPT_SHIFT             number
!endblock

# Declare Frame paragraph attributes
!block paraattrs; family="mif"
Name                Type            Rule
UseNextTag          boolean
NextTag             string
FIndent             dimension
LIndent             dimension
RIndent             dimension
Alignment           keyword         
SpBefore            dimension
SpAfter             dimension
LineSpacing         keyword         
Leading             dimension
Placement           keyword         
PlacementStyle      keyword         
RunInDefaultPunct   string
WithPrev            boolean
WithNext            boolean
BlockSize           integer
AutoNum             boolean
NumFormat           string
NumberFont          string
NumAtEnd            boolean
Hyphenate           boolean
HyphenMaxLines      integer
HyphenMinPrefix     integer
HyphenMinSuffix     integer
HyphenMinWord       integer
LetterSpace         boolean
MinWordSpace        integer
OptWordSpace        integer
MaxWordSpace        integer
Language            keyword         
TopSeparator        string
BotSeparator        string
CellAlignment       keyword         
CellMargins         LTRB
CellLMarginFixed    boolean
CellTMarginFixed    boolean
CellRMarginFixed    boolean
CellBMarginFixed    boolean
TabStop             tabstop
AcrobatLevel        integer
NumTabs             integer
Locked              boolean
FIndentRelative     boolean
FIndentOffset       dimension
BotSepAtIndent      boolean
BotSepOffset        dimension
TopSepAtIndent      boolean
TopSepOffset        dimension
!endblock

# Declare Frame phrase attributes
!block phraseattrs; family="mif"; para="Font"
Name            Type            Rule
Family          string
Angle           string
Weight          string
Var             string
PostScriptName  string
PlatformName    string
Size            dimension
Color           string          
Separation      integer
Underlining     keyword         
Overline        boolean
Strike          boolean
ChangeBar       boolean
Position        keyword         
Outline         boolean
Shadow          boolean
PairKern        boolean
Case            keyword         
DX              dimension
DY              dimension
DW              dimension
Locked          boolean
!endblock

# Declare Frame table parameters
!block tableparams; family="mif"
Name            Type            Rule
LIndent         dimension
RIndent         dimension
SpBefore        dimension
SpAfter         dimension
Alignment       keyword         
Placement       keyword         
BlockSize       integer
CellMargins     LTRB
TitlePlacement  keyword         
TitleGap        dimension
NumByColumn     boolean
ColumnRuling    string
XColumnNum      integer
XColumnRuling   string
BodyRowRuling   string
XRowRuling      string
RulingPeriod    integer
HFRowRuling     string
SeparatorRuling string
LRuling         string
BRuling         string
RRuling         string
TRuling         string
LastBRuling     boolean
HFFill          integer
HFColor         string
HFSeparation    integer
BodyFill        integer
BodyColor       string
BodySeparation  integer
ShadeByColumn   boolean
ShadePeriod     integer
XFill           integer
XColor          string
XSeparation     integer
AltShadePeriod  integer
InitNumColumns  integer
InitNumBodyRows integer
InitNumFRows    integer
InitNumHRows    integer
!endblock

# Declare Frame row parameters
!block rowparams; family="mif"
Name            Type            Rule
WithNext        boolean
WithPrev        boolean
MinHeight       dimension
MaxHeight       dimension
Height          dimension
Placement       keyword         
!endblock

# Declare Frame cell parameters
!block cellparams; family="mif"
Name                Type            Rule
Fill                integer
Color               string
LRuling             string
BRuling             string
RRuling             string
TRuling             string
Columns             integer
Rows                integer
AffectsColumnWidthA boolean
Angle               integer         <0|90|180|270>
!endblock

# Mapping tables for attribute/parameter values
!block script
%mif_bool= (
    '0',        'No',
    '1',        'Yes',
);
%mif_align = (
    '1',    'LeftRight',
    'Full', 'LeftRight',
);
%mif_top = (
    '0',        'Anywhere',
    '1',        'PageTop',
    'Page',     'PageTop',
    'Column',   'ColumnTop',
    'Left',     'LPageTop',
    'Right',    'RPageTop',
);
%mif_wide = (
    '0',        'Normal',
    '1',        'Straddle',
);
%mif_ruling = (
    'Vthin',     'Very Thin',
);
!endblock

# Mapping of paragraph attributes
!block paraattrs
Name        To              Map         Attributes
nopb                                    Placement='Anywhere'
label       NumFormat                   AutoNum
left        LIndent
first       FIndent
right       RIndent
align       Alignment       %mif_align
top         Placement       %mif_top
keep_next   WithNext        %mif_bool
keep_prev   WithPrev        %mif_bool
sp_after    SpAfter
sp_before   SpBefore
wide        PlacementStyle  %mif_wide
tabs        TabStop
!endblock

# Mapping of phrase attributes
!block phraseattrs
Name        To          Map         Attributes
family      Family
size        Size
bold                                Weight='Bold'
italics                             Angle='Oblique'
underline                           Underlining='FSingle'
changed     ChangeBar   %mif_bool
color       Color
!endblock

# Cross-reference definitions
!block targetobjects; type=Xref
Name            Attributes
pagenum         value='<$pagenum\>'
paratext        value='<$paratext\>'
paratag         value='<$paratag\>'
paranum         value='<$paranum\>'
paranumonly     value='<$paranumonly\>'
section         value='section\x11 <$paranumonly\>, \xd2 <$paratext\>\xd3 , on page\x11 <$pagenum\>'
!endblock

# Handle book mode
!if MIF_BOOK_MODE
    # Start the front part
    !output &'MifNewComponent('front')

    # End the last component
    !block end
    !DOC_COMPONENT_END
    !output '-'
    !endblock

    # Start a new component, when requested
    !on paragraph '';; \
        &'MifNewComponent($attr{'component'}) if $attr{'component'}

    # Make each level 1 heading a component, unless it is already one
    !on paragraph '[HAP]1';; \
        if ($attr{'component'}) { \
        } \
        elsif (substr($style, 0, 1) eq 'H') {\
            $attr{'component'} = 1; \
        } \
        elsif (substr($style, 0, 1) eq 'A') {\
            $attr{'component'} = 'appendix'; \
        } \
        else { \
            $attr{'component'} = $text; \
        }
!endif

#
# If we are generating html, we need paragraphs without
# hypenation. Otherwise, the fm2html converter can sometimes
# fail to highlight the whole jump text.
#
!if $var{'OPT_TARGET'} eq 'html'
!on paragraph '';; $attr{'mif.Hyphenate'} = 0
!endif

# If we are generating text:
# * minimise wrapping of example lines
# * use * as the bullet character.
!if $var{'OPT_TARGET'} eq 'txt'
!on paragraph 'E'   ;; $style = 'E80'
!on paragraph 'LU\d';; $attr{'label'} = '*\t'
!endif

# If we are generating Windows help:
# * ignore PB tags (as page-breaks cause topic breaks)
# * use plain headings.
!if $var{'OPT_TARGET'} eq 'hlp'
!on paragraph 'PB';; $style = 'N'
!on paragraph '[HA]\d';; substr($style, 0, 1) = 'P'
!endif
oUnderlining|FSingle|FDouble|FNsdf-2.001/perllib/sdf/home/stdlib/stdlib.sdm010064400042570001753000000324230672214066600205370ustar00iancmtr00000400000236# $Id$
#
# >>Title::     Standard Library
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 24-Oct-98 ianc    added KN/KP support
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{stdlib}} is the [[SDF]] library containing the built-in features.
#
# >>Description::
# This library is {{2:always}} implicitly loaded.
#
# >>Limitations::
#

######## Declare the standard entities #########

# Declare built-in paragraph styles
!block parastyles
Name    Category
A0
A1
A2
A3
A4
A5
A6
Addr
E       example
E80     example
FA
FOOTER
FT
GL
GLD
GLT
H0
H1
H2
H3
H4
H5
H6
HEADER
L1
L2
L3
L4
L5
L6
Line
LF1
LF2
LF3
LF4
LF5
LF6
LI1
LI2
LI3
LI4
LI5
LI6
LN1
LN2
LN3
LN4
LN5
LN6
LU1
LU2
LU3
LU4
LU5
LU6
N
NB
NE
NV
Note
P0
P1
P2
P3
P4
P5
P6
PB
Sign
V       example
!endblock

# Declare built-in phrase styles
!block phrasestyles
Name        Category
1
2
3
A
B
C           example
E
F
I
L
N
P
S           example
T
U
X
Y
CHAR        special
CMD
EMAIL
EX          example
ST
FILE
INLINE      special
IMPORT      special
PAGENUM     special
PAGECOUNT   special
PARATEXT    special
PARANUM     special
PARANUMONLY special
PARASHORT   special
PARALAST    special
JUMP
SECT
SUB
SUP
!endblock

# Declare built-in paragraph attributes
# (Handled and removed prior to validation: obj, noevents)
!block paraattrs
Name        Type        Rule
align       string      <1|Full|Left|Right|Center>
first       string
keep_next   boolean
keep_prev   boolean
label       string
left        string
nopb        boolean
notoc       boolean
noid        boolean
continued   boolean
sp_after    string
sp_before   string
top         string      <1|0|Page|Column|Left|Right>
right       string
wide        boolean
component   string
tabs        string
in          integer
orig_style  string
out_style   string
!endblock

# Declare built-in phrase attributes
# (Handled and removed prior to validation: expand, shrink)
!block phraseattrs
Name        Type        Rule
bgcolor     string
bold        boolean
changed     boolean
class       string
color       string
family      string
id          string
index       string
index_type  string
italics     boolean
jump        string
short       string
size        string
style       string
underline   boolean
verbatim    boolean
xref        string
!endblock

# Declare built-in table styles
!block tablestyles
Name
columns
rows
grid
plain
shade
!endblock

# Declare built-in table parameters
!block tableparams
Name        Type        Rule
style       string
format      string
title       string
wide        boolean
narrow      boolean
align       string      
placement   string      
landscape   string
bgcolor     string
cellspacing integer
cellpadding integer
listitem    integer
tmargin     integer
bmargin     integer
lmargin     integer
rmargin     integer
colaligns   string
!endblock

# Declare built-in row parameters
#!block rowparams
#Name        Type        Rule
#!endblock

# Declare built-in cell parameters
!block cellparams
Name        Type        Rule
align       string      
valign      string      
cols        integer
rows        integer
nowrap      boolean
bgcolor     string
fill        integer     <100|90|70|50|30|10|3|0>
angle       integer     <0|90|180|270>
bruling     string      
lruling     string      
rruling     string      
truling     string      
tmargin     integer
bmargin     integer
lmargin     integer
rmargin     integer
hidden      boolean
!endblock

######## Define the standard variables #########

# Setup the default stuff
!default OPT_LOOK   DEFAULT_LOOK
!default OPT_LOCALE DEFAULT_LOCALE
!default OPT_STYLE  "document"
!default OPT_WIDTH  70
!default OPT_PAGE_SIZE "global"

# Declare restricted variable families
!restrict 'OPT'
!restrict 'DEFAULT'
!restrict 'DOC'

# Declare the option variables
!block variables; family="OPT"
Name                    Type        Rule
BORDERS                 integer
HEADINGS                integer
NUMBER_PER_COMPONENT    boolean
COMPONENT_COVER         boolean
TEMPLATE                string
LIST_INDENT             dimension
MARGIN_TOP              string
MARGIN_BOTTOM           string
MARGIN_INNER            string
MARGIN_OUTER            string
LOCALE                  string
!endblock

# Character definitions
!block define
Name            Value
amp             "{{CHAR:amp}}"
bullet          "{{CHAR:bullet}}"
c               "{{CHAR:c}}"
cent            "{{CHAR:cent}}"
dagger          "{{CHAR:dagger}}"
doubledagger    "{{CHAR:doubledagger}}"
emdash          "{{CHAR:emdash}}"
endash          "{{CHAR:endash}}"
emspace         "{{CHAR:emspace}}"
enspace         "{{CHAR:enspace}}"
nbdash          "{{CHAR:nbdash}}"
nbspace         "{{CHAR:nbspace}}"
nbsp            "{{CHAR:nbspace}}"
nl              "{{CHAR:nl}}"
pound           "{{CHAR:pound}}"
r               "{{CHAR:r}}"
reg             "{{CHAR:r}}"
tab             "{{CHAR:tab}}"
tm              "{{CHAR:tm}}"
yen             "{{CHAR:yen}}"
!endblock

# Colour variables
!block define; family="COLOR"
Name    Value
WHITE   'ffffff'
BLACK   '000000'
RED     'ff0000'
GREEN   '00ff00'
BLUE    '0000ff'
YELLOW  'ffff00'
MAGENTA 'ff00ff'
CYAN    '00ffff'
GREY    'c0c0c0'
!endblock

# Default FormatTime and case conversion variables.
!block default; family="FORMAT"
Name      Value
DATETIME  '&FormatTime(\'$day $month $year, $hour:$minute0.$second0\', $_)'
TIME      '&FormatTime(\'$hour:$minute0.$second0\', $_)'
DATE      '&FormatTime(\'$day $month $year\', $_)'
SDATE     '&FormatTime(\'$day0-$smonth-$syear\', $_)'
YEAR      '&FormatTime(\'$year\', $_)'
UPPER     '"\U$_"'
LOWER     '"\L$_"'
UPPER1    '"\u$_"'
LOWER1    '"\l$_"'
!endblock

# Provide FULL and CONCISE DateTime formats for backwards compatibility
!default FORMAT_FULL    FORMAT_DATETIME
!default FORMAT_CONCISE FORMAT_SDATE

# Declare generation control variables
!block variables; family="DEFAULT"
Name        Type        Rule
TABLE_STYLE string
XREF_STYLE  string
TAB_SIZE    integer
!endblock

# Set the default generation controls
!default DEFAULT_TABLE_STYLE "columns"
!default DEFAULT_XREF_STYLE  "section"
!default DEFAULT_TAB_SIZE    8

# Declare column layout variables
!block variables; family="OPT,OPT_IX"
Name                    Type        Rule
SIDEHEAD_WIDTH          dimension
SIDEHEAD_GAP            dimension
COLUMNS                 integer
COLUMN_GAP              dimension
!endblock

# Declare page layout variables
!block variables; family="PAGE_FIRST,PAGE_RIGHT,PAGE_LEFT"
Name                Type        Rule
HEADER_BORDER       string
HEADER_HEIGHT       dimension
HEADER_GAP          dimension
FOOTER_BORDER       string
FOOTER_HEIGHT       dimension
FOOTER_GAP          dimension
BACKGROUND          string
!endblock

# Declare header/footer variables
!block variables; family="PAGE_FIRST,PAGE_RIGHT,PAGE_LEFT"
Name                Type        Rule
HEADER_INNER1       string
HEADER_INNER2       string
HEADER_CENTER1      string
HEADER_CENTER2      string
HEADER_OUTER1       string
HEADER_OUTER2       string
FOOTER_INNER0       string
FOOTER_INNER1       string
FOOTER_INNER2       string
FOOTER_INNER3       string
FOOTER_CENTER0      string
FOOTER_CENTER1      string
FOOTER_CENTER2      string
FOOTER_CENTER3      string
FOOTER_OUTER0       string
FOOTER_OUTER1       string
FOOTER_OUTER2       string
FOOTER_OUTER3       string
!endblock

# Declare the document "title" variables
!block variables; family="DOC"
Name            Type        Rule
COVER           string
NAME            string
TYPE            string
STATUS          string
AUTHOR          string
AUTHOR2         string
AUTHOR3         string
CODE            string
VERSION         string
DISTRIBUTION    string
PROJECT         string
PRODUCT         string
SECTION         integer
APPROVE         string
APPROVE2        string
APPROVE3        string
ID              string
ID_SEP          string
URL             string
TITLE           string
OWNER           string
LOGO            string
LOGO_BASE       string
TITLE_LOGO      string
TITLE_LOGO_BASE string
ADMIN_LOGO      string
ADMIN_LOGO_BASE string
HTML_LOGO       string
HTML_LOGO_BASE  string
TOPIC_LOGO      string
TOPIC_LOGO_BASE string
MANUAL_LOGO     string
COMPONENT_LOGO  string
TOC             integer
LOF             boolean
LOT             boolean
IX              boolean
TWO_SIDES       boolean
COMPONENT       string
PAGED           boolean
!endblock

# Export these for use in generating lists
#!block variables; family="DOC"; export
!block variables; family="DOC"
Name        Type        Rule
TOC_TITLE   string
TOC_GRAPHIC string
LOF_TITLE   string
LOT_TITLE   string
!endblock

# Set the default list indent (1/4 inch)
!default OPT_LIST_INDENT 18

# Modified date variable for easier memos, etc.
!define MODIFIED_DATE DATE:DOC_MODIFIED

# Generally useful SDF variables
!define SDF             "{{PRD:SDF}}"
!define SDF_WWW         "http://www.mincom.com/mtr/sdf"
!define SDF_FTP         "ftp://ftp.mincom.com/pub/mtr/sdf"
!define SDF_BUGS        '{{EMAIL:sdf-bugs@mincom.com}}'
!define SDF_USERS       '{{EMAIL:sdf-users@mincom.com}}'

######## Define the standard rules #########

# If the text attribute is set, use it instead of the current text
!on paragraph '';; if (defined($attr{'text'})) {$text = delete $attr{'text'}}
!on phrase    '';; if (defined($attr{'text'})) {$text = delete $attr{'text'}}

# For online target, ignore the style (i.e. make 'as-is') for hypertext jumps
!if $var{'OPT_TARGET'} eq 'html' || $var{'OPT_TARGET'} eq 'hlp' || $var{'OPT_TARGET'} eq 'fvo'
!on phrase '';; $style = 'A' if $attr{'jump'} ne ''
!endif

# Convert xref attributes to a special style, if the output is PostScript
!if $var{'OPT_TARGET'} eq 'ps'
!on phrase '';; &ConvertXRef
!endif

# Treat 'obj' paragraphs as phrases
!on paragraph '';; &CheckParaObject

# Support KN & KP (keep-next/previous) paragraph styles
!on paragraph 'KN';; $style = N; $attr{'keep_next'} = 1
!on paragraph 'KP';; $style = N; $attr{'keep_prev'} = 1

# Automatic hypertext generation
!on phrase 'JUMP' ;; $attr{'jump'} = $text
!on phrase 'EMAIL';; $attr{'jump'} = "mailto:" . $text
!on phrase 'SECT' ;; &BuildSectJump

# If OPT_NOBARS is set, ignore change bars
!if OPT_NOBARS
!on paragraph '';; delete $attr{'changed'} if $attr{'changed'};
!on phrase    '';; delete $attr{'changed'} if $attr{'changed'};
!endif

# Useful filters
!on filter 'template';; $name='inline'; $params.="; expand"
!on filter 'changed';; $name='sdf'; $params.="; changed"
!on filter 'center' ;; $name='sdf'; $params.="; align=Center"
!on filter 'chapter';; $name = 'sdf'
!on filter 'glossary';; $name = 'plain'

# Do nice things to phrases which look like URLs
!on phrase '1';; \
        if ($text =~ /^(http|ftp|telnet|news|gopher|wais|https|snews):/) {\
            $style = 'JUMP'; \
        }

# Make URL an alias for JUMP
!on phrase 'URL';; $style="JUMP"

# For all level 1 headings, reset the current topic name
#!on paragraph '[HAP]1';; $topic = $attr{'id'}
!on paragraph '[HAP]1';; $topic = $text

# Convert a glossary paragraph into term and definition paragraphs
!if $var{'OPT_TARGET'} ne 'html'
!on paragraph 'GL';; $style = 'GLT'; \
                     ($text, $_rest) = split(/\t/, $text, 2);\
                     &AppendText("GLD:" . $_rest)
!endif

# Give each heading a hypertext id, unless:
# * it doesn't have one, or
# * it already has one, or
# * it has been explicitly excluded from the table of contents.
!if &Var('OPT_DRIVER') ne 'raw'
!on paragraph '[HAP]\d';; \
    unless ($attr{'noid'} || $attr{'id'} ne '' || $attr{'notoc'}) { \
        $attr{'id'} = $subsection_prefix{$text} . &TextToId($text); \
    }
!endif

# If a file looks like a URL, assume it is (a PODism)
!on phrase 'FILE';; if ($text =~ /^\w\w+:/) {$attr{'jump'} = $text}

# Support POD phrase style names
!on phrase 'C';; $style = 'EX'
#!on phrase 'E';; $style = 'CHAR'
!on phrase 'F';; $style = 'FILE'

# DOC_PAGED needs to be set here (rather than in *.sdn) as sdn files
# get invoked *after* DOC_PAGED triggers the page-related stuff.
!if $var{'OPT_DRIVER'} eq 'mif' || $var{'HTMLDOC'}
!define DOC_PAGED 1
!endif


######## Define the standard classes & objects #########

# Note: Class definitions must occur AFTER the general rules defined above,
# as defining a class adds rules to the event processing tables.
# Likewise, rules which assume a class has been defined must go
# AFTER the class definitions below.

# Classes
!class references    'REF,DOC'; 'Reference,Document'; 'Jump,Version,Status'
!class terms         'TERM'   ; 'Term,Definition'
!class products      'PRD'    ; 'Name'
!class organisations 'ORG,ORGN'

# Support REFNUMONLY - a reference where only the trailing number is output
!on phrase 'REFNUMONLY';; $style = 'REF'; \
    $attr{'text'} = ($text =~ /([\d\.]+)$/) ? $1 : $text

# Objects
!block products; data
Name            Jump
SDF             http://www.mincom.com/mtr/sdf/
!endblock


######## Load the standard libraries & modules #########

!inherit "images"
!use     "stdlib/macros"
!use     "stdlib/langdefs"
!use     "locale/$var{'OPT_LOCALE'}.sdl"
sdf-2.001/perllib/sdf/home/stdlib/pages.sdm010064400042570001753000000224520640440505400203460ustar00iancmtr00000400000236
############### HEADERS & FOOTERS ##################

# Note: The headers and footers are defined in terms of other variables
# as this approach makes it easier for an author to customise them.

# Define the first page header
!macro PAGE_FIRST_HEADER
!if $var{'OPT_HEADINGS'} == 1
    HEADER:[[PAGE_FIRST_HEADER_INNER1]]
    [[tab]][[PAGE_FIRST_HEADER_CENTER1]]
    [[tab]][[PAGE_FIRST_HEADER_OUTER1]]
!elsif $var{'OPT_HEADINGS'} >= 2
    HEADER:[[PAGE_FIRST_HEADER_INNER1]]
    [[tab]][[PAGE_FIRST_HEADER_CENTER1]]
    [[tab]][[PAGE_FIRST_HEADER_OUTER1]]
     [[nl]][[PAGE_FIRST_HEADER_INNER2]]
    [[tab]][[PAGE_FIRST_HEADER_CENTER2]]
    [[tab]][[PAGE_FIRST_HEADER_OUTER2]]
!endif
!endmacro

# Define the first page footer
!macro PAGE_FIRST_FOOTER
!if $var{'OPT_HEADINGS'} == 1
    FOOTER:[[PAGE_FIRST_FOOTER_INNER1]]
    [[tab]][[PAGE_FIRST_FOOTER_CENTER1]]
    [[tab]][[PAGE_FIRST_FOOTER_OUTER1]]
!elsif $var{'OPT_HEADINGS'} == 2
    FOOTER:[[PAGE_FIRST_FOOTER_INNER1]]
    [[tab]][[PAGE_FIRST_FOOTER_CENTER1]]
    [[tab]][[PAGE_FIRST_FOOTER_OUTER1]]
     [[nl]][[PAGE_FIRST_FOOTER_INNER2]]
    [[tab]][[PAGE_FIRST_FOOTER_CENTER2]]
    [[tab]][[PAGE_FIRST_FOOTER_OUTER2]]
!elsif $var{'OPT_HEADINGS'} == 3
    FOOTER[size='7pt'][[PAGE_FIRST_FOOTER_INNER1]]
    [[tab]][[PAGE_FIRST_FOOTER_CENTER1]]
    [[tab]][[PAGE_FIRST_FOOTER_OUTER1]]
     [[nl]][[PAGE_FIRST_FOOTER_INNER2]]
    [[tab]][[PAGE_FIRST_FOOTER_CENTER2]]
    [[tab]][[PAGE_FIRST_FOOTER_OUTER2]]
     [[nl]][[PAGE_FIRST_FOOTER_INNER3]]
    [[tab]][[PAGE_FIRST_FOOTER_CENTER3]]
    [[tab]][[PAGE_FIRST_FOOTER_OUTER3]]
!elsif $var{'OPT_HEADINGS'} >= 4
    FOOTER[size='7pt'][[PAGE_FIRST_FOOTER_INNER0]]
    [[tab]][[PAGE_FIRST_FOOTER_CENTER0]]
    [[tab]][[PAGE_FIRST_FOOTER_OUTER0]]
     [[nl]][[PAGE_FIRST_FOOTER_INNER1]]
    [[tab]][[PAGE_FIRST_FOOTER_CENTER1]]
    [[tab]][[PAGE_FIRST_FOOTER_OUTER1]]
     [[nl]][[PAGE_FIRST_FOOTER_INNER2]]
    [[tab]][[PAGE_FIRST_FOOTER_CENTER2]]
    [[tab]][[PAGE_FIRST_FOOTER_OUTER2]]
     [[nl]][[PAGE_FIRST_FOOTER_INNER3]]
    [[tab]][[PAGE_FIRST_FOOTER_CENTER3]]
    [[tab]][[PAGE_FIRST_FOOTER_OUTER3]]
!endif
!endmacro

# Define the right page header
!macro PAGE_RIGHT_HEADER
!if $var{'OPT_HEADINGS'} == 1
    HEADER:[[PAGE_RIGHT_HEADER_INNER1]]
    [[tab]][[PAGE_RIGHT_HEADER_CENTER1]]
    [[tab]][[PAGE_RIGHT_HEADER_OUTER1]]
!elsif $var{'OPT_HEADINGS'} >= 2
    HEADER:[[PAGE_RIGHT_HEADER_INNER1]]
    [[tab]][[PAGE_RIGHT_HEADER_CENTER1]]
    [[tab]][[PAGE_RIGHT_HEADER_OUTER1]]
     [[nl]][[PAGE_RIGHT_HEADER_INNER2]]
    [[tab]][[PAGE_RIGHT_HEADER_CENTER2]]
    [[tab]][[PAGE_RIGHT_HEADER_OUTER2]]
!endif
!endmacro

# Define the right page footer
!macro PAGE_RIGHT_FOOTER
!if $var{'OPT_HEADINGS'} == 1
    FOOTER:[[PAGE_RIGHT_FOOTER_INNER1]]
    [[tab]][[PAGE_RIGHT_FOOTER_CENTER1]]
    [[tab]][[PAGE_RIGHT_FOOTER_OUTER1]]
!elsif $var{'OPT_HEADINGS'} == 2
    FOOTER:[[PAGE_RIGHT_FOOTER_INNER1]]
    [[tab]][[PAGE_RIGHT_FOOTER_CENTER1]]
    [[tab]][[PAGE_RIGHT_FOOTER_OUTER1]]
     [[nl]][[PAGE_RIGHT_FOOTER_INNER2]]
    [[tab]][[PAGE_RIGHT_FOOTER_CENTER2]]
    [[tab]][[PAGE_RIGHT_FOOTER_OUTER2]]
!elsif $var{'OPT_HEADINGS'} == 3
    FOOTER[size='7pt'][[PAGE_RIGHT_FOOTER_INNER1]]
    [[tab]][[PAGE_RIGHT_FOOTER_CENTER1]]
    [[tab]][[PAGE_RIGHT_FOOTER_OUTER1]]
     [[nl]][[PAGE_RIGHT_FOOTER_INNER2]]
    [[tab]][[PAGE_RIGHT_FOOTER_CENTER2]]
    [[tab]][[PAGE_RIGHT_FOOTER_OUTER2]]
     [[nl]][[PAGE_RIGHT_FOOTER_INNER3]]
    [[tab]][[PAGE_RIGHT_FOOTER_CENTER3]]
    [[tab]][[PAGE_RIGHT_FOOTER_OUTER3]]
!elsif $var{'OPT_HEADINGS'} >= 4
    FOOTER[size='7pt'][[PAGE_RIGHT_FOOTER_INNER0]]
    [[tab]][[PAGE_RIGHT_FOOTER_CENTER0]]
    [[tab]][[PAGE_RIGHT_FOOTER_OUTER0]]
     [[nl]][[PAGE_RIGHT_FOOTER_INNER1]]
    [[tab]][[PAGE_RIGHT_FOOTER_CENTER1]]
    [[tab]][[PAGE_RIGHT_FOOTER_OUTER1]]
     [[nl]][[PAGE_RIGHT_FOOTER_INNER2]]
    [[tab]][[PAGE_RIGHT_FOOTER_CENTER2]]
    [[tab]][[PAGE_RIGHT_FOOTER_OUTER2]]
     [[nl]][[PAGE_RIGHT_FOOTER_INNER3]]
    [[tab]][[PAGE_RIGHT_FOOTER_CENTER3]]
    [[tab]][[PAGE_RIGHT_FOOTER_OUTER3]]
!endif
!endmacro

# Define the left page header
!macro PAGE_LEFT_HEADER
!if $var{'OPT_HEADINGS'} == 1
    HEADER:[[PAGE_LEFT_HEADER_INNER1]]
    [[tab]][[PAGE_LEFT_HEADER_CENTER1]]
    [[tab]][[PAGE_LEFT_HEADER_OUTER1]]
!elsif $var{'OPT_HEADINGS'} >= 2
    HEADER:[[PAGE_LEFT_HEADER_OUTER1]]
    [[tab]][[PAGE_LEFT_HEADER_CENTER1]]
    [[tab]][[PAGE_LEFT_HEADER_INNER1]]
     [[nl]][[PAGE_LEFT_HEADER_OUTER2]]
    [[tab]][[PAGE_LEFT_HEADER_CENTER2]]
    [[tab]][[PAGE_LEFT_HEADER_INNER2]]
!endif
!endmacro

# Define the left page footer
!macro PAGE_LEFT_FOOTER
!if $var{'OPT_HEADINGS'} == 1
    FOOTER:[[PAGE_LEFT_FOOTER_INNER1]]
    [[tab]][[PAGE_LEFT_FOOTER_CENTER1]]
    [[tab]][[PAGE_LEFT_FOOTER_OUTER1]]
!elsif $var{'OPT_HEADINGS'} == 2
    FOOTER:[[PAGE_LEFT_FOOTER_OUTER1]]
    [[tab]][[PAGE_LEFT_FOOTER_CENTER1]]
    [[tab]][[PAGE_LEFT_FOOTER_INNER1]]
     [[nl]][[PAGE_LEFT_FOOTER_OUTER2]]
    [[tab]][[PAGE_LEFT_FOOTER_CENTER2]]
    [[tab]][[PAGE_LEFT_FOOTER_INNER2]]
!elsif $var{'OPT_HEADINGS'} == 3
    FOOTER[size='7pt'][[PAGE_LEFT_FOOTER_OUTER1]]
    [[tab]][[PAGE_LEFT_FOOTER_CENTER1]]
    [[tab]][[PAGE_LEFT_FOOTER_INNER1]]
     [[nl]][[PAGE_LEFT_FOOTER_OUTER2]]
    [[tab]][[PAGE_LEFT_FOOTER_CENTER2]]
    [[tab]][[PAGE_LEFT_FOOTER_INNER2]]
     [[nl]][[PAGE_LEFT_FOOTER_OUTER3]]
    [[tab]][[PAGE_LEFT_FOOTER_CENTER3]]
    [[tab]][[PAGE_LEFT_FOOTER_INNER3]]
!elsif $var{'OPT_HEADINGS'} >= 4
    FOOTER[size='7pt'][[PAGE_LEFT_FOOTER_OUTER0]]
    [[tab]][[PAGE_LEFT_FOOTER_CENTER0]]
    [[tab]][[PAGE_LEFT_FOOTER_INNER0]]
     [[nl]][[PAGE_LEFT_FOOTER_OUTER1]]
    [[tab]][[PAGE_LEFT_FOOTER_CENTER1]]
    [[tab]][[PAGE_LEFT_FOOTER_INNER1]]
     [[nl]][[PAGE_LEFT_FOOTER_OUTER2]]
    [[tab]][[PAGE_LEFT_FOOTER_CENTER2]]
    [[tab]][[PAGE_LEFT_FOOTER_INNER2]]
     [[nl]][[PAGE_LEFT_FOOTER_OUTER3]]
    [[tab]][[PAGE_LEFT_FOOTER_CENTER3]]
    [[tab]][[PAGE_LEFT_FOOTER_INNER3]]
!endif
!endmacro

# Macro to build the left page as a mirror of the right page
!macro left_mirror_right_page
# Copy the page layout
!define PAGE_LEFT_HEADER_BORDER   $var{'PAGE_RIGHT_HEADER_BORDER'}
!define PAGE_LEFT_HEADER_HEIGHT   $var{'PAGE_RIGHT_HEADER_HEIGHT'}
!define PAGE_LEFT_HEADER_GAP      $var{'PAGE_RIGHT_HEADER_GAP'}
!define PAGE_LEFT_FOOTER_BORDER   $var{'PAGE_RIGHT_FOOTER_BORDER'}
!define PAGE_LEFT_FOOTER_HEIGHT   $var{'PAGE_RIGHT_FOOTER_HEIGHT'}
!define PAGE_LEFT_FOOTER_GAP      $var{'PAGE_RIGHT_FOOTER_GAP'}

# Mirror the header
!define PAGE_LEFT_HEADER_INNER1   $var{'PAGE_RIGHT_HEADER_INNER1'}
!define PAGE_LEFT_HEADER_INNER2   $var{'PAGE_RIGHT_HEADER_INNER2'}
!define PAGE_LEFT_HEADER_CENTER1  $var{'PAGE_RIGHT_HEADER_CENTER1'}
!define PAGE_LEFT_HEADER_CENTER2  $var{'PAGE_RIGHT_HEADER_CENTER2'}
!define PAGE_LEFT_HEADER_OUTER1   $var{'PAGE_RIGHT_HEADER_OUTER1'}
!define PAGE_LEFT_HEADER_OUTER2   $var{'PAGE_RIGHT_HEADER_OUTER2'}

# Mirror the footer
!define PAGE_LEFT_FOOTER_INNER0   $var{'PAGE_RIGHT_FOOTER_INNER0'}
!define PAGE_LEFT_FOOTER_INNER1   $var{'PAGE_RIGHT_FOOTER_INNER1'}
!define PAGE_LEFT_FOOTER_INNER2   $var{'PAGE_RIGHT_FOOTER_INNER2'}
!define PAGE_LEFT_FOOTER_INNER3   $var{'PAGE_RIGHT_FOOTER_INNER3'}
!define PAGE_LEFT_FOOTER_CENTER0  $var{'PAGE_RIGHT_FOOTER_CENTER0'}
!define PAGE_LEFT_FOOTER_CENTER1  $var{'PAGE_RIGHT_FOOTER_CENTER1'}
!define PAGE_LEFT_FOOTER_CENTER2  $var{'PAGE_RIGHT_FOOTER_CENTER2'}
!define PAGE_LEFT_FOOTER_CENTER3  $var{'PAGE_RIGHT_FOOTER_CENTER3'}
!define PAGE_LEFT_FOOTER_OUTER0   $var{'PAGE_RIGHT_FOOTER_OUTER0'}
!define PAGE_LEFT_FOOTER_OUTER1   $var{'PAGE_RIGHT_FOOTER_OUTER1'}
!define PAGE_LEFT_FOOTER_OUTER2   $var{'PAGE_RIGHT_FOOTER_OUTER2'}
!define PAGE_LEFT_FOOTER_OUTER3   $var{'PAGE_RIGHT_FOOTER_OUTER3'}
!endmacro

# Macro to build the first page as a copy of the right page
!macro first_copy_right_page
# Copy the page layout
!define PAGE_FIRST_HEADER_BORDER $var{'PAGE_RIGHT_HEADER_BORDER'}
!define PAGE_FIRST_HEADER_HEIGHT $var{'PAGE_RIGHT_HEADER_HEIGHT'}
!define PAGE_FIRST_HEADER_GAP    $var{'PAGE_RIGHT_HEADER_GAP'}
!define PAGE_FIRST_FOOTER_BORDER $var{'PAGE_RIGHT_FOOTER_BORDER'}
!define PAGE_FIRST_FOOTER_HEIGHT $var{'PAGE_RIGHT_FOOTER_HEIGHT'}
!define PAGE_FIRST_FOOTER_GAP    $var{'PAGE_RIGHT_FOOTER_GAP'}

# Copy the header
!define PAGE_FIRST_HEADER_INNER1   $var{'PAGE_RIGHT_HEADER_INNER1'}
!define PAGE_FIRST_HEADER_INNER2   $var{'PAGE_RIGHT_HEADER_INNER2'}
!define PAGE_FIRST_HEADER_CENTER1  $var{'PAGE_RIGHT_HEADER_CENTER1'}
!define PAGE_FIRST_HEADER_CENTER2  $var{'PAGE_RIGHT_HEADER_CENTER2'}
!define PAGE_FIRST_HEADER_OUTER1   $var{'PAGE_RIGHT_HEADER_OUTER1'}
!define PAGE_FIRST_HEADER_OUTER2   $var{'PAGE_RIGHT_HEADER_OUTER2'}

# Copy the footer
!define PAGE_FIRST_FOOTER_INNER0   $var{'PAGE_RIGHT_FOOTER_INNER0'}
!define PAGE_FIRST_FOOTER_INNER1   $var{'PAGE_RIGHT_FOOTER_INNER1'}
!define PAGE_FIRST_FOOTER_INNER2   $var{'PAGE_RIGHT_FOOTER_INNER2'}
!define PAGE_FIRST_FOOTER_INNER3   $var{'PAGE_RIGHT_FOOTER_INNER3'}
!define PAGE_FIRST_FOOTER_CENTER0  $var{'PAGE_RIGHT_FOOTER_CENTER0'}
!define PAGE_FIRST_FOOTER_CENTER1  $var{'PAGE_RIGHT_FOOTER_CENTER1'}
!define PAGE_FIRST_FOOTER_CENTER2  $var{'PAGE_RIGHT_FOOTER_CENTER2'}
!define PAGE_FIRST_FOOTER_CENTER3  $var{'PAGE_RIGHT_FOOTER_CENTER3'}
!define PAGE_FIRST_FOOTER_OUTER0   $var{'PAGE_RIGHT_FOOTER_OUTER0'}
!define PAGE_FIRST_FOOTER_OUTER1   $var{'PAGE_RIGHT_FOOTER_OUTER1'}
!define PAGE_FIRST_FOOTER_OUTER2   $var{'PAGE_RIGHT_FOOTER_OUTER2'}
!define PAGE_FIRST_FOOTER_OUTER3   $var{'PAGE_RIGHT_FOOTER_OUTER3'}
!endmacro
sdf-2.001/perllib/sdf/home/stdlib/latex.sdn010075500042570001753000000033260661637603600204030ustar00iancmtr00000400000236# $Id$
#
# >>Title::     LaTeX Tuning
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 14-Aug-97 ianc    SDF 2.000
# 30-Oct-98 Valerio Added LaTeX support
# -----------------------------------------------------------------------
#
# >>Purpose::
# The {{stdlib/latex.sdn}} module defines [[SDF]] configuration details for
# generating {{LaTeX}} files.
#
# >>Description::
#
# >>Limitations::
#

# Make LATEX a restricted variable family
!restrict 'LATEX'

# Declare document variables
!block variables; family="LATEX"; export
Name                        Type            Rule
!endblock

# Define paragraph styles
!block parastyles
Name        To                      Attributes
H1          \chapter
H2          \section
H3          \subsection
H4          \subsubsection
H5          \paragraph
H6          \subparagraph
P1          \chapter*
P2          \section*
P3          \subsection*
P4          \subsubsection*
P5          \paragraph*
P6          \subparagraph*
A1          \chapter
A2          \section
A3          \subsection
A4          \subsubsection
A5          \paragraph
A6          \subparagraph



!endblock

# Define phrase styles
# Note: some of these are less than optimal :-)
!block phrasestyles
Name    To
A       SDF_ASIS
B       {\textbf{
C       {\textbf{
F       SDF_VERBATIM 
I       {\textit{
L       =F
N       {\normalfont{
S       =S
U       =B
1       =I
2       =B
3       =U
ST      =B
EX      =C
FILE    =F
JUMP    =F
EMAIL	=I
!endblock

# Default build_title output
!macro build_latex_cover
!endmacro
sdf-2.001/perllib/sdf/home/stdlib/default.sdg010064400042570001753000000022360671675616200207020ustar00iancmtr00000400000236# $Id$
#
# >>Title::     User Documentation SDG Report
#
# >>Copyright::
# Copyright (c) 1992-1999, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# This report is used to extract and format the user-oriented sections
# of SDF-style embedded documentation.
#
# >>Description::
# 
# >>Limitations::
#
Key             Format
-               "!use 'sdgmacs'\n!SDG_BEGIN\n"
Title           "H1[id=\"$short\"] $short - $data\n\n"
Purpose         "H2: $key\n\n$data\n\n"
Interface       "H2: $key\n\n$data\n\n"
-               "!SDG_DESCRIPTION_PRE\n"
Description     "H2: $key\n\n$data\n\n"
-               "!SDG_DESCRIPTION_POST\n"
Notes           "H2: $key\n\n$data\n\n"
Examples        "H2: $key\n\n$data\n\n"
Limitations     "H2: Limitations and future directions\n\n$data\n\n"
See_also        "H2: See also\n\n$data\n\n"
Authors         "H2: $key\n\n$data\n\n"
-               "!SDG_END\n"
sdf-2.001/perllib/sdf/home/stdlib/sdgmacs.sdm010075500042570001753000000061240671642431500207000ustar00iancmtr00000400000236# $Id$
#
# >>Title::     Macros for sdfget
#
# >>Copyright::
# Copyright (c) 1992-1999, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 13-May-99 ianc    Initial creation
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{MOD:sdgmacs}} provides macros used by the predefined {{FMT:SDG}} reports.
#
# >>Description::
#
# >>Limitations::
#
######## OPTION MACROS #########

#
# >>Description::
# The SDF_OPT_HELP macro provides text explaining the -h option.
#
!macro SDF_OPT_HELP
The -h option provides help. If it is specified without a parameter,
a brief description of each option is displayed. To display
the attributes for an option, specify the option letter as a parameter.
!endmacro

#
# >>Description::
# The SDF_OPT_STD macro provides text explaining the standard options.
#
!macro SDF_OPT_STD
!SDF_OPT_HELP

By default, generated output goes to standard output. To direct
output to a file per input file, use the -o option to specify
an extension for output files. If the -o option is specified
without a parameter, an extension of {{out}} is assumed.

Likewise, error messages go to standard error by default. Use
the -l option to create a log file per input file. If the -l
option is specified without a parameter, an extension of {{log}}
is assumed.

By default, generated output and log files are created in the
current directory. Use the -O option to specify an explicit
output directory. If the -O option is specified without a
parameter, the input file's directory is used.
!endmacro

######## SDG MACROS #########

#
# >>Description::
# The SDG_DESCRIPTION_PRE macro is used in SDG reports to automatically
# create an Interface, Data or Usage section just before the Description.
#
!macro SDG_DESCRIPTION_PRE
!if $var{'FILE_EXT'} eq 'pl'
	H2: Interface
	!perlapi FILE_SHORT; example
	!on phrase 'Y'; _symbols; \
          $attr{'id'} = &TextToId("$var{'FILE_BASE'}_$text"); \
          $attr{'id'} =~ s/[\$\@\%]//g
!elsif $var{'FILE_EXT'} eq 'idl'
	H2: Interface
	!getcode FILE_SHORT; idl
!elsif $var{'FILE_EXT'} eq 'sdg'
	H2: Data
	!getcode FILE_SHORT; table
!elsif $var{'FILE_EXT'} eq '' || $var{'FILE_EXT'} =~ /^(bat|cmd|sh)$/
	H2: Usage
	!getusage FILE_BASE
        !script %found = ()
	!on paragraph ''; _options; if ($text =~ / \-(\w)/) {$tmpid = "$var{'FILE_BASE'}_$1";unless ($found{$tmpid}++) {$attr{'id'} = $tmpid}}
!endif
!endmacro

#
# >>Description::
# The SDG_DESCRIPTION_POST macro is used in SDG reports to switch
# off event processing enabled by SDG_DESCRIPTION-POST.
#
!macro SDG_DESCRIPTION_POST
!if $var{'FILE_EXT'} eq 'pl'
	!off phrase _symbols
!elsif $var{'FILE_EXT'} eq '' || $var{'FILE_EXT'} =~ /^(bat|cmd|sh)$/
	!off paragraph _options
!endif
!endmacro

#
# >>Description::
# The SDG_BEGIN macro is a hook for text at the beginning of an SDG report.
#
!macro SDG_BEGIN
!endmacro

#
# >>Description::
# The SDG_END macro is a hook for text at the end of an SDG report.
#
!macro SDG_END
!endmacro
sdf-2.001/perllib/sdf/home/stdlib/pod.sdn010064400042570001753000000026460636603141000200330ustar00iancmtr00000400000236# $Id$
#
# >>Title::     POD Tuning
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 14-May-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# The {{stdlib/pod.sdn}} module defines [[SDF]] configuration details for
# generating {{POD}} files.
#
# >>Description::
# POD_MARGIN is used in the formatting of tables.
# The default margin is taken from sdf -w option.
#
# >>Limitations::
#

# Set the default margin
!default POD_MARGIN OPT_WIDTH

# Make POD a restricted variable family
!restrict 'POD'

# Declare document variables
!block variables; family="POD"; export
Name                        Type            Rule
MARGIN                      integer
!endblock

# Define paragraph styles
!block parastyles
Name        To                      Attributes
H1          head1
H2          head2
!endblock

# Define phrase styles
# Note: some of these are less than optimal :-)
!block phrasestyles
Name    To
A       S
B       B
C       C
F       F
I       I
L       L
N       S
S       S
U       B
1       =I
2       =B
3       =U
ST      B
EX      C
FILE    F
JUMP    L
!endblock

# Default build_title output
!macro build_pod_cover
	H1: NAME
	N: [[DOC_TITLE]]
!endmacro
sdf-2.001/perllib/sdf/home/stdlib/bugtrack.sdm010064400042570001753000000041260644616202200210500ustar00iancmtr00000400000236# $Id$
#
# >>Title::     Bug Tracking Module
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 20-Feb-97 ianc    SDF 2.000
#                   (With lots of initial from Tim Hudson)
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{MOD:bugtrack}} is an [[SDF]] module for
# building a simple bug tracking system.
#
# >>Description::
#
# >>Limitations::
#

# This is the ordered list of attributes at the top of each details file
# Bug tracking systems can change the order or set of attributes
# supported by defining this variable before using this module
!default BUG_ATTRIBUTES 'Status,Priority,Type'

# Define the "bugs" class
!class bugs 'BUG,BUGTITLE'; 'Code,Title'; "Jump,$var{'BUG_ATTRIBUTES'}"

# Define the hypertext generation rules
!on phrase 'BUG';; $attr{'jump'}="$text.html"
!on phrase 'BUGTITLE';; $attr{'jump'}=$obj_long{'bugs',$text,'Code'} . ".html"

# Macro to construct the title for a bug description.
# If a title is supplied, a warning is output if it does not
# match the title in the database.
!block script
@_bug_title_MacroArgs = (
    'Name       Type        Default     Rule',
    'title      string      _NULL_',
);
sub bug_title_Macro {
    local(%arg) = @_;
    local(@text);
    local($title, $db_title);
    local($code);

    # Check the title matches the database
    $title = $arg{'title'};
    $code = $var{'FILE_BASE'};
    $db_title = &Value('bugs', $code, 'Title');
    if ($title eq '') {
        $title = $db_title;
    }
    elsif ($title ne $db_title) {
        &'AppMsg("warning", "bug title does not match database value");
    }

    # Build result
    @text = (
        "!define DOC_NAME '$code - $title'",
        "!define DOC_TOC 0",
        "!build_title",
        "!subsections 'Description,Action'; 'noprefix'",
        "!namevalues 'bugs'; '$code'; BUG_ATTRIBUTES");

    # Return result
    return @text;
}
!endblock
sdf-2.001/perllib/sdf/home/stdlib/sdf_dir.sdr010064400042570001753000000027110632232565600206720ustar00iancmtr00000400000236# $Id$
#
# >>Title::     SDF Directory Report
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 07-Apr-97 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# This report generates a directory (tree) of the components (files)
# included in an SDF document.
#
# >>Description::
#
# >>Limitations::

# >>Resources::
#
# >>Implementation::
#


# Report state
$sdf_dir_level = 0;
@sdf_dir_output = ();

# Report event routine
sub sdf_dir_ReportEvent {
    local($event) = @_;
#   local();
    local($file);

    # We're only interested in the _bof_ and _eof_ macros
    next unless $event eq 'macro';
    if ($name eq '_bof_') {
        $file = $args;
        $file =~ s/'//g;
        if ($file eq $var{'DOC_SHORT'}) {
            $sdf_dir_level = 0;
            @sdf_dir_output = ("N:{{A[jump='$file']$file}} components:");
        }
        else {
            $file =~ s#^\./##;
            $sdf_dir_level++;
            push(@sdf_dir_output, "L$sdf_dir_level" . "[jump='$file'] $file")
                if $file =~ /\.sdf$/;
        }
    }
    elsif ($name eq '_eof_') {
        $sdf_dir_level--;
    }
}

# Report end routine
sub sdf_dir_ReportEnd {
    return @sdf_dir_output;
}

# package return value
1;
sdf-2.001/perllib/sdf/home/stdlib/testcase.sdm010064400042570001753000000057210633202247000210570ustar00iancmtr00000400000236# $Id$
#
# >>Title::     Testcase Module
#
# >>Copyright::
# Copyright (c) 1996-1997, Tim Hudson (tjh@mincom.com)
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 01-May-97 ianc    Replaced with tjh's latest version
# 24-Apr-97 ianc    Added revision history
# 22-Apr-97 prachin Fixed bug caused by SDF now using Perl 5.x
# 19-Jun-96 tjh     Initial writing
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{MOD:testcase}} is the [[SDF]] module for
# building test documentation.
#
# >>Description::
#
# >>Limitations::
#

#
# testcase support ... generates a table at the end of the document
#		       created from the A3: testcasename in each block
#

!on filter "testcases";; \
        $name='simple'; \
        $params.=';pre="!testcaseStart"'; \
        $params.=';post="!testcaseEnd"'

!block script

# control testcase debug stuff
$testcase_debug=0;

# set if you want tests inserted inline or leave set to zero 
# to have them output at the end of the document
$testcase_inline=0;

# gathers all the data for the output until the end of the document
@testcases_output;

# a single testcase table data
@testcases;

$testcase_first=1;

sub testcase_add
{
    local($text)=@_;

    print STDERR "TESTCASE:>$text\n" if ($testcase_debug);

    push(@testcases,$text);
}

sub testcaseStart_Macro
{
    local(@text);

    print STDERR "TESTCASE Start $topic\n" if ($testcase_debug);
    @testcases=();

    if ($testcase_first) {
        push(@text,"!block end","!testcaseEndOfDocument","!endblock");
        $testcase_first=0;
        @testcases_output=("P1[notoc] Test Results");
    }

    push(@text,'!on paragraph "A3";testcase; &testcase_add($text);');

    return (@text);
}

sub testcaseEnd_Macro
{
    local(@text);

    print STDERR "TESTCASE End $topic\n" if ($testcase_debug);

    @text=();

# Ian is going to freak out when he sees what I am doing here with 
# tables to implement "keep" --tjh
    push(@text,
#"!block table; noheadings; style=\"plain\"",
#"One",
#"<<",
"!keep on",
"P2[notoc] $topic",
"",
"!block table; noheadings; objects=\"B,N,B\"; style=\"plain\"; format='25,45,10,20'",
"Name            Value                               Name2       Value2",
"Tester:         ___________________________         Date:       __________",
"!endblock",
"",
"!block table; style=\"grid\"; format=\"50,40,10\"",
"Test_Case:Comments:Pass"
    );

    for $test (@testcases) {
        push(@text,$test);
    }

    push(@text,
"!endblock",
"!keep off",
#">>",
#"!endblock"
);

    if ($testcase_inline) {
        unshift(@text,"!off paragraph testcase","PB:");
	return(@text);
    } else {
        push(@testcases_output,@text);
        return("!off paragraph testcase");
    }
}

sub testcaseEndOfDocument_Macro
{
    print STDERR "TESTCASE EndOfDocument\n" if ($testcase_debug);

    return (@testcases_output);
}

!endblock
sdf-2.001/perllib/sdf/home/stdlib/langdefs.sdm010064400042570001753000000207120661521633200210320ustar00iancmtr00000400000236# $Id$
#
# >>Title::     Language Definitions Module
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 12-Oct-98 ianc    fixed Java keywords, removed case-sensitive names,
#                   improved Perl keywords (thanks to Colin Jitlal)
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{MOD:langdefs}} defines language definitions used in [[SDF]]
# documents.
#
# >>Description::
# Language names are case insensitive.
#
# >>Limitations::
#

!block langdefs
# For SDF, treat the built-in macros as keywords.
# We also need to put all the keywords on one line to get around
# parsing problems related to lines beginning with !.
sdf|sdm|sds|sdn|sdl|sde:\
    :cb=#:ce=$:sb=":se=\e":lb=':\
    :le=\e':\
    :kw=!build_title !block !endblock !include !execute !import !use !inherit !on !off !if !elsif !elseif !else !endif !init !define !default !undef !restrict !export !class !macro !endmacro !message !line !script !insert !getdoc !getcode !getusage !perlapi

# From the Perl FAQ
# The list of keywords is taken from cperl-mode.el
perl|pl|pm|sdp|sdr:\
    :pb=^\d?(sub|package)\d\p\d:\
    :bb={:be=}:cb=#:ce=$:sb=":se=\e":lb=':\
    :le=\e':tl:\
    :id=_:\
    :kw=\
           AUTOLOAD BEGIN DESTROY END __END__ chomp \
           chop defined delete do each else elsif \
           eval exists for foreach format goto \
           grep if keys last local map my next \
           no package pop pos print printf push \
           q qq qw qx redo return scalar shift \
           sort splice split study sub tie tr \
           undef unless unshift untie until use \
           while y \
           CORE __FILE__ __LINE__ abs accept alarm \
           and atan2 bind binmode bless caller \
           chdir chmod chown chr chroot close \
           closedir cmp connect continue cos crypt \
           dbmclose dbmopen die dump endgrent \
           endhostent endnetent endprotoent endpwent \
           endservent eof eq exec exit exp fcntl \
           fileno flock fork formline ge getc \
           getgrent getgrgid getgrnam gethostbyaddr \
           gethostbyname gethostent getlogin \
           getnetbyaddr getnetbyname getnetent \
           getpeername getpgrp getppid getpriority \
           getprotobyname getprotobynumber getprotoent \
           getpwent getpwnam getpwuid getservbyname \
           getservbyport getservent getsockname \
           getsockopt glob gmtime gt hex index int \
           ioctl join kill lc lcfirst le length \
           link listen localtime log lstat lt \
           mkdir msgctl msgget msgrcv msgsnd ne \
           not oct open opendir or ord pack pipe \
           quotemeta rand read readdir readline \
           readlink readpipe recv ref rename require \
           reset reverse rewinddir rindex rmdir seek \
           seekdir select semctl semget semop send \
           setgrent sethostent setnetent setpgrp \
           setpriority setprotoent setpwent setservent \
           setsockopt shmctl shmget shmread shmwrite \
           shutdown sin sleep socket socketpair \
           sprintf sqrt srand stat substr symlink \
           syscall sysread system syswrite tell \
           telldir time times truncate uc ucfirst \
           umask unlink unpack utime values vec \
           wait waitpid wantarray warn write x xor

# From Kent Sandvik (sandvik@sgi.com) and Sect 3.9 of the language spec.
# Note: null and super are treated as keywords.
java:\
        :pb=^\d?*?\d?\p\d?\(\a?\)(\d|{):bb={:be=}:cb=/*:ce=*/:ab=//:\
        :ae=$:sb=":se=\e":lb=':\
        :le=\e':tl:\
        :kw=abstract boolean break byte case catch char class const continue\
        default do double else extends final finally float for goto\
        if implements import instanceof int interface long native new null\
        package private protected public return short\
        static super switch synchronized this throw throws transient try\
        void volatile while

# From Prachin Ranavat (prachin@mincom.com)
c:\
    :pb=^\d?*?\d?\p\d?\(\a?\)(\d|{):bb={:be=}:cb=/*:ce=*/:sb=":se=\e":lb=':\
    :le=\e':tl:\
    :kw=asm auto break case char continue default do double else enum\
    extern float for fortran goto if int long register return short\
    sizeof static struct switch typedef union unsigned void while #define\
    #else #endif #if #ifdef #ifndef #include #undef # define endif\
    ifdef ifndef include undef defined:

c++|cpp|hpp|cc|h:\
    :pb=^\d?*?\d?\p\d?\(\a?\)(\d|{):bb={:be=}:cb=/*:ce=*/:ab=//:\
    :ae=$:sb=":se=\e":lb=':\
    :le=\e':tl:\
    :kw=asm auto break case char continue default do double else enum\
    extern float for fortran goto if int long register return short\
    sizeof static struct switch typedef union unsigned while void #define\
    #else #endif #if #ifdef #ifndef #include #undef # define endif\
    ifdef ifndef include undef defined\
    catch class const delete friend inline new operator overload private\
    protected public throw try virtual:

# Note: extensible is a Visibroker extension to the OMG standard
idl:\
	:pb=^\d?*?\d?\p\d?\(\a?\)(\d|{):bb={:be=}:cb=/*:ce=*/:ab=//:\
	:ae=$:sb=":se=\e":lb=':\
	:le=\e':tl:\
	:kw=any attribute boolean case char const context default double\
	enum exception extensible float in inout interface long module octet oneway\
	out raises readonly sequence short string struct switch typedef\
	unsigned union void FALSE Object TRUE #define #undef #include #if\
	#ifdef #ifndef #elif #else #endif #defined #error #pragma:

fortran|f77|fc|f|for:\
    :pb=(function|subroutine|program)\d\p\d?\(\a?\):\
    :bb=(function|subroutine|program)\d\p\d?\(\a?\):be=^\dend:\
    :cb=^c:\
    :ce=$:\
    :sb=':\
    :se=':\
    :oc:\
    :kw=call common complex continue dimension do double else elseif\
    end endif equivalence format function\
    goto if include integer \
    parameter precision real return stop subroutine:

delphi|pascal|pas|int:\
    :pb=(^\d?procedure|function|program\d\p\d|\(|;|\:)|(=\d?record\d):\
    :bb=\dcase|begin\d:be=\dend|forward\d|;:\
    :cb={:ce=}:\
    :ab=\(*:ae=*\):\
    :sb=':se=':\
    :kw=absolute abstract and array as asm assembler at begin case cdcel\
    class const constructor default destructor div do downto dynamic else\
    end except export exports external far file finally for forward\
    function goto if implementation in index inherited initialization\
    inline interface interrupt is label library messages mod name near\
    nil nodefault not object of on or override packed private procedure\
    program property protected public published raise read record repeat\
    resident set shl shr stored string then to try type unit until uses\
    var virtual while with write xor

sh:\
    :pb=(;|^)\d?\p\(\)(\d|{):\
    :ab=\$#:ae=(\d?|\a?):\
    :bb={:be=}:cb=#:ce=$:sb=":se=\e":lb=':\
    :le=\e':tl:\
    :kw=break case cd continue do done \
    elif else esac eval exec exit export \
    fi for if in then while until \
    read readonly set shift test trap umask wait:

csh:\
    :cb=#:ce=$:sb=":se=\e":lb=':\
    :ab=\$\a?#:ae=(\d?|\a?):\
    :le=\e':tl:\
    :kw=alias alloc break breaksw case cd chdir continue default\
    echo else end endif endsw exec exit foreach \
    glob goto history if logout nice nohup onintr repeat set\
    setenv shift source switch then time \
    while umask unalias unset wait while @ env \
    argv child home ignoreeof noclobber noglob \
    nomatch path prompt shell status verbose :

# From Programming Python
python|jpython|py:\
        :pb=^\d?\p\d?\(\a?\)(\d|\:):cb=""":ce=""":ab=#:\
        :ae=$:sb=":se=\e":lb=':\
        :le=\e':tl:\
        :kw=print del pass break continue return raise import from \
            global access exec in if elif else while for try finally \
            except class def or and not is lambda:

# TJH added in a quick set of COBOL things ... why not!
cobol:\
    :ab=*:ae=$:
    :kw=SECTION CALL PERFORM VARYING FROM BY UNTIL\
    IF END-IF ELSE NOT LESS AND OR EQUAL COMPUTE ADD SUBTRACT\
    MOVE TO EXIT SEARCH DIVISION AUTHOR GO TO GOTO\
    PIC COMP COMP-5 STRING PROGRAM-ID
mimscobol|pcom|precom:\
    :ab=*:ae=$:
    :kw=SECTION CALL PERFORM VARYING FROM BY UNTIL\
    IF END-IF ELSE NOT LESS AND OR EQUAL COMPUTE ADD SUBTRACT\
    MOVE TO EXIT SEARCH DIVISION AUTHOR GO TO GOTO\
    PIC COMP COMP-5 STRING PROGRAM-ID\
    EXEC END-EXEC MACRO MEND
!endblock
sdf-2.001/perllib/sdf/home/stdlib/txt.sdn010064400042570001753000000024300640470130200200540ustar00iancmtr00000400000236# $Id$
#
# >>Title::     Text Tuning
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 14-May-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# The {{stdlib/txt.sdn}} module defines [[SDF]] configuration details for
# generating plain text files.
#
# >>Description::
#
# >>Limitations::
#

# Set the margin
!default TXT_MARGIN OPT_WIDTH

# Make TXT a restricted variable family
!restrict 'TXT'

# Declare document variables
!block variables; family="TXT"; export
Name                        Type            Rule
MARGIN                      integer
HDG_UL_OFF                  boolean
!endblock

# Define paragraph styles
!block parastyles
Name        To                      Attributes
!endblock

# Define phrase styles
!block phrasestyles
Name    To
!endblock

# Default build_title output
!macro build_txt_cover
P1: [[DOC_TITLE]]
!if DOC_STATUS
N: [[DOC_ID]] ([[DOC_STATUS]])
!elsif DOC_ID
N: [[DOC_ID]]
!endif
!if DOC_AUTHOR
N: [[join(", ", grep(/\w/, @var{'DOC_AUTHOR', 'DOC_AUTHOR2', 'DOC_AUTHOR3'}))]]
!endif
!endmacro
sdf-2.001/perllib/sdf/home/stdlib/usecases.sdm010064400042570001753000000050640645436626400211000ustar00iancmtr00000400000236# $Id$
#
# >>Title::     Use Case Module
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 17-Dec-97 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{MOD:usecases}} is an [[SDF]] module for
# managing Use Cases.
#
# >>Description::
# You can customise this module's behavior
# by defining the following variables before using this module:
#
# * {{UC_ATTRIBUTES}} - the comma-separated list of attributes
#   at the top of each details file
# * {{UC_SUBSECTIONS}} - the comma-separated list of subsections
#   at the top of each details file.
#
# >>Limitations::
#

!default UC_ATTRIBUTES    'Version,Status'
!default UC_SUBSECTIONS   'Purpose,Actors,Scenario,Special Requirements,Related Use Cases'

# Define the classes
!class usecases 'UC,UCTITLE'; 'Code,Title'; "Jump,$var{'UC_ATTRIBUTES'}"
!class actors   'ACT';        'Name,Description'

# Define the hypertext generation rules
!on phrase 'UC';; $attr{'jump'}="$text.html"
!on phrase 'UCTITLE';; $attr{'jump'}=$obj_long{'usecases',$text,'Code'} . ".html"

!block script

sub usecases_Jump_Value {
    local($name) = @_;
#   local($result);

    return "$name.html";
}

sub usecases_Value {
    local($attr, $name) = @_;
#   local($result);

    return AttrToFile($attr, $name, 'usecases');
}

# Macro to construct the title for a details file.
# If a title is supplied, a warning is output if it does not
# match the title in the database.
@_uc_title_MacroArgs = (
    'Name       Type        Default     Rule',
    'title      string      _NULL_',
);
sub uc_title_Macro {
    local(%arg) = @_;
    local(@text);
    local($title, $db_title);
    local($code);

    # Check the title matches the database
    $title = $arg{'title'};
    $code = $var{'FILE_BASE'};
    $db_title = &Value('usecases', $code, 'Title');
    if ($title eq '') {
        $title = $db_title;
    }
    elsif ($title ne $db_title) {
        &'AppMsg("warning", "usecase title does not match database value");
    }

    # Build result
    @text = (
        "!define DOC_NAME '$code. $title'",
        "!define DOC_TOC 0",
        "!build_title",
        "!if UC_SUBSECTIONS",
        "!subsections UC_SUBSECTIONS; 'noprefix'",
        "!endif",
        "!if UC_ATTRIBUTES",
        "!namevalues 'usecases'; '$code'; UC_ATTRIBUTES",
        "!endif");

    # Return result
    return @text;
}
!endblock
sdf-2.001/perllib/sdf/home/stdlib/delphi.sdm010064400042570001753000000425650630272440000205170ustar00iancmtr00000400000236# $Id$
#
# >>Title::     Delphi Module
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
#                   (With lots of initial work from Tim Hudson)
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{MOD:delphi}} is the [[SDF]] module for
# the building {{PRD:Delphi}} documentation.
#
# >>Description::
# A {{very}} nice way of doing [[Delphi]] help without having to
# jump through major hoops and still be able to get {{great}}
# hardcopy documentation. Beat that!
#
# >>Limitations::
# TJH notes:
#    * still lots of work to do in controlling table formatting stuff
#      where we don't yet have things such that we can squish things
#      as nicely as we need ... too much whitespace 
#    * I'd like to be able to say ... take all SpBefore and SpAfter 
#      down by 50% or something like that.
#
# Some outstanding issues:
# * How do we jump to topics inside the standard Delphi help files?
# * Should H2s be H3s so that H2 can be reserved for the optional level
#   shown in the Delphi library reference?
# * What's the best way of extracting properties, etc., from the code:
#   - How are 'key' entities marked?
#   - How are parent classes found?
#   - How often do we 'go to file' vs 'access the cache'?
#

# grab things not yet "installed" in the kernel modules
!use "misc.sdm"

# Load the images library
!inherit "images"

# Make 'delphi' a filter for formatting source code
!on filter 'delphi';; $name='example'; $params .= ';lang="Delphi"'

# Define the new paragraph attributes
!block paraattrs
Name
delphi_unit
delphi_image
!endblock

#
# On a level heading, delphi_unit triggers some nice things:
# * for help, the unit is prepended before the next heading
# * otherwise, the unit name is added to the heading.
#
#
!if $var{'OPT_TARGET'} eq 'hlp'
    !on paragraph '[HAP]\d';; $delphi_unit = $attr{'delphi_unit'}
    !on paragraph '[HAP]\d';; \
        if ($delphi_unit) {\
            &PrependText("$style: Unit", "N:{{UNIT:$delphi_unit}}");\
            $delphi_unit = '';\
        }
!else
    #!on paragraph '[HAP]\d';; $attr{'label'} = $attr{'delphi_unit'};\
    #    $attr{'mif.NumAtEnd'} = 1
    !on paragraph '[HAP]\d';; \
        if ($attr{'delphi_unit'} ne '') {\
            $text .= " (" . $attr{'delphi_unit'} . ")";\
        }
!endif

# these should be moved into the images library?
# At the moment, we use IMPORT for paper-based stuff to force 'inline'
# importing, rather than 'below' importing.
!define IMG_ARROW "{{IMPORT:arrow}}"
!define IMG_KEY   "{{IMPORT:key}}"

# Control the font mapping so that things are by default in
# "normal" Delphi mode ... which the user can override where
# they see fit!

!if $var{'OPT_TARGET'} eq 'hlp'

    # Just the entities in the contents
    !on paragraph '[HAP][2-9]';; $attr{'notoc'} = 1

    # all top level headings are blue for Delphi-style help!
    !on paragraph '[HAP]1';; $attr{'color'} = 'Blue';

    # Delphi help is always in a nice "Arial" font ... 
    !on paragraph ;; $attr{'family'} = 'Arial';
    !on phrase ;; $attr{'family'} = 'Arial';

    # 12 point for headers ...
    !on paragraph '[HAP]1';; $attr{'size'} = '12 pt'; $attr{'bold'} = '1';

    # 19 point for second level headers ...
    !on paragraph '[HAP]2';; $attr{'size'} = '10 pt'; $attr{'bold'} = '1';

    # 10 point by default for everything else
    !on paragraph '';; $attr{'size'} = '10 pt';

    # Make Tasks and Example separate topics
    !on paragraph '[HAP]2';; \
        if ($text eq 'Tasks' || $text eq 'Example') {\
            $attr{'top'} = 1;\
            $attr{'id'} = "jump_${topic}_$text";\
        }

!else

    # Start level 1 headings on a new page (and make plain)
    !on paragraph '[HAP]1';; $style =~ tr/HA/PP/; $attr{'top'} = 1

    # Remove level 2+ headings from the contents (and make plain)
    !on paragraph '[HA][2-9]';; $style =~ tr/HA/PP/; $attr{'notoc'} = 1

    # For PostScript output, the 'Description' heading gets junked.
    !if $var{'OPT_TARGET'} eq 'ps'
        !on paragraph '[HAP]2';; if ($text eq 'Description') \
            {$text = ""; %attr = ('sp_before', '0 pt')}
    !endif
!endif



# Commonly used phrase styles
!block phrasestyles
Name            To
CLASS           =1
COMP            =1
EVENT           =1
EXCEPT          =1
FUNC            =1
METH            =1
OBJ             =1
PROC            =1
PROP            =1
TYPE            =1
UNIT            =1
VAR             =1
!endblock

################# Hypertext Generation Stuff #####################


# Declare short <-> long mapping tables
!block script
%delphi_s2l = (
    'class',        'class',
    'comp',         'component',
    'event',        'event',
    'except',       'exception',
    'func',         'function',
    'meth',         'method',
    'obj',          'object',
    'proc',         'procedure',
    'prop',         'property',
    'type',         'type',
    'unit',         'unit',
    'var',          'variable',
);
%delphi_l2s = (
    'class',        'class',    
    'component',    'comp',     
    'event',        'event',    
    'exception',    'except',
    'function',     'func',     
    'method',       'meth',     
    'object',       'obj',      
    'procedure',    'proc',     
    'property',     'prop',     
    'type',         'type',     
    'unit',         'unit',     
    'variable',     'var',
);

sub _DelphiGenerateHyperText {
    local($tmp, $group, $prefix);

    $tmp = $style;
    $tmp =~ tr/A-Z/a-z/;
    $prefix = '';
    if ($text =~ /\./) {
        ($group, $text) = split(/\./, $text, 2);
        unless (defined($_delphi_groups{$group})) {
            &'AppMsg("warning", "unknown delphi group '$group'");
        }
        $prefix = $_delphi_groups{$group};
    }
    $attr{'jump'} = $prefix . "#${tmp}_$text";
}
!endblock

# Generate hypertext jumps
!on phrase 'CLASS|COMP|EVENT|EXCEPT|FUNC|METH|OBJ|PROC|PROP|TYPE|UNIT|VAR';; \
    &_DelphiGenerateHyperText()

# Generate hypertext targets
!on paragraph '[HAP][12]';; \
    ($tmp1, $tmp2) = split(/\s+/, $text, 2); \
    $tmp2 =~ tr/A-Z/a-z/; \
    $tmp2 = $delphi_l2s{$tmp2}; \
    $attr{'id'} = "${tmp2}_$tmp1" if $tmp2


################# Filters #####################

!block script

# Table of "groups" - a logical name for a jump prefix
%_delphi_groups = ();

# delphi_groups - table of logical group names and matching jump prefixes
@_delphi_groups_FilterParams = ();
@_delphi_groups_FilterModel = &'TableParse(
    'Field      Category    Rule',
    'Name       key',
    'Prefix     optional',
);
sub delphi_groups_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &'TableValidate(*tbl, *_delphi_groups_FilterModel);

    # Process the data
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);
        $_delphi_groups{$values{'Name'}} = $values{'Prefix'};
    }
}

# delphi_properties - table of properties for a Delphi class
@_delphi_properties_FilterParams = ();
@_delphi_properties_FilterModel = &'TableParse(
    'Field      Category    Rule',
    'Name       key',
    'Key        optional    ',
    'RO         optional    '
);
sub delphi_properties_Filter {
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($line_count,$row_count,@items);
    local($row,$line,$pos);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &'TableValidate(*tbl, *_delphi_properties_FilterModel);

    # Sort the data
    @tbl = &'TableSort(*tbl, 'Name');

    # Get the line and row counts
    (@flds) = &'TableFields(shift @tbl);
    $line_count=scalar(@tbl);
    $row_count=int(($line_count+2)/3);
    #print STDERR "LINE_COUNT $line_count ROW_COUNT $row_count\n";

    # Build the section "header"
    if ($var{'OPT_TARGET'} eq 'hlp') {
        push(@text,
            "!block hlp_window",
            "!squish on ; ",
            "H2[notoc;hlp.topic='jump_${topic}_Properties'] Properties",
            "!block table; noheadings;style=\"plain\";format=\"3,30,6,27\"",
            "1a|1b|2a|2b",
            "[[IMG_ARROW]]|{{B:Run-time only}}|[[IMG_KEY]]|{{B:Key properties}}",
            "!endblock",
            "!block table; noheadings;style='plain';" .
              "tags=',,PROP,,,PROP,,,PROP';format=\"2,6,25,2,6,25,2,6,25\"",
            "1a|1b|1c|2a|2b|2c|3a|3b|3c"
            );
    } else {
        push(@text,
            "P2[notoc] Properties",
            "!block table; noheadings;style='plain';" .
              "tags=',,PROP,,,PROP,,,PROP';format=\"2,6,25,2,6,25,2,6,25\"",
            "1a|1b|1c|2a|2b|2c|3a|3b|3c"
        );
    }

    # Process the data
    @items = ();
    for($line=0;$line<$row_count;$line++) {
      $item='';
      for($row=0;$row<3;$row++) {
        # access in the right location
        # alphabetically down with three cols
        $pos=$line+($row*$row_count);
        if ($pos>$line_count) {
          $rec='';
          #print STDERR "TBL[$line,$row,$pos]=\n";
        } else {
          $rec=$tbl[$pos];
          #print STDERR "TBL[$line,$row,$pos]=$rec\n";
        }
        %values = &'TableRecSplit(*flds, $rec);

        # divide into a three column table ...
        if ($values{'RO'}) {
            $item .= "[[IMG_ARROW]]|";
        } else {
            $item .= "|";
        }
        if ($values{'Key'}) {
            $item .= "[[IMG_KEY]]|";
        } else {
            $item .= "|";
        }
        if ($values{'Name'}) {
            $item .= "$values{'Name'}";
        } else {
            $item .= "";
        }
        $item .= "|" if ($row<2);
      }
      push(@items, $item);
    }

    # Let the reader know if there are none
    @items = ('||None.') if $line_count == 0;

    # add in the table body
    push(@text,@items);

    push(@text,"!endblock");
    if ($var{'OPT_TARGET'} eq 'hlp') {
        push(@text, "!endblock", "!squish off");
    }

    #print STDERR "Properties:\n" . join("\n",@text);

}


# delphi_methods - table of methods for a Delphi class
@_delphi_methods_FilterParams = ();
sub delphi_methods_Filter {
    local(*text, %param) = @_;

    &_delphi_keytable(*text, 'Methods');
}

# delphi_events - table of events for a Delphi class
@_delphi_events_FilterParams = ();
sub delphi_events_Filter {
    local(*text, %param) = @_;

    &_delphi_keytable(*text, 'Events');
}

# generic processing for methods & events
@_delphi_keytable_FilterModel = &'TableParse(
    'Field      Category    Rule',
    'Name       key',
    'Key        optional    '
);
sub _delphi_keytable {
    local(*text, $label) = @_;
#   local();
    local($lc_label);
    local($tags_value);
    local(@tbl, @flds, $rec, %values);
    local($line_count,$row_count,@items);
    local($row,$line,$pos);

    # Get a lower-case version of the label
    $lc_label = $label;
    $lc_label =~ tr/A-Z/a-z/;

    # Gets the value of the tags parameter
    if ($label eq 'Methods') {
        $tags_value = ',,METH,,,METH,,,METH';
    }
    else {
        $tags_value = ',,EVENT,,,EVENT,,,EVENT';
    }

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &'TableValidate(*tbl, *_delphi_keytable_FilterModel);

    # Sort the data
    @tbl = &'TableSort(*tbl, 'Name');

    # Get the line and row counts
    (@flds) = &'TableFields(shift @tbl);
    $line_count=scalar(@tbl);
    $row_count=int(($line_count+2)/3);
    #print STDERR "LINE_COUNT $line_count ROW_COUNT $row_count\n";

    # Build the section "header"
    if ($var{'OPT_TARGET'} eq 'hlp') {
        unshift(@text,
            "!block hlp_window",
            "!squish on ; ",
            "H2[notoc;hlp.topic='jump_${topic}_$label'] $label",
            "!block table; noheadings;style=\"plain\";format=\"6,27\"",
            "1a|1b",
            "[[IMG_KEY]]|{{B:Key $lc_label}}",
            "!endblock",
            "!block table; noheadings;style='plain';" .
              "tags='$tags_value';format=\"2,6,25,2,6,25,2,6,25\"",
            "1a|1b|1c|2a|2b|2c|3a|3b|3c"
            );
    } else {
        push(@text,
            "P2[notoc] $label",
            "!block table; noheadings;style='plain';" .
              "tags='$tags_value';format=\"2,6,25,2,6,25,2,6,25\"",
            "1a|1b|1c|2a|2b|2c|3a|3b|3c"
        );
    }

    # Process the data
    @items = ();
    for($line=0;$line<$row_count;$line++) {
      $item='';
      for($row=0;$row<3;$row++) {
        # access in the right location
        # alphabetically down with three cols
        $pos=$line+($row*$row_count);
        if ($pos>$line_count) {
          $rec='';
          #print STDERR "TBL[$line,$row,$pos]=\n";
        } else {
          $rec=$tbl[$pos];
          #print STDERR "TBL[$line,$row,$pos]=$rec\n";
        }
        %values = &'TableRecSplit(*flds, $rec);

        # method/event doesn't have the RO field but does still
        # use the same table formatting ... cute huh!
        $item .= "|";

        if ($values{'Key'}) {
            $item .= "[[IMG_KEY]]|";
        } else {
            $item .= "|";
        }
        if ($values{'Name'}) {
            $item .= "$values{'Name'}";
        } else {
            $item .= "";
        }

        $item .= "|" if ($row<2);

      }
      push(@items, $item);
    }

    # Let the reader know if there are none
    @items = ('||None.') if $line_count == 0;

    # add in the table body
    push(@text,@items);

    push(@text,"!endblock");
    if ($var{'OPT_TARGET'} eq 'hlp') {
        push(@text, "!endblock", "!squish off");
    }

    #print STDERR "Methods:\n" . join("\n",@text);

}

# delphi_see_also - a table of related entities
@_delphi_see_also_FilterParams = ();
@_delphi_see_also_FilterModel = &'TableParse(
    'Field      Category    Rule',
    'Name       key',
    'Category   optional    '
);
sub delphi_see_also_Filter {
    local(*text, %param) = @_;
#   local();
    local(@tbl, @flds, $rec, %values);
    local($item, @items, $style);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &'TableValidate(*tbl, *_delphi_see_also_FilterModel);

    # Process the data
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);
        if ($values{'Category'}) {
            $style = $delphi_l2s{$values{'Category'}};
            $style =~ tr/a-z/A-Z/;
            $item = "{{$style: $values{'Name'}}} $values{'Category'}";
        } else {
            $item = "{{JUMP: $values{'Name'}}}";
        }
        push(@items, $item);
    }

    # Format the output
    if ($var{'OPT_TARGET'} eq 'hlp') {
        @text = (
            "!squish on ; ",
            "!block hlp_window",
            "H2[id='jump_${topic}_See also']See also",
            grep(s/^/N:/, @items),
            "!endblock",
            "!squish off"
        );
    }
    else {
        @text = ("H2:See also", "N:" . join(", ", @items));
    }

    #print STDERR "See Also:\n" . join("\n",@text);
}

# delphi_components - table of components for a Delphi unit
@_delphi_components_FilterParams = ();
sub delphi_components_Filter {
    local(*text, %param) = @_;

    &_delphi_list(*text, 'Components', 'COMP');
}

# delphi_objects - table of objects for a Delphi unit
@_delphi_objects_FilterParams = ();
sub delphi_objects_Filter {
    local(*text, %param) = @_;

    &_delphi_list(*text, 'Objects', 'OBJ');
}

# delphi_types - table of types for a Delphi unit
@_delphi_types_FilterParams = ();
sub delphi_types_Filter {
    local(*text, %param) = @_;

    &_delphi_list(*text, 'Types', 'TYPE');
}

# delphi_routines - table of routines for a Delphi unit
@_delphi_routines_FilterParams = ();
sub delphi_routines_Filter {
    local(*text, %param) = @_;

    &_delphi_list(*text, 'Routines', 'FUNC');
}

# delphi_exceptions - table of exceptions for a Delphi unit
@_delphi_exceptions_FilterParams = ();
sub delphi_exceptions_Filter {
    local(*text, %param) = @_;

    &_delphi_list(*text, 'Exceptions', 'EXCEPT');
}

# delphi_variables - table of variables for a Delphi unit
@_delphi_variables_FilterParams = ();
sub delphi_variables_Filter {
    local(*text, %param) = @_;

    &_delphi_list(*text, 'Variables', 'VAR');
}

# generic processing for components, objects, types and routines
@_delphi_list_FilterModel = &'TableParse(
    'Field      Category    Rule',
    'Name       key',
    'Style      optional',
);
sub _delphi_list {
    local(*text, $label, $style) = @_;
#   local();
    local(@tbl, @flds, $rec, %values);
    local($item_style, $item, @items);

    # Parse and validate the data
    @tbl = &'TableParse(@text);
    @text = ();
    &'TableValidate(*tbl, *_delphi_list_FilterModel);

    # Sort the data
    @tbl = &'TableSort(*tbl, 'Name');

    # Process the data
    (@flds) = &'TableFields(shift @tbl);
    for $rec (@tbl) {
        %values = &'TableRecSplit(*flds, $rec);
        $item_style = $values{'Style'} ne '' ? $values{'Style'} : $style;
        $item = "{{$item_style: $values{'Name'}}}";
        push(@items, $item);
    }

    # Format the output
    if ($var{'OPT_TARGET'} eq 'hlp') {
        @text = (
            "!squish on ; ",
            "H2:$label",
            grep(s/^/N:/, @items),
            "N:",
            "!squish off"
        );
    }
    else {
        @text = ("H2:$label", "N:" . join(", ", @items));
    }
}

!endblock

{
    local(*text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($line_count,$row_count,@items);
    local($row,$line,$possdf-2.001/perllib/sdf/home/stdlib/defines.sdm010064400042570001753000000052230633203027000206530ustar00iancmtr00000400000236# $Id$
#
# >>Title::     Defines Module
#
# >>Copyright::
# Copyright (c) 1996-1997, Tim Hudson (tjh@mincom.com)
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# ??-???-96 tjh     Initial writing
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{MOD:defines}} is the [[SDF]] module for
# simplifying the definition of products and sections.
#
# >>Description::
# This contains the following interesting uses of the "simple" filter:
#
# * product_defines - given a data table with two pipe (|) separated
#                     columns defines for each product are automatically
#                     created. 
# * section_defines - define section names as variables
#
# For example:
#
# !block example
# !block product_defines
# product1:url1
# product2:url2
# !endblock
# !endblock
# 
# becomes
#
# !block example
# !block products; data
# Name:Jump
# product1:url1
# product2:url2
# !endblock
# !define product1 "{{PRD:product1}}"
# !define product2 "{{PRD:product2}}"
# !endblock
#
# which lets you use the neat syntax of [\[product1]\] and [\[product2]\] to
# refer to products and get the hypertext links inserted appropriately.
#
# >>Limitations::
#

#
# product defines  ... adds a filter product_defines that takes a 
#                      "normal" products block and adds in a define
#                      for each product
#
!on filter "product_defines";; \
        $name='simple'; \
        $params.=';pre="!block products data#Name|Jump"'; \
        $params.=';exec="&AddProduct(\$line)"'; \
        $params.=';post="!endblock#!DefineProducts"'

!on filter "section_defines";; \
        $name='simple'; \
        $params.=";exec='\"!define \$line \\\"{{SECT:\$line}}\\\"\"'";

!block script

@products=();

sub AddProduct {
        local ($line)=@_;

        if ($simple_debug) {
            print STDERR "AddProduct: $line\n";
        }

        $line =~ s/\[\[(.*)\]\]/$var{$1}/g;

        ($prod,$value)=split(/\|/,$line,2);

        # do simple variable substitution so that we can
        # use [[VAR]] in lots of places that are useful
        # even when building more complex things
        #$value =~ s/\[\[(.*)\]\]/$var{$1}/g;

        push(@products,$prod);

        return $line;
}

sub DefineProducts_Macro {
        local(@text);

        if ($simple_debug) {
            print STDERR "DefineProducts -> " . join(",",@products) . "\n";
        }

        for $prod (@products) {
                push(@text,"!define $prod \"{{PRD:$prod}}\"");
        }

        return (@text);
}
!endblock
sdf-2.001/perllib/sdf/home/stdlib/objects.sdm010064400042570001753000000066510647530447600207210ustar00iancmtr00000400000236# $Id$
#
# >>Title::     Common Objects Module
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{objects.sdm}} defines objects commonly referenced in [[SDF]]
# documents.
#
# >>Description::
#
# >>Limitations::
#

# Commonly referenced organisations
!block organisations; data
Name            Long                                    Jump
Adobe           Adobe Systems Incorporated              http://www.adobe.com
Apple           Apple Computer, Incorporated            http://www.apple.com
Borland         Borland International, Incorporated     http://www.borland.com
DEC             Digital Equipment Corporation           http://www.dec.com
Frame           Frame International                     http://www.frame.com
HP              Hewlett Packard                         http://www.hp.com
IBM             International Business Machines         http://www.ibm.com
Mincom          Mincom Pty Ltd                          http://www.mincom.com
Microsoft       Microsoft Corporation                   http://www.microsoft.com
OMG             Object Management Group                 http://www.omg.org
SUN             Sun Microsystems Computer Corporation   http://www.sun.com
X/Open          X/Open Company Ltd                      http://www.xopen.org
!endblock

# Make them variables too
!define Adobe           "{{ORG:Adobe}}"
!define Apple           "{{ORG:Apple}}"
!define Borland         "{{ORG:Borland}}"
!define DEC             "{{ORG:DEC}}"
!define Frame           "{{ORG:Frame}}"
!define HP              "{{ORG:HP}}"
!define IBM             "{{ORG:IBM}}"
!define Mincom          "{{ORG:Mincom}}"
!define Microsoft       "{{ORG:Microsoft}}"
!define OMG             "{{ORG:OMG}}"
!define SUN             "{{ORG:SUN}}"
!define X_Open          "{{ORG:X/Open}}"

# Commonly referenced products
# (Thanks to Chris Moran for most of the Jump values.)
!block products; data
Name            Jump
CORBA           http://www.omg.org/corba.htm
Delphi          http://www.borland.com/Product/Lang/delphi2/
FrameMaker      http://www.frame.com/PRODUCTS/Products.doc.html
FrameViewer     http://www.frame.com
HTML            http://www.w3.org/hypertext/WWW/MarkUp/
Java            http://java.sun.com/
MIMS            http://www.mincom.com/mims
Perl            http://www.perl.com/perl/index.html
PostScript      http://www.adobe.com
SimpleDoc       http://www.mincom.com/mtr/simpledoc/
Unix            http://www.cis.ohio-state.edu/hypertext/faq/usenet/unix-faq/faq/top.html
Windows         http://www.microsoft.com/windows
Word            http://www.microsoft.com/msword/default.htm
!endblock

# Make them variables too
!define CORBA           "{{PRD:CORBA}}"
!define Delphi          "{{PRD:Delphi}}"
!define FrameMaker      "{{PRD:FrameMaker}}"
!define FrameViewer     "{{PRD:FrameViewer}}"
!define HTML            "{{PRD:HTML}}"
!define Java            "{{PRD:Java}}"
!define MIMS            "{{PRD:MIMS}}"
!define Perl            "{{PRD:Perl}}"
!define PostScript      "{{PRD:PostScript}}"
!define SimpleDoc       "{{PRD:SimpleDoc}}"
!define Unix            "{{PRD:Unix}}"
!define Windows         "{{PRD:Windows}}"
!define Word            "{{PRD:Word}}"
sdf-2.001/perllib/sdf/home/look/004075500042570001753000000000000672243772400162375ustar00iancmtr00000400000236sdf-2.001/perllib/sdf/home/look/simple/004075500042570001753000000000000672243775200175315ustar00iancmtr00000400000236sdf-2.001/perllib/sdf/home/look/simple/pages.sdm010064400042570001753000000036550640440517200213270ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Pages Module
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 08-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{pages}} is an [[SDF]] module containing configuration data
# common to styles in the {{simple}} look.
#
# >>Description::
#
# >>Limitations::
#

# Load the standard header/footer stuff
!use "stdlib/pages"

############### PAGE LAYOUTS ##################

# Define the margins. For pages >= 8 inches, a wider outer margin is used.
!define OPT_MARGIN_TOP      '0.5in'
!define OPT_MARGIN_BOTTOM   '0.5in'
!define OPT_MARGIN_INNER    '1.0in'
!define OPT_MARGIN_OUTER    $var{'DOC_PAGE_WIDTH'} >= 576 ? '1.0in' : '0.5in'

# Define the first page layout
# (no header and no borders on the footer)
!define PAGE_FIRST_HEADER_BORDER ''
!define PAGE_FIRST_HEADER_HEIGHT '0.00in'
!define PAGE_FIRST_HEADER_GAP    '0.00in'
!define PAGE_FIRST_FOOTER_BORDER ''
!define PAGE_FIRST_FOOTER_HEIGHT '0.50in'
!define PAGE_FIRST_FOOTER_GAP    '0.25in'

# Define the right page layout
!define PAGE_RIGHT_HEADER_HEIGHT  '0.40in'
!define PAGE_RIGHT_HEADER_GAP     '0.30in'
!define PAGE_RIGHT_FOOTER_HEIGHT  '0.50in'
!define PAGE_RIGHT_FOOTER_GAP     '0.25in'

# Define the header/footer borders
!macro build_borders
!if $var{'OPT_BORDERS'} == 0
!define PAGE_RIGHT_HEADER_BORDER  ''
!define PAGE_RIGHT_FOOTER_BORDER  ''
!elsif $var{'OPT_BORDERS'} == 1
!define PAGE_RIGHT_HEADER_BORDER  "bottom=0.25"
!define PAGE_RIGHT_FOOTER_BORDER  "top=0.25"
!else
!define PAGE_RIGHT_HEADER_BORDER  "top=0.25,bottom=0.25"
!define PAGE_RIGHT_FOOTER_BORDER  "top=0.25"
!endif
!endmacro

# Define the sidehead details
!define OPT_SIDEHEAD_WIDTH "30pt"
!define OPT_SIDEHEAD_GAP   "6pt"
sdf-2.001/perllib/sdf/home/look/simple/admin.sds010064400042570001753000000033650632040505000213140ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Admin Style
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 09-Jan-97 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{admin}} is an [[SDF]] style for administration documents (e.g. memos).
#
# >>Description::
#
# >>Limitations::
#

# Build the borders
!default OPT_BORDERS 2
!build_borders

# Define the number of header/footer lines
!default OPT_HEADINGS 2

# Provide defaults for variables used in the header/footer
!default DOC_URL   ''
!default DOC_OWNER 'The author'

# Define the first page footer
!define PAGE_FIRST_FOOTER_INNER1  ''
!define PAGE_FIRST_FOOTER_INNER2  ''
!define PAGE_FIRST_FOOTER_CENTER1 ''
!define PAGE_FIRST_FOOTER_CENTER2 ''
!define PAGE_FIRST_FOOTER_OUTER1  ''
!define PAGE_FIRST_FOOTER_OUTER2  ''

# Define the right page header
!define PAGE_RIGHT_HEADER_INNER1   '[[$var{"DOC_PROJECT"}]]'
!define PAGE_RIGHT_HEADER_INNER2   ''
!define PAGE_RIGHT_HEADER_CENTER1  ''
!define PAGE_RIGHT_HEADER_CENTER2  ''
!define PAGE_RIGHT_HEADER_OUTER1   '{{B:[[$var{"DOC_TITLE"}]]}}'
!define PAGE_RIGHT_HEADER_OUTER2   ''

# Define the right page footer
!define PAGE_RIGHT_FOOTER_INNER1   FULL:DOC_MODIFIED
!define PAGE_RIGHT_FOOTER_INNER2   '[[DOC_URL]]'
!define PAGE_RIGHT_FOOTER_CENTER1  "Copyright [[c]] [[YEAR:DOC_START]], [[DOC_OWNER]]"
!define PAGE_RIGHT_FOOTER_CENTER2  ''
!define PAGE_RIGHT_FOOTER_OUTER1   "{{PAGENUM:}} of {{PAGECOUNT:}}"
!define PAGE_RIGHT_FOOTER_OUTER2   ''

# Build the left page as a mirror of the right page
!left_mirror_right_page
sdf-2.001/perllib/sdf/home/look/simple/mif.sdn010064400042570001753000001042730636603141200210010ustar00iancmtr00000400000236# $Id$
#
# >>Title::	MIF Tuning (simple look)
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 01-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# The {{simple/mif.sdn}} module provides the mif objects required for
# the simple look.
#
# >>Description::
#
# >>Limitations::
#

# Inherit the standard configuration
!use 'stdlib/mif.sdn'

################ Useful constants ###################

# Define useful list indent values
!define _LI1 $var{'OPT_LIST_INDENT'}*1 . "pt"
!define _LI2 $var{'OPT_LIST_INDENT'}*2 . "pt"
!define _LI3 $var{'OPT_LIST_INDENT'}*3 . "pt"
!define _LI4 $var{'OPT_LIST_INDENT'}*4 . "pt"
!define _LI5 $var{'OPT_LIST_INDENT'}*5 . "pt"
!define _LI6 $var{'OPT_LIST_INDENT'}*6 . "pt"

# Define center and right tabs
# (Should the right tab use AREA_WIDTH?)
!define _TABC $var{'DOC_FULL_WIDTH'}/2 . "pt"
!define _TABR $var{'DOC_FULL_WIDTH'} . "pt"

# Define the size of the side area and the indent for attributes
!define _SIDE      $var{'OPT_SIDEHEAD_WIDTH'} + $var{'OPT_SIDEHEAD_GAP'}
!define _AT_INDENT ($var{'_SIDE'} >= 90 ? $var{'_SIDE'} : 90) . "pt"
!define _SIDE      $var{'_SIDE'} . "pt"

# Set the default font size
!default _BASE_SIZE 12


################ Mapping tables ###################

!block parastyles
Name        To                      Attributes

# normal paragraphs
N           b0_Body
FIRST       f0_FirstBody
L1          l0_ListBody
L2          l1_ListBody
L3          l2_ListBody
L4          l3_ListBody
L5          l4_ListBody
L6          l5_ListBody

# headings
H1          h1_Heading
H2          h2_Heading
H3          h3_Heading
H4          h4_Heading
H5          h5_Heading
H6          h5_Heading
P1          p1_PlainHeading
P2          p2_PlainHeading
P3          p3_PlainHeading
P4          p4_PlainHeading
P5          p5_PlainHeading
P6          p5_PlainHeading
A1          a1_Appendix
A2          a2_Appendix
A3          a3_Appendix
A4          a4_Appendix
A5          a5_Appendix
A6          a5_Appendix

# heading numbers
H1NUM       hn_HeadingNum
A1NUM       an_AppendixNum

# list items
LU1         u0_Unordered
LU2         u1_Unordered
LU3         u2_Unordered
LU4         u3_Unordered
LU5         u4_Unordered
LU6         u5_Unordered
LF1         oi0_OrderedInit
LF2         oi1_OrderedInit
LF3         oi2_OrderedInit
LF4         oi3_OrderedInit
LF5         oi4_OrderedInit
LF6         oi5_OrderedInit
LN1         on0_OrderedNext
LN2         on1_OrderedNext
LN3         on2_OrderedNext
LN4         on3_OrderedNext
LN5         on4_OrderedNext
LN6         on5_OrderedNext
LI1         li0_ListItem
LI2         li1_ListItem
LI3         li2_ListItem
LI4         li3_ListItem
LI5         li4_ListItem
LI6         li5_ListItem

# Miscellaneous
Addr        ad_Address
E           e0_Example
E80         e0_Example80
FA          fa_FigureAnchor
FT          ft_FigureTitle
GL          gl_Glossary
GLT         gh_GlossaryHeading
GLD         f0_FirstBody
Note        no_Note
NB          nb_NoteBegin
NE          ne_NoteEnd
NV          at_Attribute
Line        li_Line
PB          pb_PageBreak
Sign        ce_CorrEnd
TA          ta_TableAnchor
TT          tt_TableTitle
HEADER      Header
FOOTER      Footer

# Mapping of generated list title styles
TOCT        TocTitle
LOFT        LofTitle
LOTT        LotTitle
IXT         IndexTitle

# Paragraph styles for document headers
DDist       dd_DocDistr
DProj       dp_DocProject
DName       dn_DocName
DType       dt_DocType
DStat       ds_DocStatus
DCode       dc_DocCode
DSkip       dk_DocSkip
DCopy       dy_DocCopy
DActn       da_DocAction
DAuth       du_DocAuthor
DAppr       dw_DocWho
DEnd        ed_EndDocument

# Old paragraph styles
ET          et_ExampleTitle
L           l0_ListBody
RE          re_Reference
SI          si_StepInit
SN          sn_StepNext
ST          st_StepTitle

# Old paragraph styles for title page of correspondence
## THESE ARE NO LONGER SUPPORTED ##
#cAttn       ca_CorrAttention
#cAttn2      ca_CorrAttention2
#cCopy       cc_CorrCopy
#cCopy2      cc_CorrCopy2
#cDate       cd_CorrDate
#cEnd        ce_CorrEnd
#cFrom       cf_CorrFrom
#cLine       cl_CorrLine
#cPages      cp_CorrPageCount
#cRef        cr_CorrRefNo
#cSubj       cs_CorrSubject
#cTo         ct_CorrTo
#cTo2        ct_CorrTo2
#cFax        cx_CorrFax
#cComp       cy_CorrCompany
!endblock

# For component covers, we need to add the begin/end macros.
# Chapters and appendices also need a numbering paragraph prepended.
!if OPT_COMPONENT_COVER
!on paragraph '[HAP]1';; \
    &PrependText("${style}NUM:") if $style =~ /^[HA]/; \
    &PrependText('!DOC_COMPONENT_COVER_BEGIN'); \
    &AppendText ('!DOC_COMPONENT_COVER_END')
!endif

# Mapping of phrase styles
!block phrasestyles
Name    To

# Emphasis
A       Default
B       Bold
I       Italic
N       Normal
U       Underline
EX      Filename
JUMP    Jump
1       =I
2       =B
3       =U
ST      =2
Y       =2
SUB     Subscript
SUP     Superscript

# Typing
CMD     =2
DOC     =1
EMAIL   =1
FILE    =EX
ORG     =A
PRD     =A
REF     =A
SECT    =1
!endblock

# For hard-copy, format jumps as italics
!if $var{'OPT_TARGET'} eq 'ps'
!block phrasestyles
Name    To
JUMP    =I
URL     =I
!endblock
!endif

# For help, make jumps come out "as-is"
!if $var{'OPT_TARGET'} eq 'hlp'
!block phrasestyles
Name    To
JUMP    =A
!endblock
!endif

# Mapping of table styles
!block tablestyles
Name    To
columns Columns
rows    Rows
grid    Grid
plain   Plain
box     Box
shade   Shade
!endblock


################ Core paragraph formats ###################

# Define the root 'Para' format
!targetobject "Para"; "b0_Body";; \
  AcrobatLevel=0; \
  Alignment=Left; \
  AutoNum=0; \
  BlockSize=2; \
  BotSepAtIndent=0; \
  BotSepOffset='0.0"'; \
  BotSeparator=""; \
  CellAlignment=Top; \
  CellBMarginFixed=0; \
  CellLMarginFixed=0; \
  CellMargins="0.0 pt 0.0 pt 0.0 pt 0.0 pt"; \
  CellRMarginFixed=0; \
  CellTMarginFixed=0; \
  FIndent='0.0"'; \
  FIndentOffset='0.0"'; \
  FIndentRelative=0; \
  FontAngle=Regular; \
  FontCase="FAsTyped"; \
  FontChangeBar=0; \
  FontColor=Black; \
  FontDW="0.0%"; \
  FontDX="0.0%"; \
  FontDY="0.0%"; \
  FontFamily=Times; \
  FontLocked=0; \
  FontOutline=0; \
  FontOverline=0; \
  FontPairKern=Yes; \
  FontPosition="FNormal"; \
  FontSeparation=0; \
  FontShadow=0; \
  FontSize="$var{'_BASE_SIZE'} pt"; \
  FontStrike=0; \
  FontUnderlining="FNoUnderlining"; \
  FontVar=Regular; \
  FontWeight=Regular; \
  HyphenMaxLines=2; \
  HyphenMinPrefix=3; \
  HyphenMinSuffix=3; \
  HyphenMinWord=5; \
  Hyphenate=0; \
  LIndent='0.0"'; \
  Language="UKEnglish"; \
  Leading="2.0 pt"; \
  LetterSpace=0; \
  LineSpacing=Fixed; \
  Locked=0; \
  MaxWordSpace=110; \
  MinWordSpace=90; \
  NextTag=""; \
  OptWordSpace=100; \
  Placement=Anywhere; \
  PlacementStyle=Normal; \
  RIndent='0.0"'; \
  RunInDefaultPunct=". "; \
  SpAfter="6.0 pt"; \
  SpBefore="12.0 pt"; \
  TabStop=""; \
  TopSepAtIndent=0; \
  TopSepOffset='0.0"'; \
  TopSeparator=""; \
  UseNextTag=0; \
  WithNext=0; \
  WithPrev=0

# Define the other 'Para' formats
!targetobject "Para"; "f0_FirstBody"; "b0_Body"; \
  SpBefore="6.0 pt"

!targetobject "Para"; "fn_Footnote"; "b0_Body"; \
  BlockSize=1; \
  FontSize="10.0 pt"; \
  SpAfter="0.0 pt"; \
  SpBefore="3.0 pt"

!targetobject "Para"; "Footer"; "b0_Body"; \
  BlockSize=1; \
  FontPairKern=0; \
  FontFamily=Helvetica; \
  FontSize="10.0 pt"; \
  HyphenMinPrefix=2; \
  HyphenMinSuffix=2; \
  Hyphenate=0; \
  MaxWordSpace=125; \
  MinWordSpace=75; \
  SpAfter="0.0 pt"; \
  SpBefore="0.0 pt"; \
  TabStop="$var{'_TABC'}/Center,$var{'_TABR'}/Right"

!targetobject "Para"; "Header"; "Footer"; \
  FontFamily=Helvetica; \
  FontSize="10.5 pt"; \
  Leading="3.0 pt"


################ Heading paragraph formats ###################

!targetobject "Para"; "h1_Heading"; "b0_Body"; \
  AcrobatLevel=1; \
  AutoNum=Yes; \
  FontFamily=Helvetica; \
  FontSize="18.0 pt"; \
  FontWeight=Bold; \
  Hyphenate=0; \
  LIndent='0.5"'; \
  NumAtEnd=0; \
  NumFormat='H:.\\t'; \
  Placement="PageTop"; \
  PlacementStyle=Straddle; \
  SpAfter="8.0 pt"; \
  TabStop='0.5"'; \
  WithNext=Yes

!targetobject "Para"; "h2_Heading"; "h1_Heading"; \
  AcrobatLevel=4; \
  FontSize="14.0 pt"; \
  NumFormat='H:.\\t'; \
  Placement=Anywhere

!targetobject "Para"; "h3_Heading"; "h2_Heading"; \
  AcrobatLevel=7; \
  FontSize="12.0 pt"; \
  NumFormat='H:..\\t'

!targetobject "Para"; "h4_Heading"; "h3_Heading"; \
  AcrobatLevel=10; \
  AutoNum=0; \
  LIndent='0.0"'; \
  NumAtEnd=""; \
  NumFormat=""; \
  PlacementStyle=Normal; \
  TabStop=""

!targetobject "Para"; "h5_Heading"; "h4_Heading"; \
  AcrobatLevel=13; \
  FontSize="11.0 pt"; \
  Leading="3.0 pt"

!targetobject "Para"; "a1_Appendix"; "h1_Heading"; \
  NumFormat='A:.\\t'

!targetobject "Para"; "a2_Appendix"; "h2_Heading"; \
  NumFormat='A:.\\t'

!targetobject "Para"; "a3_Appendix"; "h3_Heading"; \
  NumFormat='A:..\\t'

!targetobject "Para"; "a4_Appendix"; "h4_Heading"

!targetobject "Para"; "a5_Appendix"; "h5_Heading"; \
  Leading="2.0 pt"; \
  SpAfter="7.0 pt"; \
  SpBefore="11.0 pt"

!targetobject "Para"; "p1_PlainHeading"; "h1_Heading"; \
  AutoNum=0; \
  LIndent='0.0"'; \
  NumAtEnd=""; \
  NumFormat=""; \
  TabStop=""

!targetobject "Para"; "p2_PlainHeading"; "h2_Heading"; \
  AutoNum=0; \
  LIndent='0.0"'; \
  NumAtEnd=""; \
  NumFormat=""; \
  TabStop=""

!targetobject "Para"; "p3_PlainHeading"; "h3_Heading"; \
  AutoNum=0; \
  LIndent='0.0"'; \
  NumAtEnd=""; \
  NumFormat=""; \
  PlacementStyle=Normal; \
  TabStop=""

!targetobject "Para"; "p4_PlainHeading"; "h4_Heading"

!targetobject "Para"; "p5_PlainHeading"; "h5_Heading"

# If a component cover page is requested, level 1 headings are
# preceded by a separate numbering paragraph, if appropriate
!if OPT_COMPONENT_COVER

!targetobject "Para"; "hn_HeadingNum"; "b0_Body"; \
  Alignment=Right; \
  AutoNum=Yes; \
  BotSeparator="CoverLine"; \
  FIndent="150 pt"; \
  FontFamily=Helvetica; \
  FontSize="36.0 pt"; \
  Leading="0.0 pt"; \
  NumAtEnd=0; \
  NumFormat='H:Chapter '; \
  NumberFont="Bold helvetica"; \
  PlacementStyle=Straddle; \
  SpAfter="7.0 pt"; \
  SpBefore="0.0 pt"

!targetobject "Para"; "an_AppendixNum"; "hn_HeadingNum"; \
  NumFormat='A:Appendix '

!targetobject "Para"; "h1_Heading"; "b0_Body"; \
  Alignment=Right; \
  FIndent="150 pt"; \
  FontFamily=Helvetica; \
  FontSize="33.0 pt"; \
  Leading="0.0 pt"; \
  LIndent="150 pt"; \
  PlacementStyle=Straddle; \
  SpAfter="1000.0 pt"; \
  SpBefore="0.0 pt"

!targetobject "Para"; "a1_Appendix";     "h1_Heading"
!targetobject "Para"; "p1_PlainHeading"; "h1_Heading"
!endif

# NoTOC versions for headings excluding from the contents
!targetobject "Para"; "h1_HeadingNoTOC"; "h1_Heading"; AcrobatLevel=0
!targetobject "Para"; "h2_HeadingNoTOC"; "h2_Heading"; AcrobatLevel=0
!targetobject "Para"; "h3_HeadingNoTOC"; "h3_Heading"; AcrobatLevel=0
!targetobject "Para"; "h4_HeadingNoTOC"; "h4_Heading"; AcrobatLevel=0
!targetobject "Para"; "h5_HeadingNoTOC"; "h5_Heading"; AcrobatLevel=0
!targetobject "Para"; "a1_AppendixNoTOC"; "a1_Appendix"; AcrobatLevel=0
!targetobject "Para"; "a2_AppendixNoTOC"; "a2_Appendix"; AcrobatLevel=0
!targetobject "Para"; "a3_AppendixNoTOC"; "a3_Appendix"; AcrobatLevel=0
!targetobject "Para"; "a4_AppendixNoTOC"; "a4_Appendix"; AcrobatLevel=0
!targetobject "Para"; "a5_AppendixNoTOC"; "a5_Appendix"; AcrobatLevel=0
!targetobject "Para"; "p1_PlainHeadingNoTOC"; "p1_PlainHeading"; AcrobatLevel=0
!targetobject "Para"; "p2_PlainHeadingNoTOC"; "p2_PlainHeading"; AcrobatLevel=0
!targetobject "Para"; "p3_PlainHeadingNoTOC"; "p3_PlainHeading"; AcrobatLevel=0
!targetobject "Para"; "p4_PlainHeadingNoTOC"; "p4_PlainHeading"; AcrobatLevel=0
!targetobject "Para"; "p5_PlainHeadingNoTOC"; "p5_PlainHeading"; AcrobatLevel=0


################ Generated list paragraph formats ###################

!if OPT_COMPONENT_COVER
!targetobject "Para"; "TocTitle"; "p1_PlainHeading"
!else
!targetobject "Para"; "TocTitle"; "b0_Body"; \
  Alignment=Center; \
  FontFamily=Helvetica; \
  FontSize="18.0 pt"; \
  FontWeight=Bold; \
  Hyphenate=0; \
  Placement="PageTop"; \
  PlacementStyle=Straddle; \
  SpAfter="8.0 pt"; \
  WithNext=Yes
!endif

!targetobject "Para"; "LofTitle"; "p2_PlainHeading"
!targetobject "Para"; "LotTitle"; "p2_PlainHeading"
!targetobject "Para"; "IndexTitle"; "TocTitle"

!targetobject "Para"; "h1_HeadingTOC"; "b0_Body"; \
  FontFamily=Helvetica; \
  FontWeight=Bold; \
  HyphenMinPrefix=2; \
  HyphenMinSuffix=2; \
  PlacementStyle=Straddle; \
  SpAfter="0.0 pt"; \
  SpBefore="4.0 pt"; \
  TabStop="0.5in,$var{'_TABR'}/Right/. "

!targetobject "Para"; "h2_HeadingTOC"; "h1_HeadingTOC"; \
  FontSize="11.0 pt"; \
  FontWeight=Regular; \
  SpBefore="2.0 pt"; \
  TabStop="0.75in,$var{'_TABR'}/Right/. "

!targetobject "Para"; "h3_HeadingTOC"; "h2_HeadingTOC"; \
  TabStop="1.0in,$var{'_TABR'}/Right/. "

!targetobject "Para"; "h4_HeadingTOC"; "h3_HeadingTOC"; \
  TabStop="1.25in,$var{'_TABR'}/Right/. "

!targetobject "Para"; "h5_HeadingTOC"; "h4_HeadingTOC"; \
  TabStop="1.5in,$var{'_TABR'}/Right/. "

!targetobject "Para"; "a1_AppendixTOC"; "h1_HeadingTOC"
!targetobject "Para"; "a2_AppendixTOC"; "h2_HeadingTOC"
!targetobject "Para"; "a3_AppendixTOC"; "h3_HeadingTOC"
!targetobject "Para"; "a4_AppendixTOC"; "h4_HeadingTOC"
!targetobject "Para"; "a5_AppendixTOC"; "h5_HeadingTOC"

!targetobject "Para"; "p1_PlainHeadingTOC"; "h1_HeadingTOC"
!targetobject "Para"; "p2_PlainHeadingTOC"; "h2_HeadingTOC"
!targetobject "Para"; "p3_PlainHeadingTOC"; "h3_HeadingTOC"
!targetobject "Para"; "p4_PlainHeadingTOC"; "h4_HeadingTOC"
!targetobject "Para"; "p5_PlainHeadingTOC"; "h5_HeadingTOC"

!targetobject "Para"; "LofTitleTOC"; "h2_HeadingTOC"
!targetobject "Para"; "LotTitleTOC"; "h2_HeadingTOC"
!targetobject "Para"; "IndexTitleTOC"; "h1_HeadingTOC"

!targetobject "Para"; "ft_FigureTitleLOF"; "b0_Body"; \
  LIndent='1.0"'; \
  MaxWordSpace=100; \
  MinWordSpace=100; \
  SpAfter="0.0 pt"; \
  SpBefore="2.0 pt"; \
  PlacementStyle=Straddle; \
  TabStop="0.5in,$var{'_TABR'}/Right/. "

!targetobject "Para"; "tt_TableTitleLOT"; "ft_FigureTitleLOF"

!targetobject "Para"; "GroupTitlesIX"; "b0_Body"; \
  Alignment="LeftRight"; \
  BlockSize=1; \
  FontPairKern=0; \
  FontWeight=Bold; \
  HyphenMinPrefix=2; \
  HyphenMinSuffix=2; \
  MaxWordSpace=125; \
  MinWordSpace=75; \
  SpAfter="0.0 pt"; \
  SpBefore="15.0 pt"; \
  WithNext=Yes

!targetobject "Para"; "IndexIX"; "GroupTitlesIX"; \
  Alignment=Left; \
  FontSize="12.0 pt"; \
  FontWeight=Regular; \
  Hyphenate=Yes; \
  SpBefore="0.0 pt"; \
  WithNext=0

!targetobject "Para"; "Level1IX"; "IndexIX"; \
  Alignment="LeftRight"; \
  LIndent='0.5"'

!targetobject "Para"; "Level2IX"; "Level1IX"; \
  FIndent='0.25"'; \
  FontSize="11.5 pt"; \
  LIndent='0.75"'


################ List paragraph formats ###################

!targetobject "Para"; "l0_ListBody"; "b0_Body"; \
  BlockSize=3; \
  FIndent=_LI1; \
  LIndent=_LI1; \
  SpAfter="8.0 pt"; \
  SpBefore="6.0 pt"

!targetobject "Para"; "l1_ListBody"; "l0_ListBody"; \
  FIndent=_LI2; \
  LIndent=_LI2

!targetobject "Para"; "l2_ListBody"; "l1_ListBody"; \
  FIndent=_LI3; \
  LIndent=_LI3

!targetobject "Para"; "l3_ListBody"; "l2_ListBody"; \
  FIndent=_LI4; \
  LIndent=_LI4

!targetobject "Para"; "l4_ListBody"; "l3_ListBody"; \
  FIndent=_LI5; \
  LIndent=_LI5

!targetobject "Para"; "l5_ListBody"; "l4_ListBody"; \
  FIndent=_LI6; \
  LIndent=_LI6

!targetobject "Para"; "li0_ListItem"; "b0_Body"; \
  BlockSize=3; \
  FontSize=$var{'_BASE_SIZE'} + 1 . " pt"; \
  SpAfter="8.0 pt"; \
  SpBefore="6.0 pt"

!targetobject "Para"; "li1_ListItem"; "li0_ListItem"; \
  FIndent=_LI1; \
  LIndent=_LI1

!targetobject "Para"; "li2_ListItem"; "li1_ListItem"; \
  FIndent=_LI2; \
  LIndent=_LI2

!targetobject "Para"; "li3_ListItem"; "li2_ListItem"; \
  FIndent=_LI3; \
  LIndent=_LI3

!targetobject "Para"; "li4_ListItem"; "li3_ListItem"; \
  FIndent=_LI4; \
  LIndent=_LI4

!targetobject "Para"; "li5_ListItem"; "li4_ListItem"; \
  FIndent=_LI5; \
  LIndent=_LI5

!targetobject "Para"; "u0_Unordered"; "b0_Body"; \
  AutoNum=Yes; \
  BlockSize=3; \
  LIndent=_LI1; \
  NumAtEnd=0; \
  NumFormat='\xa5 \\t'; \
  NumberFont="Bullet Symbol"; \
  SpBefore="6.0 pt"; \
  TabStop=_LI1

!targetobject "Para"; "u1_Unordered"; "u0_Unordered"; \
  NumFormat='\xd0 \\t'; \
  NumberFont=""; \
  FIndent=_LI1; \
  LIndent=_LI2; \
  TabStop=_LI2

!targetobject "Para"; "u2_Unordered"; "u0_Unordered"; \
  FIndent=_LI2; \
  LIndent=_LI3; \
  TabStop=_LI3

!targetobject "Para"; "u3_Unordered"; "u1_Unordered"; \
  FIndent=_LI3; \
  LIndent=_LI4; \
  TabStop=_LI4

!targetobject "Para"; "u4_Unordered"; "u2_Unordered"; \
  FIndent=_LI4; \
  LIndent=_LI5; \
  TabStop=_LI5

!targetobject "Para"; "u5_Unordered"; "u3_Unordered"; \
  FIndent=_LI5; \
  LIndent=_LI6; \
  TabStop=_LI6

!targetobject "Para"; "oi0_OrderedInit"; "u0_Unordered"; \
  NumFormat='L:.\\t'; \
  NumberFont=""; \
  SpAfter="0.0 pt"

!targetobject "Para"; "oi1_OrderedInit"; "oi0_OrderedInit"; \
  NumFormat='M:)\\t'; \
  FIndent=_LI1; \
  LIndent=_LI2; \
  TabStop=_LI2

!targetobject "Para"; "oi2_OrderedInit"; "oi1_OrderedInit"; \
  NumFormat='N:.\\t'; \
  FIndent=_LI2; \
  LIndent=_LI3; \
  TabStop=_LI3

!targetobject "Para"; "oi3_OrderedInit"; "oi2_OrderedInit"; \
  NumFormat='0:)\\t'; \
  FIndent=_LI3; \
  LIndent=_LI4; \
  TabStop=_LI4

!targetobject "Para"; "oi4_OrderedInit"; "oi3_OrderedInit"; \
  NumFormat='Q:.\\t'; \
  FIndent=_LI4; \
  LIndent=_LI5; \
  TabStop=_LI5

!targetobject "Para"; "oi5_OrderedInit"; "oi4_OrderedInit"; \
  NumFormat='R:)\\t'; \
  FIndent=_LI5; \
  LIndent=_LI6; \
  TabStop=_LI6

!targetobject "Para"; "on0_OrderedNext"; "oi0_OrderedInit"; \
  NumFormat='L:.\\t'

!targetobject "Para"; "on1_OrderedNext"; "oi1_OrderedInit"; \
  NumFormat='M:)\\t'

!targetobject "Para"; "on2_OrderedNext"; "oi2_OrderedInit"; \
  NumFormat='N:.\\t'

!targetobject "Para"; "on3_OrderedNext"; "oi3_OrderedInit"; \
  NumFormat='O:)\\t'

!targetobject "Para"; "on4_OrderedNext"; "oi4_OrderedInit"; \
  NumFormat='Q:.\\t'

!targetobject "Para"; "on5_OrderedNext"; "oi5_OrderedInit"; \
  NumFormat='R:)\\t'

!targetobject "Para"; "s0_SimpleList"; "l0_ListBody"
!targetobject "Para"; "s1_SimpleList"; "l1_ListBody"
!targetobject "Para"; "s2_SimpleList"; "l2_ListBody"
!targetobject "Para"; "s3_SimpleList"; "l3_ListBody"
!targetobject "Para"; "s4_SimpleList"; "l4_ListBody"
!targetobject "Para"; "s5_SimpleList"; "l5_ListBody"


################ Figure/table paragraph formats ###################

!targetobject "Para"; "fa_FigureAnchor"; "b0_Body"; \
  FontSize="2.0 pt"; \
  Leading="12.0 pt"; \
  SpAfter="0.0 pt"; \
  SpBefore="0.0 pt"

!targetobject "Para"; "ta_TableAnchor"; "fa_FigureAnchor"

!targetobject "Para"; "ft_FigureTitle"; "b0_Body"; \
  Alignment=Center; \
  AutoNum=Yes; \
  Hyphenate=0; \
  Leading="0.0 pt"; \
  NumAtEnd=0; \
  NumFormat='F:Figure . '; \
  SpAfter="18.0 pt"; \
  SpBefore="13.5 pt"

!targetobject "Para"; "tt_TableTitle"; "ft_FigureTitle"; \
  NumFormat='T:Table . '

!if OPT_NUMBER_PER_COMPONENT
!targetobject "Para"; "ft_FigureTitle"; "ft_FigureTitle"; \
  NumFormat='H:Figure -< \>. '
!targetobject "Para"; "tt_TableTitle"; "tt_TableTitle"; \
  NumFormat='H:Table -< \>. '
!endif

!targetobject "Para"; "CellBody"; "b0_Body"; \
  FontFamily=Helvetica; \
  FontSize="11.0 pt"; \
  SpAfter="2.0 pt"; \
  SpBefore="0.0 pt"; \
  TabStop='1.5",2.5",3.5",4.5",5.5"'

!targetobject "Para"; "CellGroup"; "CellBody"; \
  FontWeight=Bold

!targetobject "Para"; "CellHeading"; "CellGroup"

!targetobject "Para"; "tf_TableFootnote"; "ta_TableAnchor"; \
  BlockSize=1; \
  FIndent='0.1"'; \
  FontSize="10.0 pt"; \
  LIndent='0.1"'; \
  Leading="2.0 pt"; \
  RIndent='0.25"'; \
  SpBefore="3.0 pt"


################ Miscellaneous paragraph formats ###################

!targetobject "Para"; "e0_Example"; "b0_Body"; \
  BlockSize=4; \
  FontFamily=Courier; \
  FontPairKern=0; \
  FontSize="10.0 pt"; \
  Hyphenate=0; \
  Language="NoLanguage"; \
  Leading="0.0 pt"; \
  MaxWordSpace=100; \
  MinWordSpace=100; \
  SpAfter="0.0 pt"; \
  SpBefore="6.0 pt"; \
  TabStop='0.5",1.0",1.5",2.0",2.5",3.0",3.5"'

!targetobject "Para"; "e0_Example80"; "e0_Example"; \
  FontSize="9.4 pt"; \
  PlacementStyle=Straddle

!targetobject "Para"; "et_ExampleTitle"; "b0_Body"; \
  AutoNum=Yes; \
  BotSeparator="Table Rule"; \
  FIndent='0.1"'; \
  FontSize="11.0 pt"; \
  Hyphenate=0; \
  LIndent='0.1"'; \
  Leading="0.0 pt"; \
  NumAtEnd=0; \
  NumFormat='E:Example . '; \
  NumberFont=Bold; \
  SpAfter="18.0 pt"; \
  SpBefore="13.0 pt"

!targetobject "Para"; "gh_GlossaryHeading"; "b0_Body"; \
  FontFamily=Helvetica; \
  FontWeight=Bold; \
  Hyphenate=0; \
  SpAfter="8.0 pt"; \
  WithNext=Yes

!targetobject "Para"; "gl_Glossary"; "b0_Body"; \
  FontFamily=Helvetica; \
  FontSize="10.0 pt"; \
  LIndent='1.5"'; \
  SpAfter="2.0 pt"; \
  SpBefore="0.0 pt"; \
  TabStop='1.5"'

!targetobject "Para"; "li_Line"; "b0_Body"; \
  BotSeparator="Line"; \
  FontSize="2.0 pt"; \
  Leading="1.0 pt"; \
  SpAfter="0.0 pt"; \
  SpBefore="0.0 pt"

!targetobject "Para"; "nb_NoteBegin"; "b0_Body"; \
  AutoNum=Yes; \
  BlockSize=3; \
  NumAtEnd=0; \
  NumFormat='Note: '; \
  NumberFont=Bold; \
  SpBefore="6.0 pt"; \
  TabStop='0.7"'; \
  TopSeparator="Note Above"

!targetobject "Para"; "ne_NoteEnd"; "li_Line"; \
  BotSeparator="Note Below"

!targetobject "Para"; "no_Note"; "nb_NoteBegin"; \
  BotSeparator="Note Below"

!targetobject "Para"; "pb_PageBreak"; "b0_Body"; \
  Alignment=Right; \
  FontSize="4.0 pt"; \
  Hyphenate=0; \
  Leading="0.0 pt"; \
  PlacementStyle=Straddle; \
  SpAfter="999.0 pt"; \
  SpBefore="0.0 pt"

# This definition currently causes problems as SDF's escaping
# mechanisms cannot yet handle the embedded ] in the NumFormat attribute
#!targetobject "Para"; "re_Reference"; "b0_Body"; \
#  AutoNum=Yes; \
#  FontFamily=Helvetica; \
#  FontSize="10.0 pt"; \
#  Hyphenate=0; \
#  LIndent='0.5"'; \
#  NumAtEnd=0; \
#  NumFormat='R:[]\\t'; \
#  SpAfter="8.0 pt"; \
#  SpBefore="8.0 pt"; \
#  TabStop='0.5"'

!targetobject "Para"; "si_StepInit"; "oi0_OrderedInit"; \
  NumFormat='S:.\\t'; \
  NumberFont=Bold

!targetobject "Para"; "sn_StepNext"; "si_StepInit"; \
  NumFormat='S:.\\t'

!targetobject "Para"; "st_StepTitle"; "sn_StepNext"; \
  AutoNum=0; \
  FontWeight=Bold; \
  NumAtEnd=""; \
  NumFormat=''; \
  NumberFont=""; \
  TabStop='0.7"'


################ Cover page & title block paragraph formats ###################

!targetobject "Para"; "ad_Address"; "b0_Body"; \
  SpAfter="0.0 pt"; \
  SpBefore="0.0 pt"

!targetobject "Para"; "at_Attribute"; "b0_Body"; \
  AutoNum=Yes; \
  LIndent=_AT_INDENT; \
  NumAtEnd=0; \
  NumFormat='\\t'; \
  NumberFont='AttributeLabel'; \
  PlacementStyle=Straddle; \
  SpBefore="0.0 pt"; \
  TabStop=_AT_INDENT; \
  WithPrev=1

!targetobject "Para"; "ca_CorrAttention"; "b0_Body"; \
  AutoNum=Yes; \
  BlockSize=1; \
  FontSize="14.0 pt"; \
  Leading="3.0 pt"; \
  LineSpacing=Proportional; \
  NumAtEnd=0; \
  NumFormat='Attention:\\t'; \
  NumberFont=Bold; \
  PlacementStyle=Straddle; \
  SpAfter="0.0 pt"; \
  TabStop='1.0",2.75"'

!targetobject "Para"; "ca_CorrAttention2"; "ca_CorrAttention"; \
  AutoNum=0; \
  FIndent='1.0"'; \
  LIndent='1.0"'; \
  NumAtEnd=""; \
  NumFormat=''; \
  NumberFont=""; \
  SpBefore="2.0 pt"; \
  TabStop='2.75",4.5"'

!targetobject "Para"; "cc_CorrCopy"; "ca_CorrAttention2"; \
  AutoNum=Yes; \
  FIndent='0.0"'; \
  LIndent='0.0"'; \
  NumAtEnd=0; \
  NumFormat='Copy:\\t'; \
  NumberFont=Bold; \
  SpBefore="12.0 pt"; \
  TabStop='1.0",2.75001",4.5"'

!targetobject "Para"; "cc_CorrCopy2"; "cc_CorrCopy"; \
  AutoNum=0; \
  FIndent='1.0"'; \
  LIndent='1.0"'; \
  NumAtEnd=""; \
  NumFormat=''; \
  NumberFont=""; \
  SpBefore="2.0 pt"; \
  TabStop='2.75",4.5"'

!targetobject "Para"; "cd_CorrDate"; "cc_CorrCopy2"; \
  AutoNum=Yes; \
  FIndent='0.0"'; \
  LIndent='0.0"'; \
  NumAtEnd=0; \
  NumFormat='Date:\\t'; \
  NumberFont=Bold; \
  SpBefore="12.0 pt"; \
  TabStop='1.01915"'

!targetobject "Para"; "ce_CorrEnd"; "b0_Body"; \
  FontWeight=Bold; \
  SpAfter="4.0 pt"; \
  SpBefore="4.0 pt"

!targetobject "Para"; "cf_CorrFrom"; "b0_Body"; \
  AutoNum=Yes; \
  BlockSize=1; \
  FontSize="14.0 pt"; \
  Leading="3.0 pt"; \
  LineSpacing=Proportional; \
  NumAtEnd=0; \
  NumFormat='From:\\t'; \
  NumberFont=Bold; \
  PlacementStyle=Straddle; \
  SpAfter="0.0 pt"; \
  TabStop='1.0",2.75"'

!targetobject "Para"; "cp_CorrPageCount"; "b0_Body"; \
  AutoNum=Yes; \
  BlockSize=1; \
  FontSize="14.0 pt"; \
  Leading="3.0 pt"; \
  LineSpacing=Proportional; \
  NumAtEnd=0; \
  NumFormat='No. of Pages (including this one):\\t'; \
  NumberFont=Bold; \
  PlacementStyle=Straddle; \
  SpAfter="0.0 pt"; \
  TabStop='3.25"'

!targetobject "Para"; "cr_CorrRefNo"; "cp_CorrPageCount"; \
  NumFormat='Ref. No.:\\t'; \
  TabStop='1.0"'

!targetobject "Para"; "cs_CorrSubject"; "cr_CorrRefNo"; \
  LIndent='1.0"'; \
  NumFormat='Subject:\\t'; \
  RIndent='0.264"'

!targetobject "Para"; "ct_CorrTo"; "cs_CorrSubject"; \
  LIndent='0.0"'; \
  NumFormat='To:\\t'; \
  RIndent='0.0"'; \
  TabStop='1.0",2.75",4.5"'

!targetobject "Para"; "ct_CorrTo2"; "ct_CorrTo"; \
  AutoNum=0; \
  FIndent='1.0"'; \
  LIndent='1.0"'; \
  NumAtEnd=""; \
  NumFormat=''; \
  NumberFont=""; \
  SpBefore="2.0 pt"; \
  TabStop='2.75",4.5"'

!targetobject "Para"; "cx_CorrFax"; "ct_CorrTo2"; \
  AutoNum=Yes; \
  FIndent='0.0"'; \
  LIndent='0.0"'; \
  NumAtEnd=0; \
  NumFormat='Fax No.:\\t'; \
  NumberFont=Bold; \
  SpBefore="12.0 pt"; \
  TabStop='1.0"'

!targetobject "Para"; "cy_CorrCompany"; "cx_CorrFax"; \
  NumFormat='Company:\\t'

!targetobject "Para"; "da_DocAction"; "b0_Body"; \
  FontSize="14.0 pt"; \
  FontWeight=Bold; \
  PlacementStyle=Straddle; \
  SpAfter="10.0 pt"; \
  SpBefore="20.0 pt"

!targetobject "Para"; "dc_DocCode"; "da_DocAction"; \
  Alignment=Center; \
  AutoNum=Yes; \
  FontSize="18.0 pt"; \
  NumAtEnd=0; \
  NumFormat='Document No: '; \
  SpAfter="20.0 pt"

!targetobject "Para"; "dd_DocDistr"; "b0_Body"; \
  Alignment=Right; \
  FontAngle=Oblique; \
  FontFamily=Helvetica; \
  HyphenMinPrefix=2; \
  HyphenMinSuffix=2; \
  PlacementStyle=Straddle; \
  SpAfter="100.0 pt"

!targetobject "Para"; "dk_DocSkip"; "b0_Body"; \
  Alignment=Center; \
  FontSize="18.0 pt"; \
  FontWeight=Bold; \
  PlacementStyle=Straddle; \
  SpAfter="20.0 pt"; \
  SpBefore="20.0 pt"

!targetobject "Para"; "dn_DocName"; "dk_DocSkip"; \
  FontFamily=Helvetica; \
  TabStop='0.5",1.0",1.5",2.0",2.5",3.0",3.5"'

!targetobject "Para"; "dp_DocProject"; "dn_DocName"; \
  FontFamily=Times; \
  SpAfter="40.0 pt"; \
  SpBefore="0.0 pt"; \
  TabStop=""

!targetobject "Para"; "ds_DocStatus"; "dp_DocProject"; \
  SpAfter="60.0 pt"; \
  SpBefore="20.0 pt"

!targetobject "Para"; "dt_DocType"; "ds_DocStatus"; \
  SpAfter="20.0 pt"

!targetobject "Para"; "du_DocAuthor"; "dt_DocType"; \
  FontAngle=Oblique; \
  FontSize="12.0 pt"; \
  FontWeight=Regular; \
  SpAfter="10.0 pt"; \
  SpBefore="10.0 pt"

!targetobject "Para"; "dw_DocWho"; "dt_DocType"; \
  Alignment=Left; \
  AutoNum=Yes; \
  FIndent='0.25"'; \
  FontSize="12.0 pt"; \
  LIndent='0.25"'; \
  NumAtEnd=Yes; \
  NumFormat='............................ ....................'; \
  SpAfter="10.0 pt"; \
  SpBefore="10.0 pt"; \
  TabStop='2.0"'


!targetobject "Para"; "dy_DocCopy"; "dw_DocWho"; \
  Alignment=Center; \
  FIndent='0.0"'; \
  FontSize="18.0 pt"; \
  LIndent='0.0"'; \
  NumAtEnd=0; \
  NumFormat='Copy No: '; \
  SpAfter='20.0 pt'; \
  SpBefore="20.0 pt"; \
  TabStop=""


################ Phrase formats ###################

# Define the root 'Phrase' format
!targetobject "Phrase"; "Emphasis";; \
  Angle=Italic

# Define the other 'Phrase' formats
!targetobject "Phrase"; "Bold"; "Emphasis"; \
  Angle=""; \
  Weight=Bold

!targetobject "Phrase"; "Bold 9 pt"; "Bold"; \
  Size="9.0 pt"

!targetobject "Phrase"; "AttributeLabel"; "Bold"; \
  Family=Helvetica

!targetobject "Phrase"; "Bold helvetica"; "Bold"; \
  Family=Helvetica

!targetobject "Phrase"; "Bold italic"; "Emphasis"; \
  Weight=Bold

!targetobject "Phrase"; "Bullet Symbol"; "Emphasis"; \
  Angle=Regular; \
  Family=Courier; \
  Size="18.0 pt"; \
  Weight=Bold

!targetobject "Phrase"; "Callout"; "Bullet Symbol"; \
  Family=Times; \
  Size="10.0 pt"; \
  Weight=Regular

!targetobject "Phrase"; "DiagramBold"; "Bold"; \
  Family=Helvetica; \
  Size="11.0 pt"; \

!targetobject "Phrase"; "DiagramStd"; "DiagramBold"; \
  Weight=Regular

!targetobject "Phrase"; "Emphasis 9 pt"; "Emphasis"; \
  Size="9.0 pt"

!targetobject "Phrase"; "EquationVariables"; "Emphasis"

!targetobject "Phrase"; "Filename"; "Emphasis"; \
  Angle=Regular; \
  Family=Courier; \
  Size="9.4 pt"

!targetobject "Phrase"; "Italic"; "Emphasis"; \
  Weight=Regular

!targetobject "Phrase"; "Jump"; "Emphasis"; \
  Angle=""; \
  Color=Blue; \
  Separation=4

!targetobject "Phrase"; "Normal"; "Emphasis"; \
  Angle=Regular; \
  Weight=Regular

!targetobject "Phrase"; "Reference document"; "Emphasis"; \
  Family=Times; \
  Size="11.5 pt"; \
  Weight=Regular

!targetobject "Phrase"; "Run-In Heading"; "Emphasis"; \
  Angle=Regular; \
  Size="11.0 pt"; \
  Weight=Bold

!targetobject "Phrase"; "Subscript"; "Emphasis"; \
  Angle=""; \
  Position="FSubscript"

!targetobject "Phrase"; "Superscript"; "Subscript"; \
  Position="FSuperscript"

!targetobject "Phrase"; "Symbol"; "Emphasis"; \
  Angle=Regular; \
  Family=Symbol; \
  Weight=Regular

!targetobject "Phrase"; "Underline"; "Emphasis"; \
  Angle=""; \
  Underlining="FSingle"


################ Table formats ###################

# Define the root 'Table' format
!targetobject "Table"; "Format A";; \
  Alignment=Left; \
  AltShadePeriod=2; \
  BRuling=""; \
  BlockSize=2; \
  BodyColor=Black; \
  BodyFill=15; \
  BodyRowRuling=""; \
  BodySeparation=0; \
  CellMargins="6.0 pt 4.0 pt 6.0 pt 2.0 pt"; \
  ColumnRuling=""; \
  HFColor=Black; \
  HFFill=15; \
  HFRowRuling=""; \
  HFSeparation=0; \
  InitNumBodyRows=3; \
  InitNumColumns=3; \
  InitNumFRows=0; \
  InitNumHRows=1; \
  LIndent='0.117"'; \
  LRuling=""; \
  LastBRuling=0; \
  Locked=0; \
  NumByColumn=0; \
  Placement=Anywhere; \
  RIndent='0.0"'; \
  RRuling=""; \
  RulingPeriod=4; \
  SeparatorRuling=""; \
  ShadeByColumn=0; \
  ShadePeriod=2; \
  SpAfter="2.0 pt"; \
  SpBefore="12.0 pt"; \
  TRuling=Thin; \
  TitleGap="3.0 pt"; \
  TitlePlacement="InHeader"; \
  XColor=Black; \
  XColumnNum=1; \
  XColumnRuling=""; \
  XFill=15; \
  XRowRuling=""; \
  XSeparation=0

# Define the other 'Table' formats
!targetobject "Table"; "Box"; "Format A"; \
  BRuling=Thin; \
  BlockSize=4; \
  InitNumBodyRows=5; \
  LIndent='0.0"'; \
  LRuling=Thin; \
  RRuling=Thin; \
  SpBefore="4.0 pt"; \
  TitlePlacement=None

!targetobject "Table"; "Columns"; "Box"; \
  BRuling="Very Thin"; \
  ColumnRuling="Very Thin"; \
  LRuling="Very Thin"; \
  RRuling="Very Thin"; \
  SeparatorRuling="Very Thin"; \
  TRuling="Very Thin"; \
  XColumnRuling="Very Thin"

!targetobject "Table"; "Format B"; "Format A"; \
  SpBefore="4.0 pt"; \
  TRuling=""; \
  TitlePlacement=None

!targetobject "Table"; "Format IC1"; "Format A"; \
  BRuling=Medium; \
  BodyRowRuling="Very Thin"; \
  InitNumBodyRows=14; \
  InitNumColumns=2; \
  LIndent='0.55"'; \
  LRuling=Thin; \
  LastBRuling=Yes; \
  RRuling=Thin; \
  SeparatorRuling=Medium; \
  TRuling=Medium; \
  XColumnRuling=Thin; \
  XRowRuling="Very Thin"

!targetobject "Table"; "Grid"; "Format IC1"; \
  BRuling="Very Thin"; \
  BlockSize=4; \
  ColumnRuling="Very Thin"; \
  InitNumBodyRows=5; \
  InitNumColumns=3; \
  LIndent='0.0"'; \
  LRuling="Very Thin"; \
  LastBRuling=0; \
  RRuling="Very Thin"; \
  SeparatorRuling=Double; \
  SpBefore="4.0 pt"; \
  TRuling="Very Thin"; \
  TitlePlacement=None; \
  XColumnRuling="Very Thin"

!targetobject "Table"; "Plain"; "Format A"; \
  BlockSize=4; \
  InitNumBodyRows=5; \
  LIndent='0.0"'; \
  SpBefore="4.0 pt"; \
  TRuling=""; \
  TitlePlacement=None

!targetobject "Table"; "Rows"; "Plain"; \
  BRuling="Very Thin"; \
  BodyRowRuling="Very Thin"; \
  SeparatorRuling=Thin; \
  TRuling="Very Thin"; \
  XRowRuling="Very Thin"

!targetobject "Table"; "Shade"; "Rows"; \
  BodyRowRuling=""; \
  ColumnRuling="Very Thin"; \
  HFFill=5; \
  LRuling="Very Thin"; \
  RRuling="Very Thin"; \
  SeparatorRuling="Very Thin"; \
  XColumnRuling="Very Thin"; \
  XRowRuling=""

!targetobject "Table"; "Shade1"; "Shade"; \
  AltShadePeriod=1; \
  ShadePeriod=1; \
  XFill=6

!targetobject "Table"; "Shade2"; "Shade1"; \
  BRuling=Thin; \
  ColumnRuling=Thin; \
  HFFill=4; \
  LRuling=Thin; \
  RRuling=Thin; \
  SeparatorRuling=Thin; \
  TRuling=Thin; \
  XColumnRuling=Thin; \
  XFill=5

################ Generated lists ###################

!targetobject "List"; "TOC";; \
  Layout='<$paranumonly\>\\t<$paratext\>\\t<$pagenum\>'

!targetobject "List"; "LOF";; \
  Layout='<$paranum\>\\t<$paratext\>\\t<$pagenum\>'

!targetobject "List"; "LOT";; \
  Layout='<$paranum\>\\t<$paratext\>\\t<$pagenum\>'

# Note: the parameters below are not yet used, i.e. a special text flow for
# indexes is not yet generated as the default one is good enough for now.
!targetobject "Index"; "IX";; \
  Index='<$pagenum\>'; \
  SortSpec='<$symbols\><$numerics\><$alphabetics\>'; \
  Spec=' 1, 2-3'
  #GroupTitles='Symbols[\\ ];Numerics[0];A;B;C;D;E;F;G;H;I;J;K;L;M;N;O;P;Q;R;S;T;U;V;W;X;Y;Z'; \


# Give the index 2 columns, but no sidehead
!define OPT_IX_COLUMNS          2
!define OPT_IX_COLUMN_GAP       36
!define OPT_IX_SIDEHEAD_WIDTH   0
!define OPT_IX_SIDEHEAD_GAP     0

################ Reference page frames ###################

!targetobject "Frame"; "Footnote";; \
  Height=20; \
  PenWidth=0.25; \
  LineY=12; \
  LineLength=132

!targetobject "Frame"; "Line";; \
  Height=6; \
  PenWidth=0.2; \
  LineY=2; \
  LineLength=DOC_FULL_WIDTH

!targetobject "Frame"; "CoverLine";; \
  Height=6; \
  PenWidth=0.2; \
  LineX=150; \
  LineY=2; \
  LineLength=$var{'DOC_FULL_WIDTH'} - 150

!targetobject "Frame"; "Note Above";; \
  Height=6; \
  PenWidth=0.2; \
  LineY=2; \
  LineLength=DOC_FULL_WIDTH

!targetobject "Frame"; "Note Below"; "Note Above"

!targetobject "Frame"; "TableFootnote";; \
  Height=7; \
  PenWidth=0.25; \
  LineY=6; \
  LineLength=132


################ Special target formats ###################

# For rtf, use Word's standard style names
!if $var{'OPT_TARGET'} eq 'rtf'
!use 'rtf.sdn'
!endif

# For hlp, load the necessary configuration
!if $var{'OPT_TARGET'} eq 'hlp'
!use 'hlp.sdn'
!endif
tEnd=0; \
  NumFormat='From:\\t'; \
  NumberFont=Bold; \
  PlacementStyle=Straddle; \
  SpAfter="0.0 pt"; \
  TabStop='1.0",2.75"'

!targetobject "Para"; "cp_CorrPageCount"; "b0_Body"; \
  AutoNum=Yes; \
  BlockSize=1; \
  FontSize="14.0 pt"; \
  Leading="3.0 pt"; \
  LineSpacing=Proportional; \
  NumAtEnd=0; \
  NumFormat=sdf-2.001/perllib/sdf/home/look/simple/memo.sds010064400042570001753000000011350630323423200211550ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Memo Style
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 08-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{memo}} is an [[SDF]] style for memos.
#
# >>Description::
#
# >>Limitations::
#

# Use the admin style with an appropriate default title
!default DOC_TYPE "MEMORANDUM"
!use "admin.sds"
sdf-2.001/perllib/sdf/home/look/simple/mif.sdt.keep010064400042570001753000001047450636554644400217550ustar00iancmtr00000400000236# $Id$
#
# >>Title::	MIF Target (simple look)
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 01-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# The {{simple/mif.sdt}} module provides the mif objects required for
# the simple look.
#
# >>Description::
#
# >>Limitations::
#

# Inherit the standard configuration
!use 'stdlib/mif.sdt'

################ Useful constants ###################

# Define useful list indent values
!define _LI1 $var{'OPT_LIST_INDENT'}*1 . "pt"
!define _LI2 $var{'OPT_LIST_INDENT'}*2 . "pt"
!define _LI3 $var{'OPT_LIST_INDENT'}*3 . "pt"
!define _LI4 $var{'OPT_LIST_INDENT'}*4 . "pt"
!define _LI5 $var{'OPT_LIST_INDENT'}*5 . "pt"
!define _LI6 $var{'OPT_LIST_INDENT'}*6 . "pt"

# Define center and right tabs for the footer
!define _TABC $var{'DOC_FULL_WIDTH'}/2 . "pt"
!define _TABR $var{'DOC_FULL_WIDTH'} . "pt"

# Define the center tab for the header. If OPT_LONG_HEADERS is set,
# the center tab is put next to the left one, so that the right aligned
# bit of the header has as much space as it needs
!if OPT_LONG_HEADERS
!define _TABHC "1pt"
!else
!define _TABHC _TABC
!endif

# Define the size of the side area and the indent for attributes
!define _SIDE      $var{'OPT_SIDEHEAD_WIDTH'} + $var{'OPT_SIDEHEAD_GAP'}
!define _AT_INDENT ($var{'_SIDE'} >= 90 ? $var{'_SIDE'} : 90) . "pt"
!define _SIDE      $var{'_SIDE'} . "pt"

# Set the default font size
!default _BASE_SIZE 12


################ Mapping tables ###################

!block parastyles
Name        To                      Attributes

# normal paragraphs
N           b0_Body
FIRST       f0_FirstBody
L1          l0_ListBody
L2          l1_ListBody
L3          l2_ListBody
L4          l3_ListBody
L5          l4_ListBody
L6          l5_ListBody

# headings
H1          h1_Heading
H2          h2_Heading
H3          h3_Heading
H4          h4_Heading
H5          h5_Heading
H6          h5_Heading
P1          p1_PlainHeading
P2          p2_PlainHeading
P3          p3_PlainHeading
P4          p4_PlainHeading
P5          p5_PlainHeading
P6          p5_PlainHeading
A1          a1_Appendix
A2          a2_Appendix
A3          a3_Appendix
A4          a4_Appendix
A5          a5_Appendix
A6          a5_Appendix

# heading numbers
H1NUM       hn_HeadingNum
A1NUM       an_AppendixNum

# list items
LU1         u0_Unordered
LU2         u1_Unordered
LU3         u2_Unordered
LU4         u3_Unordered
LU5         u4_Unordered
LU6         u5_Unordered
LF1         oi0_OrderedInit
LF2         oi1_OrderedInit
LF3         oi2_OrderedInit
LF4         oi3_OrderedInit
LF5         oi4_OrderedInit
LF6         oi5_OrderedInit
LN1         on0_OrderedNext
LN2         on1_OrderedNext
LN3         on2_OrderedNext
LN4         on3_OrderedNext
LN5         on4_OrderedNext
LN6         on5_OrderedNext
LI1         li0_ListItem
LI2         li1_ListItem
LI3         li2_ListItem
LI4         li3_ListItem
LI5         li4_ListItem
LI6         li5_ListItem

# Miscellaneous
Addr        ad_Address
E           e0_Example
E80         e0_Example80
FA          fa_FigureAnchor
FT          ft_FigureTitle
GL          gl_Glossary
GLT         gh_GlossaryHeading
GLD         f0_FirstBody
Note        no_Note
NB          nb_NoteBegin
NE          ne_NoteEnd
NV          at_Attribute
Line        li_Line
PB          pb_PageBreak
Sign        ce_CorrEnd
TA          ta_TableAnchor
TT          tt_TableTitle
HEADER      Header
FOOTER      Footer

# Mapping of generated list title styles
TOCT        TocTitle
LOFT        LofTitle
LOTT        LotTitle
IXT         IndexTitle

# Paragraph styles for document headers
DDist       dd_DocDistr
DProj       dp_DocProject
DName       dn_DocName
DType       dt_DocType
DStat       ds_DocStatus
DCode       dc_DocCode
DSkip       dk_DocSkip
DCopy       dy_DocCopy
DActn       da_DocAction
DAuth       du_DocAuthor
DAppr       dw_DocWho
DEnd        ed_EndDocument

# Old paragraph styles
ET          et_ExampleTitle
L           l0_ListBody
RE          re_Reference
SI          si_StepInit
SN          sn_StepNext
ST          st_StepTitle

# Old paragraph styles for title page of correspondence
## THESE ARE NO LONGER SUPPORTED ##
#cAttn       ca_CorrAttention
#cAttn2      ca_CorrAttention2
#cCopy       cc_CorrCopy
#cCopy2      cc_CorrCopy2
#cDate       cd_CorrDate
#cEnd        ce_CorrEnd
#cFrom       cf_CorrFrom
#cLine       cl_CorrLine
#cPages      cp_CorrPageCount
#cRef        cr_CorrRefNo
#cSubj       cs_CorrSubject
#cTo         ct_CorrTo
#cTo2        ct_CorrTo2
#cFax        cx_CorrFax
#cComp       cy_CorrCompany
!endblock

# For component covers, we need to add the begin/end macros.
# Chapters and appendices also need a numbering paragraph prepended.
!if OPT_COMPONENT_COVER
!on paragraph '[HAP]1';; \
    &PrependText("${style}NUM:") if $style =~ /^[HA]/; \
    &PrependText('!DOC_COMPONENT_COVER_BEGIN'); \
    &AppendText ('!DOC_COMPONENT_COVER_END')
!endif

# Mapping of phrase styles
!block phrasestyles
Name    To

# Emphasis
A       Default
B       Bold
I       Italic
N       Normal
U       Underline
EX      Filename
JUMP    Jump
1       =I
2       =B
3       =U
ST      =2
Y       =2
SUB     Subscript
SUP     Superscript

# Typing
CMD     =2
DOC     =1
EMAIL   =1
FILE    =EX
ORG     =A
PRD     =A
REF     =A
SECT    =1
!endblock

# For hard-copy, format jumps as italics
!if $var{'OPT_TARGET'} eq 'ps'
!block phrasestyles
Name    To
JUMP    =I
URL     =I
!endblock
!endif

# For help, make jumps come out "as-is"
!if $var{'OPT_TARGET'} eq 'hlp'
!block phrasestyles
Name    To
JUMP    =A
!endblock
!endif

# Mapping of table styles
!block tablestyles
Name    To
columns Columns
rows    Rows
grid    Grid
plain   Plain
box     Box
shade   Shade
!endblock


################ Core paragraph formats ###################

# Define the root 'Para' format
!targetobject "Para"; "b0_Body";; \
  AcrobatLevel=0; \
  Alignment=Left; \
  AutoNum=0; \
  BlockSize=2; \
  BotSepAtIndent=0; \
  BotSepOffset='0.0"'; \
  BotSeparator=""; \
  CellAlignment=Top; \
  CellBMarginFixed=0; \
  CellLMarginFixed=0; \
  CellMargins="0.0 pt 0.0 pt 0.0 pt 0.0 pt"; \
  CellRMarginFixed=0; \
  CellTMarginFixed=0; \
  FIndent='0.0"'; \
  FIndentOffset='0.0"'; \
  FIndentRelative=0; \
  FontAngle=Regular; \
  FontCase="FAsTyped"; \
  FontChangeBar=0; \
  FontColor=Black; \
  FontDW="0.0%"; \
  FontDX="0.0%"; \
  FontDY="0.0%"; \
  FontFamily=Times; \
  FontLocked=0; \
  FontOutline=0; \
  FontOverline=0; \
  FontPairKern=Yes; \
  FontPosition="FNormal"; \
  FontSeparation=0; \
  FontShadow=0; \
  FontSize="$var{'_BASE_SIZE'} pt"; \
  FontStrike=0; \
  FontUnderlining="FNoUnderlining"; \
  FontVar=Regular; \
  FontWeight=Regular; \
  HyphenMaxLines=2; \
  HyphenMinPrefix=3; \
  HyphenMinSuffix=3; \
  HyphenMinWord=5; \
  Hyphenate=0; \
  LIndent='0.0"'; \
  Language="UKEnglish"; \
  Leading="2.0 pt"; \
  LetterSpace=0; \
  LineSpacing=Fixed; \
  Locked=0; \
  MaxWordSpace=110; \
  MinWordSpace=90; \
  NextTag=""; \
  OptWordSpace=100; \
  Placement=Anywhere; \
  PlacementStyle=Normal; \
  RIndent='0.0"'; \
  RunInDefaultPunct=". "; \
  SpAfter="6.0 pt"; \
  SpBefore="12.0 pt"; \
  TabStop=""; \
  TopSepAtIndent=0; \
  TopSepOffset='0.0"'; \
  TopSeparator=""; \
  UseNextTag=0; \
  WithNext=0; \
  WithPrev=0

# Define the other 'Para' formats
!targetobject "Para"; "f0_FirstBody"; "b0_Body"; \
  SpBefore="6.0 pt"

!targetobject "Para"; "fn_Footnote"; "b0_Body"; \
  BlockSize=1; \
  FontSize="10.0 pt"; \
  SpAfter="0.0 pt"; \
  SpBefore="3.0 pt"

!targetobject "Para"; "Footer"; "b0_Body"; \
  BlockSize=1; \
  FontPairKern=0; \
  FontFamily=Helvetica; \
  FontSize="10.0 pt"; \
  HyphenMinPrefix=2; \
  HyphenMinSuffix=2; \
  Hyphenate=0; \
  MaxWordSpace=125; \
  MinWordSpace=75; \
  SpAfter="0.0 pt"; \
  SpBefore="0.0 pt"; \
  TabStop="$var{'_TABC'}/Center,$var{'_TABR'}/Right"

!targetobject "Para"; "Header"; "Footer"; \
  FontFamily=Helvetica; \
  FontSize="10.5 pt"; \
  Leading="3.0 pt"; \
  TabStop="$var{'_TABHC'}/Center,$var{'_TABR'}/Right"


################ Heading paragraph formats ###################

!targetobject "Para"; "h1_Heading"; "b0_Body"; \
  AcrobatLevel=1; \
  AutoNum=Yes; \
  FontFamily=Helvetica; \
  FontSize="18.0 pt"; \
  FontWeight=Bold; \
  Hyphenate=0; \
  LIndent='0.5"'; \
  NumAtEnd=0; \
  NumFormat='H:.\\t'; \
  Placement="PageTop"; \
  PlacementStyle=Straddle; \
  SpAfter="8.0 pt"; \
  TabStop='0.5"'; \
  WithNext=Yes

!targetobject "Para"; "h2_Heading"; "h1_Heading"; \
  AcrobatLevel=4; \
  FontSize="14.0 pt"; \
  NumFormat='H:.\\t'; \
  Placement=Anywhere

!targetobject "Para"; "h3_Heading"; "h2_Heading"; \
  AcrobatLevel=7; \
  FontSize="12.0 pt"; \
  NumFormat='H:..\\t'

!targetobject "Para"; "h4_Heading"; "h3_Heading"; \
  AcrobatLevel=10; \
  AutoNum=0; \
  LIndent='0.0"'; \
  NumAtEnd=""; \
  NumFormat=""; \
  PlacementStyle=Normal; \
  TabStop=""

!targetobject "Para"; "h5_Heading"; "h4_Heading"; \
  AcrobatLevel=13; \
  FontSize="11.0 pt"; \
  Leading="3.0 pt"

!targetobject "Para"; "a1_Appendix"; "h1_Heading"; \
  NumFormat='A:.\\t'

!targetobject "Para"; "a2_Appendix"; "h2_Heading"; \
  NumFormat='A:.\\t'

!targetobject "Para"; "a3_Appendix"; "h3_Heading"; \
  NumFormat='A:..\\t'

!targetobject "Para"; "a4_Appendix"; "h4_Heading"

!targetobject "Para"; "a5_Appendix"; "h5_Heading"; \
  Leading="2.0 pt"; \
  SpAfter="7.0 pt"; \
  SpBefore="11.0 pt"

!targetobject "Para"; "p1_PlainHeading"; "h1_Heading"; \
  AutoNum=0; \
  LIndent='0.0"'; \
  NumAtEnd=""; \
  NumFormat=""; \
  TabStop=""

!targetobject "Para"; "p2_PlainHeading"; "h2_Heading"; \
  AutoNum=0; \
  LIndent='0.0"'; \
  NumAtEnd=""; \
  NumFormat=""; \
  TabStop=""

!targetobject "Para"; "p3_PlainHeading"; "h3_Heading"; \
  AutoNum=0; \
  LIndent='0.0"'; \
  NumAtEnd=""; \
  NumFormat=""; \
  PlacementStyle=Normal; \
  TabStop=""

!targetobject "Para"; "p4_PlainHeading"; "h4_Heading"

!targetobject "Para"; "p5_PlainHeading"; "h5_Heading"

# If a component cover page is requested, level 1 headings are
# preceded by a separate numbering paragraph, if appropriate
!if OPT_COMPONENT_COVER

!targetobject "Para"; "hn_HeadingNum"; "b0_Body"; \
  Alignment=Right; \
  AutoNum=Yes; \
  BotSeparator="CoverLine"; \
  FIndent="150 pt"; \
  FontFamily=Helvetica; \
  FontSize="36.0 pt"; \
  Leading="0.0 pt"; \
  NumAtEnd=0; \
  NumFormat='H:Chapter '; \
  NumberFont="Bold helvetica"; \
  PlacementStyle=Straddle; \
  SpAfter="7.0 pt"; \
  SpBefore="0.0 pt"

!targetobject "Para"; "an_AppendixNum"; "hn_HeadingNum"; \
  NumFormat='A:Appendix '

!targetobject "Para"; "h1_Heading"; "b0_Body"; \
  Alignment=Right; \
  FIndent="150 pt"; \
  FontFamily=Helvetica; \
  FontSize="33.0 pt"; \
  Leading="0.0 pt"; \
  LIndent="150 pt"; \
  PlacementStyle=Straddle; \
  SpAfter="1000.0 pt"; \
  SpBefore="0.0 pt"

!targetobject "Para"; "a1_Appendix";     "h1_Heading"
!targetobject "Para"; "p1_PlainHeading"; "h1_Heading"
!endif

# NoTOC versions for headings excluding from the contents
!targetobject "Para"; "h1_HeadingNoTOC"; "h1_Heading"; AcrobatLevel=0
!targetobject "Para"; "h2_HeadingNoTOC"; "h2_Heading"; AcrobatLevel=0
!targetobject "Para"; "h3_HeadingNoTOC"; "h3_Heading"; AcrobatLevel=0
!targetobject "Para"; "h4_HeadingNoTOC"; "h4_Heading"; AcrobatLevel=0
!targetobject "Para"; "h5_HeadingNoTOC"; "h5_Heading"; AcrobatLevel=0
!targetobject "Para"; "a1_AppendixNoTOC"; "a1_Appendix"; AcrobatLevel=0
!targetobject "Para"; "a2_AppendixNoTOC"; "a2_Appendix"; AcrobatLevel=0
!targetobject "Para"; "a3_AppendixNoTOC"; "a3_Appendix"; AcrobatLevel=0
!targetobject "Para"; "a4_AppendixNoTOC"; "a4_Appendix"; AcrobatLevel=0
!targetobject "Para"; "a5_AppendixNoTOC"; "a5_Appendix"; AcrobatLevel=0
!targetobject "Para"; "p1_PlainHeadingNoTOC"; "p1_PlainHeading"; AcrobatLevel=0
!targetobject "Para"; "p2_PlainHeadingNoTOC"; "p2_PlainHeading"; AcrobatLevel=0
!targetobject "Para"; "p3_PlainHeadingNoTOC"; "p3_PlainHeading"; AcrobatLevel=0
!targetobject "Para"; "p4_PlainHeadingNoTOC"; "p4_PlainHeading"; AcrobatLevel=0
!targetobject "Para"; "p5_PlainHeadingNoTOC"; "p5_PlainHeading"; AcrobatLevel=0


################ Generated list paragraph formats ###################

!if OPT_COMPONENT_COVER
!targetobject "Para"; "TocTitle"; "p1_PlainHeading"
!else
!targetobject "Para"; "TocTitle"; "b0_Body"; \
  Alignment=Center; \
  FontFamily=Helvetica; \
  FontSize="18.0 pt"; \
  FontWeight=Bold; \
  Hyphenate=0; \
  Placement="PageTop"; \
  PlacementStyle=Straddle; \
  SpAfter="8.0 pt"; \
  WithNext=Yes
!endif

!targetobject "Para"; "LofTitle"; "p2_PlainHeading"
!targetobject "Para"; "LotTitle"; "p2_PlainHeading"
!targetobject "Para"; "IndexTitle"; "TocTitle"

!targetobject "Para"; "h1_HeadingTOC"; "b0_Body"; \
  FontFamily=Helvetica; \
  FontWeight=Bold; \
  HyphenMinPrefix=2; \
  HyphenMinSuffix=2; \
  PlacementStyle=Straddle; \
  SpAfter="0.0 pt"; \
  SpBefore="4.0 pt"; \
  TabStop="0.5in,$var{'_TABR'}/Right/. "

!targetobject "Para"; "h2_HeadingTOC"; "h1_HeadingTOC"; \
  FontSize="11.0 pt"; \
  FontWeight=Regular; \
  SpBefore="2.0 pt"; \
  TabStop="0.75in,$var{'_TABR'}/Right/. "

!targetobject "Para"; "h3_HeadingTOC"; "h2_HeadingTOC"; \
  TabStop="1.0in,$var{'_TABR'}/Right/. "

!targetobject "Para"; "h4_HeadingTOC"; "h3_HeadingTOC"; \
  TabStop="1.25in,$var{'_TABR'}/Right/. "

!targetobject "Para"; "h5_HeadingTOC"; "h4_HeadingTOC"; \
  TabStop="1.5in,$var{'_TABR'}/Right/. "

!targetobject "Para"; "a1_AppendixTOC"; "h1_HeadingTOC"
!targetobject "Para"; "a2_AppendixTOC"; "h2_HeadingTOC"
!targetobject "Para"; "a3_AppendixTOC"; "h3_HeadingTOC"
!targetobject "Para"; "a4_AppendixTOC"; "h4_HeadingTOC"
!targetobject "Para"; "a5_AppendixTOC"; "h5_HeadingTOC"

!targetobject "Para"; "p1_PlainHeadingTOC"; "h1_HeadingTOC"
!targetobject "Para"; "p2_PlainHeadingTOC"; "h2_HeadingTOC"
!targetobject "Para"; "p3_PlainHeadingTOC"; "h3_HeadingTOC"
!targetobject "Para"; "p4_PlainHeadingTOC"; "h4_HeadingTOC"
!targetobject "Para"; "p5_PlainHeadingTOC"; "h5_HeadingTOC"

!targetobject "Para"; "LofTitleTOC"; "h2_HeadingTOC"
!targetobject "Para"; "LotTitleTOC"; "h2_HeadingTOC"
!targetobject "Para"; "IndexTitleTOC"; "h1_HeadingTOC"

!targetobject "Para"; "ft_FigureTitleLOF"; "b0_Body"; \
  LIndent='1.0"'; \
  MaxWordSpace=100; \
  MinWordSpace=100; \
  SpAfter="0.0 pt"; \
  SpBefore="2.0 pt"; \
  PlacementStyle=Straddle; \
  TabStop="0.5in,$var{'_TABR'}/Right/. "

!targetobject "Para"; "tt_TableTitleLOT"; "ft_FigureTitleLOF"

!targetobject "Para"; "GroupTitlesIX"; "b0_Body"; \
  Alignment="LeftRight"; \
  BlockSize=1; \
  FontPairKern=0; \
  FontWeight=Bold; \
  HyphenMinPrefix=2; \
  HyphenMinSuffix=2; \
  MaxWordSpace=125; \
  MinWordSpace=75; \
  SpAfter="0.0 pt"; \
  SpBefore="15.0 pt"; \
  WithNext=Yes

!targetobject "Para"; "IndexIX"; "GroupTitlesIX"; \
  Alignment=Left; \
  FontSize="12.0 pt"; \
  FontWeight=Regular; \
  Hyphenate=Yes; \
  SpBefore="0.0 pt"; \
  WithNext=0

!targetobject "Para"; "Level1IX"; "IndexIX"; \
  Alignment="LeftRight"; \
  LIndent='0.5"'

!targetobject "Para"; "Level2IX"; "Level1IX"; \
  FIndent='0.25"'; \
  FontSize="11.5 pt"; \
  LIndent='0.75"'


################ List paragraph formats ###################

!targetobject "Para"; "l0_ListBody"; "b0_Body"; \
  BlockSize=3; \
  FIndent=_LI1; \
  LIndent=_LI1; \
  SpAfter="8.0 pt"; \
  SpBefore="6.0 pt"

!targetobject "Para"; "l1_ListBody"; "l0_ListBody"; \
  FIndent=_LI2; \
  LIndent=_LI2

!targetobject "Para"; "l2_ListBody"; "l1_ListBody"; \
  FIndent=_LI3; \
  LIndent=_LI3

!targetobject "Para"; "l3_ListBody"; "l2_ListBody"; \
  FIndent=_LI4; \
  LIndent=_LI4

!targetobject "Para"; "l4_ListBody"; "l3_ListBody"; \
  FIndent=_LI5; \
  LIndent=_LI5

!targetobject "Para"; "l5_ListBody"; "l4_ListBody"; \
  FIndent=_LI6; \
  LIndent=_LI6

!targetobject "Para"; "li0_ListItem"; "b0_Body"; \
  BlockSize=3; \
  FontSize=$var{'_BASE_SIZE'} + 1 . " pt"; \
  SpAfter="8.0 pt"; \
  SpBefore="6.0 pt"

!targetobject "Para"; "li1_ListItem"; "li0_ListItem"; \
  FIndent=_LI1; \
  LIndent=_LI1

!targetobject "Para"; "li2_ListItem"; "li1_ListItem"; \
  FIndent=_LI2; \
  LIndent=_LI2

!targetobject "Para"; "li3_ListItem"; "li2_ListItem"; \
  FIndent=_LI3; \
  LIndent=_LI3

!targetobject "Para"; "li4_ListItem"; "li3_ListItem"; \
  FIndent=_LI4; \
  LIndent=_LI4

!targetobject "Para"; "li5_ListItem"; "li4_ListItem"; \
  FIndent=_LI5; \
  LIndent=_LI5

!targetobject "Para"; "u0_Unordered"; "b0_Body"; \
  AutoNum=Yes; \
  BlockSize=3; \
  LIndent=_LI1; \
  NumAtEnd=0; \
  NumFormat='\xa5 \\t'; \
  NumberFont="Bullet Symbol"; \
  SpBefore="6.0 pt"; \
  TabStop=_LI1

!targetobject "Para"; "u1_Unordered"; "u0_Unordered"; \
  NumFormat='\xd0 \\t'; \
  NumberFont=""; \
  FIndent=_LI1; \
  LIndent=_LI2; \
  TabStop=_LI2

!targetobject "Para"; "u2_Unordered"; "u0_Unordered"; \
  FIndent=_LI2; \
  LIndent=_LI3; \
  TabStop=_LI3

!targetobject "Para"; "u3_Unordered"; "u1_Unordered"; \
  FIndent=_LI3; \
  LIndent=_LI4; \
  TabStop=_LI4

!targetobject "Para"; "u4_Unordered"; "u2_Unordered"; \
  FIndent=_LI4; \
  LIndent=_LI5; \
  TabStop=_LI5

!targetobject "Para"; "u5_Unordered"; "u3_Unordered"; \
  FIndent=_LI5; \
  LIndent=_LI6; \
  TabStop=_LI6

!targetobject "Para"; "oi0_OrderedInit"; "u0_Unordered"; \
  NumFormat='L:.\\t'; \
  NumberFont=""; \
  SpAfter="0.0 pt"

!targetobject "Para"; "oi1_OrderedInit"; "oi0_OrderedInit"; \
  NumFormat='M:)\\t'; \
  FIndent=_LI1; \
  LIndent=_LI2; \
  TabStop=_LI2

!targetobject "Para"; "oi2_OrderedInit"; "oi1_OrderedInit"; \
  NumFormat='N:.\\t'; \
  FIndent=_LI2; \
  LIndent=_LI3; \
  TabStop=_LI3

!targetobject "Para"; "oi3_OrderedInit"; "oi2_OrderedInit"; \
  NumFormat='0:)\\t'; \
  FIndent=_LI3; \
  LIndent=_LI4; \
  TabStop=_LI4

!targetobject "Para"; "oi4_OrderedInit"; "oi3_OrderedInit"; \
  NumFormat='Q:.\\t'; \
  FIndent=_LI4; \
  LIndent=_LI5; \
  TabStop=_LI5

!targetobject "Para"; "oi5_OrderedInit"; "oi4_OrderedInit"; \
  NumFormat='R:)\\t'; \
  FIndent=_LI5; \
  LIndent=_LI6; \
  TabStop=_LI6

!targetobject "Para"; "on0_OrderedNext"; "oi0_OrderedInit"; \
  NumFormat='L:.\\t'

!targetobject "Para"; "on1_OrderedNext"; "oi1_OrderedInit"; \
  NumFormat='M:)\\t'

!targetobject "Para"; "on2_OrderedNext"; "oi2_OrderedInit"; \
  NumFormat='N:.\\t'

!targetobject "Para"; "on3_OrderedNext"; "oi3_OrderedInit"; \
  NumFormat='O:)\\t'

!targetobject "Para"; "on4_OrderedNext"; "oi4_OrderedInit"; \
  NumFormat='Q:.\\t'

!targetobject "Para"; "on5_OrderedNext"; "oi5_OrderedInit"; \
  NumFormat='R:)\\t'

!targetobject "Para"; "s0_SimpleList"; "l0_ListBody"
!targetobject "Para"; "s1_SimpleList"; "l1_ListBody"
!targetobject "Para"; "s2_SimpleList"; "l2_ListBody"
!targetobject "Para"; "s3_SimpleList"; "l3_ListBody"
!targetobject "Para"; "s4_SimpleList"; "l4_ListBody"
!targetobject "Para"; "s5_SimpleList"; "l5_ListBody"


################ Figure/table paragraph formats ###################

!targetobject "Para"; "fa_FigureAnchor"; "b0_Body"; \
  FontSize="2.0 pt"; \
  Leading="12.0 pt"; \
  SpAfter="0.0 pt"; \
  SpBefore="0.0 pt"

!targetobject "Para"; "ta_TableAnchor"; "fa_FigureAnchor"

!targetobject "Para"; "ft_FigureTitle"; "b0_Body"; \
  Alignment=Center; \
  AutoNum=Yes; \
  Hyphenate=0; \
  Leading="0.0 pt"; \
  NumAtEnd=0; \
  NumFormat='F:Figure . '; \
  SpAfter="18.0 pt"; \
  SpBefore="13.5 pt"

!targetobject "Para"; "tt_TableTitle"; "ft_FigureTitle"; \
  NumFormat='T:Table . '

!if OPT_NUMBER_PER_COMPONENT
!targetobject "Para"; "ft_FigureTitle"; "ft_FigureTitle"; \
  NumFormat='H:Figure -< \>. '
!targetobject "Para"; "tt_TableTitle"; "tt_TableTitle"; \
  NumFormat='H:Table -< \>. '
!endif

!targetobject "Para"; "CellBody"; "b0_Body"; \
  FontFamily=Helvetica; \
  FontSize="11.0 pt"; \
  SpAfter="2.0 pt"; \
  SpBefore="0.0 pt"; \
  TabStop='1.5",2.5",3.5",4.5",5.5"'

!targetobject "Para"; "CellGroup"; "CellBody"; \
  FontWeight=Bold

!targetobject "Para"; "CellHeading"; "CellGroup"

!targetobject "Para"; "tf_TableFootnote"; "ta_TableAnchor"; \
  BlockSize=1; \
  FIndent='0.1"'; \
  FontSize="10.0 pt"; \
  LIndent='0.1"'; \
  Leading="2.0 pt"; \
  RIndent='0.25"'; \
  SpBefore="3.0 pt"


################ Miscellaneous paragraph formats ###################

!targetobject "Para"; "e0_Example"; "b0_Body"; \
  BlockSize=4; \
  FontFamily=Courier; \
  FontPairKern=0; \
  FontSize="10.0 pt"; \
  Hyphenate=0; \
  Language="NoLanguage"; \
  Leading="0.0 pt"; \
  MaxWordSpace=100; \
  MinWordSpace=100; \
  SpAfter="0.0 pt"; \
  SpBefore="6.0 pt"; \
  TabStop='0.5",1.0",1.5",2.0",2.5",3.0",3.5"'

!targetobject "Para"; "e0_Example80"; "e0_Example"; \
  FontSize="9.4 pt"; \
  PlacementStyle=Straddle

!targetobject "Para"; "et_ExampleTitle"; "b0_Body"; \
  AutoNum=Yes; \
  BotSeparator="Table Rule"; \
  FIndent='0.1"'; \
  FontSize="11.0 pt"; \
  Hyphenate=0; \
  LIndent='0.1"'; \
  Leading="0.0 pt"; \
  NumAtEnd=0; \
  NumFormat='E:Example . '; \
  NumberFont=Bold; \
  SpAfter="18.0 pt"; \
  SpBefore="13.0 pt"

!targetobject "Para"; "gh_GlossaryHeading"; "b0_Body"; \
  FontFamily=Helvetica; \
  FontWeight=Bold; \
  Hyphenate=0; \
  SpAfter="8.0 pt"; \
  WithNext=Yes

!targetobject "Para"; "gl_Glossary"; "b0_Body"; \
  FontFamily=Helvetica; \
  FontSize="10.0 pt"; \
  LIndent='1.5"'; \
  SpAfter="2.0 pt"; \
  SpBefore="0.0 pt"; \
  TabStop='1.5"'

!targetobject "Para"; "li_Line"; "b0_Body"; \
  BotSeparator="Line"; \
  FontSize="2.0 pt"; \
  Leading="1.0 pt"; \
  SpAfter="0.0 pt"; \
  SpBefore="0.0 pt"

!targetobject "Para"; "nb_NoteBegin"; "b0_Body"; \
  AutoNum=Yes; \
  BlockSize=3; \
  NumAtEnd=0; \
  NumFormat='Note: '; \
  NumberFont=Bold; \
  SpBefore="6.0 pt"; \
  TabStop='0.7"'; \
  TopSeparator="Note Above"

!targetobject "Para"; "ne_NoteEnd"; "li_Line"; \
  BotSeparator="Note Below"

!targetobject "Para"; "no_Note"; "nb_NoteBegin"; \
  BotSeparator="Note Below"

!targetobject "Para"; "pb_PageBreak"; "b0_Body"; \
  Alignment=Right; \
  FontSize="4.0 pt"; \
  Hyphenate=0; \
  Leading="0.0 pt"; \
  PlacementStyle=Straddle; \
  SpAfter="999.0 pt"; \
  SpBefore="0.0 pt"

# This definition currently causes problems as SDF's escaping
# mechanisms cannot yet handle the embedded ] in the NumFormat attribute
#!targetobject "Para"; "re_Reference"; "b0_Body"; \
#  AutoNum=Yes; \
#  FontFamily=Helvetica; \
#  FontSize="10.0 pt"; \
#  Hyphenate=0; \
#  LIndent='0.5"'; \
#  NumAtEnd=0; \
#  NumFormat='R:[]\\t'; \
#  SpAfter="8.0 pt"; \
#  SpBefore="8.0 pt"; \
#  TabStop='0.5"'

!targetobject "Para"; "si_StepInit"; "oi0_OrderedInit"; \
  NumFormat='S:.\\t'; \
  NumberFont=Bold

!targetobject "Para"; "sn_StepNext"; "si_StepInit"; \
  NumFormat='S:.\\t'

!targetobject "Para"; "st_StepTitle"; "sn_StepNext"; \
  AutoNum=0; \
  FontWeight=Bold; \
  NumAtEnd=""; \
  NumFormat=''; \
  NumberFont=""; \
  TabStop='0.7"'


################ Cover page & title block paragraph formats ###################

!targetobject "Para"; "ad_Address"; "b0_Body"; \
  SpAfter="0.0 pt"; \
  SpBefore="0.0 pt"

!targetobject "Para"; "at_Attribute"; "b0_Body"; \
  AutoNum=Yes; \
  LIndent=_AT_INDENT; \
  NumAtEnd=0; \
  NumFormat='\\t'; \
  NumberFont='AttributeLabel'; \
  PlacementStyle=Straddle; \
  SpBefore="0.0 pt"; \
  TabStop=_AT_INDENT; \
  WithPrev=1

!targetobject "Para"; "ca_CorrAttention"; "b0_Body"; \
  AutoNum=Yes; \
  BlockSize=1; \
  FontSize="14.0 pt"; \
  Leading="3.0 pt"; \
  LineSpacing=Proportional; \
  NumAtEnd=0; \
  NumFormat='Attention:\\t'; \
  NumberFont=Bold; \
  PlacementStyle=Straddle; \
  SpAfter="0.0 pt"; \
  TabStop='1.0",2.75"'

!targetobject "Para"; "ca_CorrAttention2"; "ca_CorrAttention"; \
  AutoNum=0; \
  FIndent='1.0"'; \
  LIndent='1.0"'; \
  NumAtEnd=""; \
  NumFormat=''; \
  NumberFont=""; \
  SpBefore="2.0 pt"; \
  TabStop='2.75",4.5"'

!targetobject "Para"; "cc_CorrCopy"; "ca_CorrAttention2"; \
  AutoNum=Yes; \
  FIndent='0.0"'; \
  LIndent='0.0"'; \
  NumAtEnd=0; \
  NumFormat='Copy:\\t'; \
  NumberFont=Bold; \
  SpBefore="12.0 pt"; \
  TabStop='1.0",2.75001",4.5"'

!targetobject "Para"; "cc_CorrCopy2"; "cc_CorrCopy"; \
  AutoNum=0; \
  FIndent='1.0"'; \
  LIndent='1.0"'; \
  NumAtEnd=""; \
  NumFormat=''; \
  NumberFont=""; \
  SpBefore="2.0 pt"; \
  TabStop='2.75",4.5"'

!targetobject "Para"; "cd_CorrDate"; "cc_CorrCopy2"; \
  AutoNum=Yes; \
  FIndent='0.0"'; \
  LIndent='0.0"'; \
  NumAtEnd=0; \
  NumFormat='Date:\\t'; \
  NumberFont=Bold; \
  SpBefore="12.0 pt"; \
  TabStop='1.01915"'

!targetobject "Para"; "ce_CorrEnd"; "b0_Body"; \
  FontWeight=Bold; \
  SpAfter="4.0 pt"; \
  SpBefore="4.0 pt"

!targetobject "Para"; "cf_CorrFrom"; "b0_Body"; \
  AutoNum=Yes; \
  BlockSize=1; \
  FontSize="14.0 pt"; \
  Leading="3.0 pt"; \
  LineSpacing=Proportional; \
  NumAtEnd=0; \
  NumFormat='From:\\t'; \
  NumberFont=Bold; \
  PlacementStyle=Straddle; \
  SpAfter="0.0 pt"; \
  TabStop='1.0",2.75"'

!targetobject "Para"; "cp_CorrPageCount"; "b0_Body"; \
  AutoNum=Yes; \
  BlockSize=1; \
  FontSize="14.0 pt"; \
  Leading="3.0 pt"; \
  LineSpacing=Proportional; \
  NumAtEnd=0; \
  NumFormat='No. of Pages (including this one):\\t'; \
  NumberFont=Bold; \
  PlacementStyle=Straddle; \
  SpAfter="0.0 pt"; \
  TabStop='3.25"'

!targetobject "Para"; "cr_CorrRefNo"; "cp_CorrPageCount"; \
  NumFormat='Ref. No.:\\t'; \
  TabStop='1.0"'

!targetobject "Para"; "cs_CorrSubject"; "cr_CorrRefNo"; \
  LIndent='1.0"'; \
  NumFormat='Subject:\\t'; \
  RIndent='0.264"'

!targetobject "Para"; "ct_CorrTo"; "cs_CorrSubject"; \
  LIndent='0.0"'; \
  NumFormat='To:\\t'; \
  RIndent='0.0"'; \
  TabStop='1.0",2.75",4.5"'

!targetobject "Para"; "ct_CorrTo2"; "ct_CorrTo"; \
  AutoNum=0; \
  FIndent='1.0"'; \
  LIndent='1.0"'; \
  NumAtEnd=""; \
  NumFormat=''; \
  NumberFont=""; \
  SpBefore="2.0 pt"; \
  TabStop='2.75",4.5"'

!targetobject "Para"; "cx_CorrFax"; "ct_CorrTo2"; \
  AutoNum=Yes; \
  FIndent='0.0"'; \
  LIndent='0.0"'; \
  NumAtEnd=0; \
  NumFormat='Fax No.:\\t'; \
  NumberFont=Bold; \
  SpBefore="12.0 pt"; \
  TabStop='1.0"'

!targetobject "Para"; "cy_CorrCompany"; "cx_CorrFax"; \
  NumFormat='Company:\\t'

!targetobject "Para"; "da_DocAction"; "b0_Body"; \
  FontSize="14.0 pt"; \
  FontWeight=Bold; \
  PlacementStyle=Straddle; \
  SpAfter="10.0 pt"; \
  SpBefore="20.0 pt"

!targetobject "Para"; "dc_DocCode"; "da_DocAction"; \
  Alignment=Center; \
  AutoNum=Yes; \
  FontSize="18.0 pt"; \
  NumAtEnd=0; \
  NumFormat='Document No: '; \
  SpAfter="20.0 pt"

!targetobject "Para"; "dd_DocDistr"; "b0_Body"; \
  Alignment=Right; \
  FontAngle=Oblique; \
  FontFamily=Helvetica; \
  HyphenMinPrefix=2; \
  HyphenMinSuffix=2; \
  PlacementStyle=Straddle; \
  SpAfter="100.0 pt"

!targetobject "Para"; "dk_DocSkip"; "b0_Body"; \
  Alignment=Center; \
  FontSize="18.0 pt"; \
  FontWeight=Bold; \
  PlacementStyle=Straddle; \
  SpAfter="20.0 pt"; \
  SpBefore="20.0 pt"

!targetobject "Para"; "dn_DocName"; "dk_DocSkip"; \
  FontFamily=Helvetica; \
  TabStop='0.5",1.0",1.5",2.0",2.5",3.0",3.5"'

!targetobject "Para"; "dp_DocProject"; "dn_DocName"; \
  FontFamily=Times; \
  SpAfter="40.0 pt"; \
  SpBefore="0.0 pt"; \
  TabStop=""

!targetobject "Para"; "ds_DocStatus"; "dp_DocProject"; \
  SpAfter="60.0 pt"; \
  SpBefore="20.0 pt"

!targetobject "Para"; "dt_DocType"; "ds_DocStatus"; \
  SpAfter="20.0 pt"

!targetobject "Para"; "du_DocAuthor"; "dt_DocType"; \
  FontAngle=Oblique; \
  FontSize="12.0 pt"; \
  FontWeight=Regular; \
  SpAfter="10.0 pt"; \
  SpBefore="10.0 pt"

!targetobject "Para"; "dw_DocWho"; "dt_DocType"; \
  Alignment=Left; \
  AutoNum=Yes; \
  FIndent='0.25"'; \
  FontSize="12.0 pt"; \
  LIndent='0.25"'; \
  NumAtEnd=Yes; \
  NumFormat='............................ ....................'; \
  SpAfter="10.0 pt"; \
  SpBefore="10.0 pt"; \
  TabStop='2.0"'


!targetobject "Para"; "dy_DocCopy"; "dw_DocWho"; \
  Alignment=Center; \
  FIndent='0.0"'; \
  FontSize="18.0 pt"; \
  LIndent='0.0"'; \
  NumAtEnd=0; \
  NumFormat='Copy No: '; \
  SpAfter='20.0 pt'; \
  SpBefore="20.0 pt"; \
  TabStop=""


################ Phrase formats ###################

# Define the root 'Phrase' format
!targetobject "Phrase"; "Emphasis";; \
  Angle=Italic

# Define the other 'Phrase' formats
!targetobject "Phrase"; "Bold"; "Emphasis"; \
  Angle=""; \
  Weight=Bold

!targetobject "Phrase"; "Bold 9 pt"; "Bold"; \
  Size="9.0 pt"

!targetobject "Phrase"; "AttributeLabel"; "Bold"; \
  Family=Helvetica

!targetobject "Phrase"; "Bold helvetica"; "Bold"; \
  Family=Helvetica

!targetobject "Phrase"; "Bold italic"; "Emphasis"; \
  Weight=Bold

!targetobject "Phrase"; "Bullet Symbol"; "Emphasis"; \
  Angle=Regular; \
  Family=Courier; \
  Size="18.0 pt"; \
  Weight=Bold

!targetobject "Phrase"; "Callout"; "Bullet Symbol"; \
  Family=Times; \
  Size="10.0 pt"; \
  Weight=Regular

!targetobject "Phrase"; "DiagramBold"; "Bold"; \
  Family=Helvetica; \
  Size="11.0 pt"; \

!targetobject "Phrase"; "DiagramStd"; "DiagramBold"; \
  Weight=Regular

!targetobject "Phrase"; "Emphasis 9 pt"; "Emphasis"; \
  Size="9.0 pt"

!targetobject "Phrase"; "EquationVariables"; "Emphasis"

!targetobject "Phrase"; "Filename"; "Emphasis"; \
  Angle=Regular; \
  Family=Courier; \
  Size="9.4 pt"

!targetobject "Phrase"; "Italic"; "Emphasis"; \
  Weight=Regular

!targetobject "Phrase"; "Jump"; "Emphasis"; \
  Angle=""; \
  Color=Blue; \
  Separation=4

!targetobject "Phrase"; "Normal"; "Emphasis"; \
  Angle=Regular; \
  Weight=Regular

!targetobject "Phrase"; "Reference document"; "Emphasis"; \
  Family=Times; \
  Size="11.5 pt"; \
  Weight=Regular

!targetobject "Phrase"; "Run-In Heading"; "Emphasis"; \
  Angle=Regular; \
  Size="11.0 pt"; \
  Weight=Bold

!targetobject "Phrase"; "Subscript"; "Emphasis"; \
  Angle=""; \
  Position="FSubscript"

!targetobject "Phrase"; "Superscript"; "Subscript"; \
  Position="FSuperscript"

!targetobject "Phrase"; "Symbol"; "Emphasis"; \
  Angle=Regular; \
  Family=Symbol; \
  Weight=Regular

!targetobject "Phrase"; "Underline"; "Emphasis"; \
  Angle=""; \
  Underlining="FSingle"


################ Table formats ###################

# Define the root 'Table' format
!targetobject "Table"; "Format A";; \
  Alignment=Left; \
  AltShadePeriod=2; \
  BRuling=""; \
  BlockSize=2; \
  BodyColor=Black; \
  BodyFill=15; \
  BodyRowRuling=""; \
  BodySeparation=0; \
  CellMargins="6.0 pt 4.0 pt 6.0 pt 2.0 pt"; \
  ColumnRuling=""; \
  HFColor=Black; \
  HFFill=15; \
  HFRowRuling=""; \
  HFSeparation=0; \
  InitNumBodyRows=3; \
  InitNumColumns=3; \
  InitNumFRows=0; \
  InitNumHRows=1; \
  LIndent='0.117"'; \
  LRuling=""; \
  LastBRuling=0; \
  Locked=0; \
  NumByColumn=0; \
  Placement=Anywhere; \
  RIndent='0.0"'; \
  RRuling=""; \
  RulingPeriod=4; \
  SeparatorRuling=""; \
  ShadeByColumn=0; \
  ShadePeriod=2; \
  SpAfter="2.0 pt"; \
  SpBefore="12.0 pt"; \
  TRuling=Thin; \
  TitleGap="3.0 pt"; \
  TitlePlacement="InHeader"; \
  XColor=Black; \
  XColumnNum=1; \
  XColumnRuling=""; \
  XFill=15; \
  XRowRuling=""; \
  XSeparation=0

# Define the other 'Table' formats
!targetobject "Table"; "Box"; "Format A"; \
  BRuling=Thin; \
  BlockSize=4; \
  InitNumBodyRows=5; \
  LIndent='0.0"'; \
  LRuling=Thin; \
  RRuling=Thin; \
  SpBefore="4.0 pt"; \
  TitlePlacement=None

!targetobject "Table"; "Columns"; "Box"; \
  BRuling="Very Thin"; \
  ColumnRuling="Very Thin"; \
  LRuling="Very Thin"; \
  RRuling="Very Thin"; \
  SeparatorRuling="Very Thin"; \
  TRuling="Very Thin"; \
  XColumnRuling="Very Thin"

!targetobject "Table"; "Format B"; "Format A"; \
  SpBefore="4.0 pt"; \
  TRuling=""; \
  TitlePlacement=None

!targetobject "Table"; "Format IC1"; "Format A"; \
  BRuling=Medium; \
  BodyRowRuling="Very Thin"; \
  InitNumBodyRows=14; \
  InitNumColumns=2; \
  LIndent='0.55"'; \
  LRuling=Thin; \
  LastBRuling=Yes; \
  RRuling=Thin; \
  SeparatorRuling=Medium; \
  TRuling=Medium; \
  XColumnRuling=Thin; \
  XRowRuling="Very Thin"

!targetobject "Table"; "Grid"; "Format IC1"; \
  BRuling="Very Thin"; \
  BlockSize=4; \
  ColumnRuling="Very Thin"; \
  InitNumBodyRows=5; \
  InitNumColumns=3; \
  LIndent='0.0"'; \
  LRuling="Very Thin"; \
  LastBRuling=0; \
  RRuling="Very Thin"; \
  SeparatorRuling=Double; \
  SpBefore="4.0 pt"; \
  TRuling="Very Thin"; \
  TitlePlacement=None; \
  XColumnRuling="Very Thin"

!targetobject "Table"; "Plain"; "Format A"; \
  BlockSize=4; \
  InitNumBodyRows=5; \
  LIndent='0.0"'; \
  SpBefore="4.0 pt"; \
  TRuling=""; \
  TitlePlacement=None

!targetobject "Table"; "Rows"; "Plain"; \
  BRuling="Very Thin"; \
  BodyRowRuling="Very Thin"; \
  SeparatorRuling=Thin; \
  TRuling="Very Thin"; \
  XRowRuling="Very Thin"

!targetobject "Table"; "Shade"; "Rows"; \
  BodyRowRuling=""; \
  ColumnRuling="Very Thin"; \
  HFFill=5; \
  LRuling="Very Thin"; \
  RRuling="Very Thin"; \
  SeparatorRuling="Very Thin"; \
  XColumnRuling="Very Thin"; \
  XRowRuling=""

!targetobject "Table"; "Shade1"; "Shade"; \
  AltShadePeriod=1; \
  ShadePeriod=1; \
  XFill=6

!targetobject "Table"; "Shade2"; "Shade1"; \
  BRuling=Thin; \
  ColumnRuling=Thin; \
  HFFill=4; \
  LRuling=Thin; \
  RRuling=Thin; \
  SeparatorRuling=Thin; \
  TRuling=Thin; \
  XColumnRuling=Thin; \
  XFill=5

################ Generated lists ###################

!targetobject "List"; "TOC";; \
  Layout='<$paranumonly\>\\t<$paratext\>\\t<$pagenum\>'

!targetobject "List"; "LOF";; \
  Layout='<$paranum\>\\t<$paratext\>\\t<$pagenum\>'

!targetobject "List"; "LOT";; \
  Layout='<$paranum\>\\t<$paratext\>\\t<$pagenum\>'

# Note: the parameters below are not yet used, i.e. a special text flow for
# indexes is not yet generated as the default one is good enough for now.
!targetobject "Index"; "IX";; \
  Index='<$pagenum\>'; \
  SortSpec='<$symbols\><$numerics\><$alphabetics\>'; \
  Spec=' 1, 2-3'
  #GroupTitles='Symbols[\\ ];Numerics[0];A;B;C;D;E;F;G;H;I;J;K;L;M;N;O;P;Q;R;S;T;U;V;W;X;Y;Z'; \


# Give the index 2 columns, but no sidehead
!define OPT_IX_COLUMNS          2
!define OPT_IX_COLUMN_GAP       36
!define OPT_IX_SIDEHEAD_WIDTH   0
!define OPT_IX_SIDEHEAD_GAP     0

################ Reference page frames ###################

!targetobject "Frame"; "Footnote";; \
  Height=20; \
  PenWidth=0.25; \
  LineY=12; \
  LineLength=132

!targetobject "Frame"; "Line";; \
  Height=6; \
  PenWidth=0.2; \
  LineY=2; \
  LineLength=DOC_FULL_WIDTH

!targetobject "Frame"; "CoverLine";; \
  Height=6; \
  PenWidth=0.2; \
  LineX=150; \
  LineY=2; \
  LineLength=$var{'DOC_FULL_WIDTH'} - 150

!targetobject "Frame"; "Note Above";; \
  Height=6; \
  PenWidth=0.2; \
  LineY=2; \
  LineLength=DOC_FULL_WIDTH

!targetobject "Frame"; "Note Below"; "Note Above"

!targetobject "Frame"; "TableFootnote";; \
  Height=7; \
  PenWidth=0.25; \
  LineY=6; \
  LineLength=132


################ Special target formats ###################

# For rtf, use Word's standard style names
!if $var{'OPT_TARGET'} eq 'rtf'
!use 'rtf.sdt'
!endif

# For hlp, load the necessary configuration
!if $var{'OPT_TARGET'} eq 'hlp'
!use 'hlp.sdt'
!endif
tEnd=0; \
  NumFormat='Fromsdf-2.001/perllib/sdf/home/look/simple/simple.sdm010064400042570001753000000010710630522653200215100ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Simple Look
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 01-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{simple}} is an [[SDF]] look for general documentation.
#
# >>Description::
#
# >>Limitations::
#

# Load the general page layout stuff
!use "pages"
sdf-2.001/perllib/sdf/home/look/simple/listing.sds010064400042570001753000000031110631570462000216730ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Listing Style
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 01-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{listing}} is an [[SDF]] style for source code listings.
#
# >>Description::
#
# >>Limitations::
#

# Number lines if requested
!if OPT_NUMBER
!on paragraph 'E80|PB';; $_plcnt++;\
    if ($_plcnt % $var{'OPT_NUMBER'} == 0 && $style ne 'PB') {\
        $attr{'label'} = "$_plcnt\\t";\
        $attr{'sp_before'} = 0;\
    }
!endif

# Build the borders
!default OPT_BORDERS 2
!build_borders

# Define the number of header/footer lines
!default OPT_HEADINGS 2

# Define the right page header
!define PAGE_RIGHT_HEADER_INNER1   DOC_PATH
!define PAGE_RIGHT_HEADER_INNER2   'Listing'
!define PAGE_RIGHT_HEADER_CENTER1  ''
!define PAGE_RIGHT_HEADER_CENTER2  ''
!define PAGE_RIGHT_HEADER_OUTER1   ''
!define PAGE_RIGHT_HEADER_OUTER2   ''

# Define the right page footer
!define PAGE_RIGHT_FOOTER_INNER1   FULL:DOC_MODIFIED
!define PAGE_RIGHT_FOOTER_INNER2   ''
!define PAGE_RIGHT_FOOTER_CENTER1  ''
!define PAGE_RIGHT_FOOTER_CENTER2  ''
!define PAGE_RIGHT_FOOTER_OUTER1   "{{PAGENUM:}} of {{PAGECOUNT:}}"
!define PAGE_RIGHT_FOOTER_OUTER2   ''

# Build the first page as a copy of the right page
!first_copy_right_page

# Build the left page as a mirror of the right page
!left_mirror_right_page
sdf-2.001/perllib/sdf/home/look/simple/newslttr.sds010064400042570001753000000011530630323423200221020ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Newslttr Style
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 08-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{newslttr}} is an [[SDF]] style for newsletters.
#
# >>Description::
#
# >>Limitations::
#

# Use the admin style with an appropriate default title
!default DOC_TYPE "NEWSLETTER"
!use "admin.sds"
sdf-2.001/perllib/sdf/home/look/simple/paper.sds010064400042570001753000000033060645306712200213410ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Paper Style
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 01-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{paper}} is an [[SDF]] style for white papers.
#
# >>Description::
#
# >>Limitations::
#

# Load the cover page definitions
!use "covers"

# Override the cover page setting
!define DOC_COVER "paper"

# Remove the sidehead
!define OPT_SIDEHEAD_WIDTH 0
!define OPT_SIDEHEAD_GAP   0

# Build the borders
!default OPT_BORDERS 0
!build_borders

# Define the number of header/footer lines
!default OPT_HEADINGS 1

# Define the first page footer
!define PAGE_FIRST_FOOTER_INNER1  ''
!define PAGE_FIRST_FOOTER_INNER2  ''
!define PAGE_FIRST_FOOTER_CENTER1  "{{PAGENUM:}}"
!define PAGE_FIRST_FOOTER_CENTER2 ''
!define PAGE_FIRST_FOOTER_OUTER1  ''
!define PAGE_FIRST_FOOTER_OUTER2  ''

# Define the right page header
!define PAGE_RIGHT_HEADER_INNER1   ''
!define PAGE_RIGHT_HEADER_INNER2   ''
!define PAGE_RIGHT_HEADER_CENTER1  ''
!define PAGE_RIGHT_HEADER_CENTER2  ''
!define PAGE_RIGHT_HEADER_OUTER1   '{{I[family=Times][[DOC_NAME]]}}'
!define PAGE_RIGHT_HEADER_OUTER2   ''

# Define the right page footer
!define PAGE_RIGHT_FOOTER_INNER1   ''
!define PAGE_RIGHT_FOOTER_INNER2   ''
!define PAGE_RIGHT_FOOTER_CENTER1  "{{PAGENUM:}}"
!define PAGE_RIGHT_FOOTER_CENTER2  ''
!define PAGE_RIGHT_FOOTER_OUTER1   ''
!define PAGE_RIGHT_FOOTER_OUTER2   ''

# Build the left page as a mirror of the right page
!left_mirror_right_page
sdf-2.001/perllib/sdf/home/look/simple/document.sds010064400042570001753000000044470635664765000220730ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Document Style
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 01-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{document}} is an [[SDF]] style for normal documents.
#
# >>Description::
# If a document name is not set, the text of the first level heading is used.
# (This makes the output for a single topic a little nicer.)
#
# >>Limitations::
#

# Load the cover page definitions
!use "covers"

# Provide the default cover page setting
!default DOC_COVER "original"

# Setup defaults to eliminate warning messages for files without a title
!block default; family="DOC"
Name            Value
NAME            ''
TYPE            ''
PROJECT         ''
ID              ''
URL             ''
OWNER           ''
!endblock

# Build the borders
!default OPT_BORDERS 2
!build_borders

# Define the number of header/footer lines
!default OPT_HEADINGS 2

# Define the first page footer
!define PAGE_FIRST_FOOTER_INNER1  ''
!define PAGE_FIRST_FOOTER_INNER2  ''
!define PAGE_FIRST_FOOTER_CENTER1 "{{B:[[FULL:DOC_MODIFIED]]}}"
!define PAGE_FIRST_FOOTER_CENTER2 ''
!define PAGE_FIRST_FOOTER_OUTER1  ''
!define PAGE_FIRST_FOOTER_OUTER2  ''

# Define the right page header
!define PAGE_RIGHT_HEADER_INNER1   '[[DOC_PROJECT]]'
!define PAGE_RIGHT_HEADER_INNER2   ''
!define PAGE_RIGHT_HEADER_CENTER1  ''
!define PAGE_RIGHT_HEADER_CENTER2  ''
!define PAGE_RIGHT_HEADER_OUTER1   '{{B:[[$var{"DOC_NAME"} || "{{PARATEXT:H1,A1,P1}}"]]}}'
!define PAGE_RIGHT_HEADER_OUTER2   '[[DOC_TYPE]]'

# Define the right page footer
!define PAGE_RIGHT_FOOTER_INNER1   FULL:DOC_MODIFIED
!define PAGE_RIGHT_FOOTER_INNER2   '[[DOC_URL]]'
!if DOC_OWNER
!define PAGE_RIGHT_FOOTER_CENTER1  "[[c]] [[YEAR:DOC_START]], [[DOC_OWNER]]"
!else
!define PAGE_RIGHT_FOOTER_CENTER1  ""
!endif
!define PAGE_RIGHT_FOOTER_CENTER2  ''
!define PAGE_RIGHT_FOOTER_OUTER1   "Page {{PAGENUM:}} of {{PAGECOUNT:}}"
!define PAGE_RIGHT_FOOTER_OUTER2   '[[DOC_ID]][[$var{"DOC_STATUS"} ? " ($var{\'DOC_STATUS\'})" : ""]]'

# Build the left page as a mirror of the right page
!left_mirror_right_page
sdf-2.001/perllib/sdf/home/look/simple/rtf.sdn010064400042570001753000000054400636603141200210150ustar00iancmtr00000400000236# $Id$
#
# >>Title::	RTF Tuning (simple look)
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 10-Feb-97 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# The {{simple/rtf.sdn}} module provides the mapping of sdf styles to
# rtf styles.
#
# >>Description::
#
# >>Limitations::
#

#!message "Using rtf mapping tables"

# Inherit the standard configuration
!use 'stdlib/rtf.sdn'

################ Mapping tables ###################

!block parastyles
Name        To                      Attributes

# normal paragraphs
N           Normal
FIRST       Normal
L1          List Continue
L2          List Continue 2
L3          List Continue 3
L4          List Continue 4
L5          List Continue 5
L6          List Continue 6

# headings
H1          Heading 1
H2          Heading 2
H3          Heading 3
H4          Heading 4
H5          Heading 5
H6          Heading 6
P1          Heading 1
P2          Heading 2
P3          Heading 3
P4          Heading 4
P5          Heading 5
P6          Heading 6
A1          Heading 1
A2          Heading 2
A3          Heading 3
A4          Heading 4
A5          Heading 5
A6          Heading 6

# list items
LU1         List Bullet
LU2         List Bullet 2
LU3         List Bullet 3
LU4         List Bullet 4
LU5         List Bullet 5
LU6         List Bullet 6
LF1         List Number
LF2         List Number 2
LF3         List Number 3
LF4         List Number 4
LF5         List Number 5
LF6         List Number 6
LN1         List Number
LN2         List Number 2
LN3         List Number 3
LN4         List Number 4
LN5         List Number 5
LN6         List Number 6
!endblock


################ Define paragraph formats ###################

!block targetobjects; type="Para"
Name                Parent
Normal              b0_Body
List Continue       l0_ListBody
List Continue 2     l1_ListBody
List Continue 3     l2_ListBody
List Continue 4     l3_ListBody
List Continue 5     l4_ListBody
List Continue 6     l5_ListBody
Heading 1           h1_Heading
Heading 2           h2_Heading
Heading 3           h3_Heading
Heading 4           h4_Heading
Heading 5           h5_Heading
Heading 6           h5_Heading
List Bullet         u0_Unordered
List Bullet 2       u1_Unordered
List Bullet 3       u2_Unordered
List Bullet 4       u3_Unordered
List Bullet 5       u4_Unordered
List Bullet 6       u5_Unordered
List Number         on0_OrderedNext
List Number 2       on1_OrderedNext
List Number 3       on2_OrderedNext
List Number 4       on3_OrderedNext
List Number 5       on4_OrderedNext
List Number 6       on5_OrderedNext
!endblock
e      Who     Change
# 10-Feb-97 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# The {{simple/rtf.sdn}} module provides the mapping of sdf styles to
# rtf stylessdf-2.001/perllib/sdf/home/look/simple/fax.sds010064400042570001753000000011370630323423200210000ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Fax Style
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 08-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{fax}} is an [[SDF]] style for fascimiles.
#
# >>Description::
#
# >>Limitations::
#

# Use the admin style with an appropriate default title
!default DOC_TYPE "FASCIMILE"
!use "admin.sds"
sdf-2.001/perllib/sdf/home/look/simple/minutes.sds010064400042570001753000000011710630323423200217040ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Minutes Style
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 08-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{minutes}} is an [[SDF]] style for minutes of meetings.
#
# >>Description::
#
# >>Limitations::
#

# Use the admin style with an appropriate default title
!default DOC_TYPE "MINUTES OF MEETING"
!use "admin.sds"
sdf-2.001/perllib/sdf/home/look/simple/covers.sdm010064400042570001753000000176560644370202400215360ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Covers Module
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 07-Jan-97 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{covers}} contains the definitions of SDF's pre-defined cover pages.
#
# >>Description::
#
# >>Limitations::
#

# This is needed for the hyphenation macros
# (which should probably be predefined via stdlib.sdm)
!use "misc"

# Define the "original" cover page
!macro build_original_cover

    # Request a table of contents
    !default DOC_TOC 3

    # Build the cover contents
    !build_original_cover_top
    !build_original_cover_approval
    #PB:
    !if $macro{'DOC_RECIPIENTS'}
    !build_original_cover_inside
    !endif
!endmacro

!macro build_original_cover_top
    !default DOC_TITLE_LOGO $var{'DOC_LOGO'}
    !if DOC_TITLE_LOGO
        DDist: {{IMPORT[align=Left;wrap_text][[DOC_TITLE_LOGO]]}}[[DOC_DISTRIBUTION]]
    !else
        DDist: [[DOC_DISTRIBUTION]]
    !endif
    DProj: [[DOC_PROJECT]]
    DName: [[DOC_NAME]]
    DType: [[DOC_TYPE]]
    !if DOC_STATUS
        DStat: ([[DOC_STATUS]])
    !endif
    !if DOC_ID
        DCode: [[DOC_ID]]
    !else
        DSkip: 
    !endif
    !if $macro{'DOC_RECIPIENTS'}
        DCopy: _____
    !else
        DSkip: 
    !endif
    DSkip: 
    DSkip: 
    !if DOC_AUTHOR
        #dActn: PREPARED BY:
        DAuth: [[DOC_AUTHOR]]
    !endif
    !if DOC_AUTHOR2
        DAuth: [[DOC_AUTHOR2]]
    !endif
    !if DOC_AUTHOR3
        DAuth: [[DOC_AUTHOR3]]
    !endif
!endmacro

!macro build_original_cover_approval
    !if DOC_APPROVE
        DActn: APPROVED BY:
        DAppr: [[DOC_APPROVE]]
    !endif
    !if DOC_APPROVE2
        DAppr: [[DOC_APPROVE2]]
    !endif
    !if DOC_APPROVE3
        DAppr: [[DOC_APPROVE3]]
    !endif
!endmacro

!macro build_original_cover_inside
    P2[top;notoc]Copyright

    Copyright [[c]] [[_DOC_YEAR]], [[DOC_OWNER]]

    All rights reserved.

    No part of this document may be reproduced, transferred, sold, or 
    otherwise disposed of, without the written permission
    of [[DOC_OWNER]].

    This document was generated using [[SDF]] [[SDF_VERSION]].

    P2[notoc]Document control

    This document is deemed to be controlled only as long as
    the project to which it relates is active. Controlled printed
    copies have a {{2:red}} {{Copy number}} on the front cover and
    will be distributed to each of the people (numbered) below.
    A copy number of "*" indicates that the person will only be
    notified by email of updates to the document.

    !DOC_RECIPIENTS

    Once the project is completed or terminated, this document will revert
    to an uncontrolled document status. No further advice will be
    provided, and each recipient may either destroy the document or mark
    it as obsolete and retain it for future personal reference.
!endmacro


# Define the "project" cover page
!macro build_project_cover

    # Request a table of contents
    !default DOC_TOC 3

    # Remove the front footer
    !define PAGE_FIRST_FOOTER_CENTER1 ''

    # Build the cover contents
    !hyphen off
    !build_project_cover_top
    !build_project_cover_approval
    !build_project_cover_copyright
    !hyphen on
    #PB:
    !if $macro{'DOC_RECIPIENTS'}
    !build_project_cover_inside
    !endif
!endmacro

!macro build_project_cover_top
!default DOC_TITLE_LOGO $var{'DOC_LOGO'}
!if DOC_TITLE_LOGO
N[sp_after="50pt"]{{IMPORT[align=Right;wrap_text][[DOC_TITLE_LOGO]]}}
!else
N[sp_after="50pt"]
!endif
!block sdf; align='Center'; size="18pt"; bold; wide
N: [[DOC_PROJECT]]
E:
N: [[DOC_NAME]]
N: [[DOC_TYPE]]
E:
N: [[UPPER:DOC_STATUS]]
!endblock

# Document attributes
!define _format $var{'DOC_PAGE_WIDTH'} < 576 ? '40,60' : '25,75'
N[sp_before="20pt"]
!block table; noheadings; tags="B"; style="box"; format=_format; wide
Name            Value
Document Id:    [[DOC_ID]]
URL:            [[DOC_URL]]
Author:         [[DOC_AUTHOR]]
Effective Date: [[DATE:DOC_MODIFIED]]
!if $macro{'DOC_RECIPIENTS'}
Copy Number:    ____
!else
                {{EX: }}
!endif
!endblock
!endmacro

!macro build_project_cover_approval
!if DOC_APPROVE2
N[sp_before="10pt"]
!block table; noheadings; tags="B,N,B"; style="plain"; format='25,45,10,20'; wide
Name            Value                               Name2       Value2
Authorised:     ___________________________         Date:       __________
                {{N[size='8pt'][[DOC_APPROVE]]}}
{{EX: }}
Authorised:     ___________________________         Date:       __________
                {{N[size='8pt'][[DOC_APPROVE2]]}}
!endblock
!elsif DOC_APPROVE
N[sp_before="10pt"]
!block table; noheadings; tags="B,N,B"; style="plain"; format='25,45,10,20'; wide
Name            Value                               Name2       Value2
Authorised:     ___________________________         Date:       __________
                {{N[size='8pt'][[DOC_APPROVE]]}}
!endblock
N[sp_before="10pt"]
!else
N[sp_before="50pt"]
!endif
!endmacro

!macro build_project_cover_copyright
N[sp_before="10pt"]
!if $macro{'DOC_COPYRIGHT'}
!block sdf; align='Center'; wide
!DOC_COPYRIGHT
!endblock
!else
!block sdf; align='Center'; wide; bold; sp_before=0; sp_after=0; size='10pt'
N: COPYRIGHT
N: Copyright [[c]] [[_DOC_YEAR]], [[DOC_OWNER]]
N: All rights reserved.
E:
N: This document and all related documentation is the property of
[[DOC_OWNER]] and may not be sold, transferred or otherwise
disposed of without the written permission of the owners.
E:
N: COMMERCIAL IN CONFIDENCE
!endblock
!endif
!endmacro

!macro build_project_cover_inside

    P2[top;notoc]Document control

    P3[notoc] Copy numbers

    This document is deemed to be controlled only as long as
    the project to which it relates is active. Controlled printed
    copies have a {{red}} copy number on the front cover and
    will be distributed to each of the people below.
    A copy number of "*" indicates that the person will only be
    notified by E-mail of updates to the document.

    P3[notoc] Recipients

    !DOC_RECIPIENTS

    P3[notoc] At completion of project

    Once the project is completed or terminated, this document will revert
    to an uncontrolled document status. No futher advice will be
    provided, and each recipient can either destroy the document or mark
    it as obsolete and retain it for future personal reference.

    P3[notoc] Tools

    This document was generated using [[SDF]] [[SDF_VERSION]].
!endmacro


# Define the "manual" cover page
!macro build_manual_cover

    # Request a table of contents
    !default DOC_TOC 3

    # Build the cover contents
    !build_manual_cover_top
    !build_manual_cover_inside
!endmacro

!macro build_manual_cover_top
    [align=Right;family=Helvetica;size="33pt"] [[DOC_TITLE]]
    !default DOC_MANUAL_LOGO $var{'DOC_LOGO'}
    !if DOC_MANUAL_LOGO
        {{IMPORT[align=Right;position=Bottom][[DOC_MANUAL_LOGO]]}}
    !endif

    # Put the project name in the footer
    !define PAGE_FIRST_FOOTER_INNER0  '[[DOC_PROJECT]]'
!endmacro

!macro build_manual_cover_inside
    P3[top;notoc]Copyright

    !if $macro{'DOC_COPYRIGHT'}
    !DOC_COPYRIGHT
    !else
    Copyright [[c]] [[_DOC_YEAR]], [[DOC_OWNER]]

    All rights reserved.

    No part of this document may be reproduced, transferred, sold, or 
    otherwise disposed of, without the written permission
    of the owner.
    !endif

    P3[notoc]Trademarks

    !if $macro{'DOC_TRADEMARKS'}
    !DOC_TRADEMARKS
    !else
    All the trademarks mentioned in this document are the property of
    their respective owners.
    !endif

    P3[notoc]Tools

    !if $macro{'DOC_TOOLS'}
    !DOC_TOOLS
    !else
    This document was generated using [[SDF]] [[SDF_VERSION]].
    !endif

!endmacro

# Define the "paper" cover page
!macro build_paper_cover
!define DOC_TOC 0
P1[align='Center'] [[DOC_TITLE]]
N[align='Center']   {{[[DOC_AUTHOR]]}}
E:
!endmacro
VE3
        DAppr: [[DOC_APPROVE3]]
    !endif
!endmacro

!macro build_original_cosdf-2.001/perllib/sdf/home/look/simple/manual.sds010064400042570001753000000072340636307162200215130ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Manual Style
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 01-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{manual}} is an [[SDF]] style for manuals.
#
# >>Description::
#
# >>Limitations::
# As [[FrameMaker]] has difficult with total page counts for a book,
# the total page count is not currently output if a manual is being generated.
#

# Load the cover page definitions
!use "covers"

# Provide the default cover page setting
!default DOC_COVER "manual"

# Assume two-sided documents, by default
!default DOC_TWO_SIDES

# Assume numbering per section, by default
!default OPT_NUMBER_PER_COMPONENT

# Build the borders
!default OPT_BORDERS 1
!build_borders

# Define the number of header/footer lines
!default OPT_HEADINGS 4

# Setup defaults to eliminate warning messages for files without a title
!block default; family="DOC"
Name            Value
NAME            ''
TYPE            ''
PROJECT         ''
ID              ''
URL             ''
!endblock

# Define the first page footer
!define PAGE_FIRST_FOOTER_INNER0  ''
!define PAGE_FIRST_FOOTER_INNER1  ''
!define PAGE_FIRST_FOOTER_INNER2  ''
!define PAGE_FIRST_FOOTER_INNER3  ''
!define PAGE_FIRST_FOOTER_CENTER0 ''
!define PAGE_FIRST_FOOTER_CENTER1 ''
!define PAGE_FIRST_FOOTER_CENTER2 ''
!define PAGE_FIRST_FOOTER_CENTER3 ''
!define PAGE_FIRST_FOOTER_OUTER0  ''
!define PAGE_FIRST_FOOTER_OUTER1  ''
!define PAGE_FIRST_FOOTER_OUTER2  ''
!define PAGE_FIRST_FOOTER_OUTER3  ''

# Define the right page header
!define PAGE_RIGHT_HEADER_INNER1   ''
!define PAGE_RIGHT_HEADER_INNER2   ''
!define PAGE_RIGHT_HEADER_CENTER1  ''
!define PAGE_RIGHT_HEADER_CENTER2  ''
!define PAGE_RIGHT_HEADER_OUTER1   '{{B:{{PARATEXT:H1,A1,P1}}}}'
!define PAGE_RIGHT_HEADER_OUTER2   '{{PARATEXT:H2,A2,P2}}'

# Define the right page footer
#!define PAGE_RIGHT_FOOTER_INNER0   '{{PARASHORT:}}'
!define PAGE_RIGHT_FOOTER_INNER0   '[[$var{"DOC_PROJECT"}]]'
!define PAGE_RIGHT_FOOTER_INNER1   '[[DOC_ID]]'
!define PAGE_RIGHT_FOOTER_INNER2   '[[CONCISE:DOC_MODIFIED]]'
!define PAGE_RIGHT_FOOTER_INNER3   "[[c]] [[DOC_OWNER]]"
!define PAGE_RIGHT_FOOTER_CENTER0  ''
!define PAGE_RIGHT_FOOTER_CENTER1  ''
!define PAGE_RIGHT_FOOTER_CENTER2  '{{A[size="12pt"][[$var{"DOC_STATUS"} && $var{"DOC_STATUS"} ne "Final" ? " ($var{\'DOC_STATUS\'})" : ""]]}}'
!define PAGE_RIGHT_FOOTER_CENTER3  ''
!define PAGE_RIGHT_FOOTER_OUTER0   ''
!define PAGE_RIGHT_FOOTER_OUTER1   ''
!define PAGE_RIGHT_FOOTER_OUTER2   "{{B[size='12pt']{{PAGENUM:}}}}"
!define PAGE_RIGHT_FOOTER_OUTER3   ''

# Build the left page as a mirror of the right page
!left_mirror_right_page

# Adjust the headers for derived components
!define PAGE_TOC_RIGHT_HEADER_OUTER1   '{{B:[[DOC_TITLE]]}}'
!define PAGE_TOC_RIGHT_HEADER_OUTER2   '[[DOC_TOC_TITLE]]'
!define PAGE_TOC_LEFT_HEADER_OUTER1    '{{B:[[DOC_TITLE]]}}'
!define PAGE_TOC_LEFT_HEADER_OUTER2    '[[DOC_TOC_TITLE]]'
!define PAGE_IX_RIGHT_HEADER_OUTER1    '{{B:[[DOC_TITLE]]}}'
!define PAGE_IX_RIGHT_HEADER_OUTER2    '[[DOC_TOC_TITLE]]'
!define PAGE_IX_LEFT_HEADER_OUTER1     '{{B:[[DOC_TITLE]]}}'
!define PAGE_IX_LEFT_HEADER_OUTER2     '[[DOC_TOC_TITLE]]'

# Adjust the headers for special components after the contents
!define PAGE_PRECHAPTER_RIGHT_HEADER_OUTER1   '{{B:[[DOC_TITLE]]}}'
!define PAGE_PRECHAPTER_RIGHT_HEADER_OUTER2   '{{PARATEXT:P2}}'
!define PAGE_PRECHAPTER_LEFT_HEADER_OUTER1    '{{B:[[DOC_TITLE]]}}'
!define PAGE_PRECHAPTER_LEFT_HEADER_OUTER2    '{{PARATEXT:P2}}'
sdf-2.001/perllib/sdf/home/look/overhead/004075500042570001753000000000000672243771700200365ustar00iancmtr00000400000236sdf-2.001/perllib/sdf/home/look/overhead/overhead.sdm010064400042570001753000000010350630523522600223200ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Overhead Look
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 09-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{overhead}} is an [[SDF]] look for user documentation.
#
# >>Description::
#
# >>Limitations::
#

# Do nothing for now
sdf-2.001/perllib/sdf/home/look/overhead/mif.sdn010064400042570001753000000552240636603141200213060ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Overhead MIF Tuning
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 01-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# This module provides the mif objects required for the overhead look.
#
# >>Description::
#
# >>Limitations::
#

################ Useful constants ###################

# Define useful list indent values
!define _LI1 $var{'OPT_LIST_INDENT'}*1 . "pt"
!define _LI2 $var{'OPT_LIST_INDENT'}*2 . "pt"
!define _LI3 $var{'OPT_LIST_INDENT'}*3 . "pt"
!define _LI4 $var{'OPT_LIST_INDENT'}*4 . "pt"
!define _LI5 $var{'OPT_LIST_INDENT'}*5 . "pt"
!define _LI6 $var{'OPT_LIST_INDENT'}*6 . "pt"

# Define center and right tabs
# (Should the right tab use AREA_WIDTH?)
!define _TABC $var{'DOC_FULL_WIDTH'}/2 . "pt"
!define _TABR $var{'DOC_FULL_WIDTH'} . "pt"


################ Core paragraph formats ###################

# Define the root 'Para' format
!targetobject "Para"; "b0_Body";; \
  Alignment=Left; \
  AutoNum=0; \
  BlockSize=2; \
  BotSepAtIndent=0; \
  BotSepOffset='0.0"'; \
  BotSeparator=""; \
  CellAlignment=Top; \
  CellBMarginFixed=0; \
  CellLMarginFixed=0; \
  CellMargins="0.0 pt 0.0 pt 0.0 pt 0.0 pt"; \
  CellRMarginFixed=0; \
  CellTMarginFixed=0; \
  FIndent='0.5"'; \
  FIndentOffset='0.0"'; \
  FIndentRelative=0; \
  FontAngle=Regular; \
  FontCase="FAsTyped"; \
  FontChangeBar=0; \
  FontColor=Black; \
  FontDW="0.0%"; \
  FontDX="0.0%"; \
  FontDY="0.0%"; \
  FontFamily=Times; \
  FontLocked=0; \
  FontOutline=0; \
  FontOverline=0; \
  FontPairKern=Yes; \
  FontPosition="FNormal"; \
  FontSeparation=0; \
  FontShadow=0; \
  FontSize="24.0 pt"; \
  FontStrike=0; \
  FontUnderlining="FNoUnderlining"; \
  FontVar=Regular; \
  FontWeight=Regular; \
  HyphenMaxLines=2; \
  HyphenMinPrefix=3; \
  HyphenMinSuffix=3; \
  HyphenMinWord=5; \
  Hyphenate=Yes; \
  LIndent='0.5"'; \
  Language="UKEnglish"; \
  Leading="2.0 pt"; \
  LetterSpace=0; \
  LineSpacing=Fixed; \
  Locked=0; \
  MaxWordSpace=110; \
  MinWordSpace=90; \
  NextTag=""; \
  OptWordSpace=100; \
  Placement=Anywhere; \
  PlacementStyle=Normal; \
  RIndent='0.0"'; \
  RunInDefaultPunct=". "; \
  SpAfter="6.0 pt"; \
  SpBefore="12.0 pt"; \
  TabStop='0.5",1.0",1.5",2.0",2.5",3.0",3.5"'; \
  TopSepAtIndent=0; \
  TopSepOffset='0.0"'; \
  TopSeparator=""; \
  UseNextTag=0; \
  WithNext=0; \
  WithPrev=0


# Define the other 'Para' formats
!targetobject "Para"; "f0_FirstBody"; "b0_Body"; \
  FontFamily=Helvetica; \
  SpAfter="14.0 pt"; \
  SpBefore="14.0 pt"

!targetobject "Para"; "fn_Footnote"; "b0_Body"; \
  BlockSize=1; \
  FIndent='0.0"'; \
  FontSize="10.0 pt"; \
  LIndent='0.0"'; \
  SpAfter="0.0 pt"; \
  SpBefore="3.0 pt"; \
  TabStop=""

!targetobject "Para"; "Footer"; "b0_Body"; \
  BlockSize=1; \
  FIndent='0.0"'; \
  FontPairKern=0; \
  FontSize="10.0 pt"; \
  HyphenMinPrefix=2; \
  HyphenMinSuffix=2; \
  Hyphenate=0; \
  LIndent='0.0"'; \
  MaxWordSpace=125; \
  MinWordSpace=75; \
  SpAfter="0.0 pt"; \
  SpBefore="0.0 pt"; \
  TabStop="$var{'_TABC'}/Center,$var{'_TABR'}/Right"

!targetobject "Para"; "Header"; "Footer"


################ Heading paragraph formats ###################

!targetobject "Para"; "h1_Heading"; "b0_Body"; \
  FIndent='0.0"'; \
  FontAngle=Oblique; \
  FontFamily=Helvetica; \
  FontSize="36.0 pt"; \
  Hyphenate=0; \
  Placement="RPageTop"; \
  SpAfter="32.0 pt"; \
  SpBefore="32.0 pt"; \
  TabStop="$var{'_TABR'}/Right/. "; \
  WithNext=Yes

!targetobject "Para"; "h2_Heading"; "h1_Heading"; \
  FontAngle=Regular; \
  FontSize="30.0 pt"; \
  FontWeight=Bold; \
  Placement=Anywhere; \
  SpAfter="17.0 pt"; \
  SpBefore="24.0 pt"; \
  TabStop='0.5",1.0",1.5",2.0",2.5",3.0"'

!targetobject "Para"; "h3_Heading"; "h2_Heading"; \
  FIndent='0.5"'; \
  FontSize="12.0 pt"; \
  SpAfter="8.0 pt"; \
  SpBefore="12.0 pt"

!targetobject "Para"; "h4_Heading"; "h3_Heading"; \
  FontSize="11.0 pt"

!targetobject "Para"; "a1_Appendix"; "h1_Heading"; \
  FontAngle=Regular; \
  FontSize="18.0 pt"; \
  FontWeight=Bold; \
  LIndent='1.583"'; \
  Placement="PageTop"; \
  SpAfter="8.0 pt"; \
  SpBefore="12.0 pt"; \
  TabStop='1.6"'

!targetobject "Para"; "a2_Appendix"; "h2_Heading"; \
  FontSize="14.0 pt"; \
  SpAfter="8.0 pt"; \
  SpBefore="12.0 pt"

!targetobject "Para"; "a3_Appendix"; "h3_Heading"; \
  AutoNum=Yes; \
  FIndent='0.0"'; \
  NumAtEnd=0; \
  NumFormat='A:..\\t'

!targetobject "Para"; "a4_Appendix"; "h4_Heading"; \
  FontSize="12.0 pt"

!targetobject "Para"; "p1_PlainHeading"; "h1_Heading"; \
  FontAngle=Regular; \
  FontSize="18.0 pt"; \
  FontWeight=Bold; \
  Placement="PageTop"; \
  SpAfter="8.0 pt"; \
  SpBefore="12.0 pt"; \
  TabStop='0.5",1.0",1.5",2.0",2.5",3.0"'


################ List paragraph formats ###################

!targetobject "Para"; "l0_ListBody"; "b0_Body"; \
  BlockSize=3; \
  FIndent='0.7"'; \
  LIndent='0.7"'; \
  SpAfter="14.0 pt"; \
  SpBefore="14.0 pt"; \
  TabStop='0.7"'

!targetobject "Para"; "l1_ListBody"; "l0_ListBody"; \
  FIndent='1.0"'; \
  FontSize="12.0 pt"; \
  LIndent='1.2"'; \
  SpAfter="0.0 pt"; \
  SpBefore="6.0 pt"; \
  TabStop='1.2"'

!targetobject "Para"; "l2_ListBody"; "l1_ListBody"; \
  FIndent='1.5"'; \
  LIndent='1.7"'; \
  TabStop='1.7"'

!targetobject "Para"; "u0_Unordered"; "b0_Body"; \
  AutoNum=Yes; \
  BlockSize=3; \
  FontFamily=Helvetica; \
  LIndent='0.7"'; \
  NumAtEnd=0; \
  NumFormat='\xa5 \\t'; \
  NumberFont="Bullet Symbol"; \
  SpAfter="14.0 pt"; \
  SpBefore="14.0 pt"; \
  TabStop='0.7"'

!targetobject "Para"; "u1_Unordered"; "u0_Unordered"; \
  FIndent='1.0"'; \
  FontFamily=Times; \
  LIndent='1.2"'; \
  SpAfter="6.0 pt"; \
  SpBefore="6.0 pt"; \
  TabStop='1.2"'

!targetobject "Para"; "u2_Unordered"; "u1_Unordered"; \
  FIndent='1.5"'; \
  LIndent='1.7"'; \
  SpAfter="14.0 pt"; \
  SpBefore="14.0 pt"; \
  TabStop='1.7"'

!targetobject "Para"; "oi0_OrderedInit"; "u0_Unordered"; \
  NumFormat='L:.\\t'; \
  NumberFont=Bold; \
  TabStop='0.8"'

!targetobject "Para"; "oi1_OrderedInit"; "oi0_OrderedInit"; \
  FIndent='1.0"'; \
  FontFamily=Times; \
  FontSize="12.0 pt"; \
  LIndent='1.2"'; \
  NumFormat='M:.\\t'; \
  NumberFont=""; \
  SpAfter="0.0 pt"; \
  SpBefore="6.0 pt"; \
  TabStop='1.2"'

!targetobject "Para"; "oi2_OrderedInit"; "oi1_OrderedInit"; \
  FIndent='1.5"'; \
  LIndent='1.7"'; \
  NumFormat='N:.\\t'; \
  TabStop='1.7"'

!targetobject "Para"; "on0_OrderedNext"; "oi0_OrderedInit"; \
  NumFormat='L:.\\t'

!targetobject "Para"; "on1_OrderedNext"; "oi1_OrderedInit"; \
  NumFormat='M:.\\t'

!targetobject "Para"; "on2_OrderedNext"; "oi2_OrderedInit"; \
  NumFormat='N:.\\t'

!targetobject "Para"; "s0_SimpleList"; "l0_ListBody"; \
  FontFamily=Helvetica

!targetobject "Para"; "s1_SimpleList"; "l1_ListBody"; \
  FIndent='1.2"'; \
  FontSize="24.0 pt"; \
  SpAfter="6.0 pt"

!targetobject "Para"; "s2_SimpleList"; "l2_ListBody"; \
  FIndent='1.7"'; \
  FontSize="24.0 pt"; \
  SpAfter="14.0 pt"; \
  SpBefore="14.0 pt"


################ Figure/table paragraph formats ###################

!targetobject "Para"; "CellBody"; "b0_Body"; \
  FIndent='0.0"'; \
  FontSize="18.0 pt"; \
  Hyphenate=0; \
  LIndent='0.0"'; \
  Leading="4.0 pt"; \
  SpAfter="0.0 pt"; \
  SpBefore="0.0 pt"; \
  TabStop=""

!targetobject "Para"; "CellHeading"; "CellGroup"; \
  Alignment=Left; \
  AutoNum=0; \
  BlockSize=2; \
  BotSepAtIndent=0; \
  BotSepOffset='0.0"'; \
  BotSeparator=""; \
  CellAlignment=Top; \
  CellBMarginFixed=0; \
  CellLMarginFixed=0; \
  CellMargins="0.0 pt 0.0 pt 0.0 pt 0.0 pt"; \
  CellRMarginFixed=0; \
  CellTMarginFixed=0; \
  FIndent='0.0"'; \
  FIndentOffset='0.0"'; \
  FIndentRelative=0; \
  FontAngle=Regular; \
  FontCase="FAsTyped"; \
  FontChangeBar=0; \
  FontColor=Black; \
  FontDW="0.0%"; \
  FontDX="0.0%"; \
  FontDY="0.0%"; \
  FontFamily=Times; \
  FontLocked=0; \
  FontOutline=0; \
  FontOverline=0; \
  FontPairKern=Yes; \
  FontPosition="FNormal"; \
  FontSeparation=0; \
  FontShadow=0; \
  FontSize="18.0 pt"; \
  FontStrike=0; \
  FontUnderlining="FNoUnderlining"; \
  FontVar=Regular; \
  FontWeight=Bold; \
  HyphenMaxLines=2; \
  HyphenMinPrefix=3; \
  HyphenMinSuffix=3; \
  HyphenMinWord=5; \
  Hyphenate=0; \
  LIndent='0.0"'; \
  Language="UKEnglish"; \
  Leading="4.0 pt"; \
  LetterSpace=0; \
  LineSpacing=Fixed; \
  Locked=0; \
  MaxWordSpace=110; \
  MinWordSpace=90; \
  NextTag=""; \
  OptWordSpace=100; \
  Placement=Anywhere; \
  PlacementStyle=Normal; \
  RIndent='0.0"'; \
  RunInDefaultPunct=". "; \
  SpAfter="0.0 pt"; \
  SpBefore="0.0 pt"; \
  TabStop=""; \
  TopSepAtIndent=0; \
  TopSepOffset='0.0"'; \
  TopSeparator=""; \
  UseNextTag=0; \
  WithNext=0; \
  WithPrev=0

!targetobject "Para"; "ft_FigureTitle"; "b0_Body"; \
  Alignment=Center; \
  AutoNum=Yes; \
  BotSeparator="Table Rule"; \
  FIndent='0.0"'; \
  FontSize="10.0 pt"; \
  Hyphenate=0; \
  LIndent='0.0"'; \
  Leading="0.0 pt"; \
  NumAtEnd=0; \
  NumFormat='F:Figure . '; \
  NumberFont=Bold; \
  SpAfter="16.0 pt"; \
  TabStop=""

!targetobject "Para"; "tf_TableFootnote"; "ta_TableAnchor"; \
  Alignment=Left; \
  AutoNum=0; \
  BlockSize=1; \
  BotSepAtIndent=0; \
  BotSepOffset='0.0"'; \
  BotSeparator=""; \
  CellAlignment=Top; \
  CellBMarginFixed=0; \
  CellLMarginFixed=0; \
  CellMargins="0.0 pt 0.0 pt 0.0 pt 0.0 pt"; \
  CellRMarginFixed=0; \
  CellTMarginFixed=0; \
  FIndent='0.6"'; \
  FIndentOffset='0.0"'; \
  FIndentRelative=0; \
  FontAngle=Regular; \
  FontCase="FAsTyped"; \
  FontChangeBar=0; \
  FontColor=Black; \
  FontDW="0.0%"; \
  FontDX="0.0%"; \
  FontDY="0.0%"; \
  FontFamily=Times; \
  FontLocked=0; \
  FontOutline=0; \
  FontOverline=0; \
  FontPairKern=Yes; \
  FontPosition="FNormal"; \
  FontSeparation=0; \
  FontShadow=0; \
  FontSize="10.0 pt"; \
  FontStrike=0; \
  FontUnderlining="FNoUnderlining"; \
  FontVar=Regular; \
  FontWeight=Regular; \
  HyphenMaxLines=2; \
  HyphenMinPrefix=3; \
  HyphenMinSuffix=3; \
  HyphenMinWord=5; \
  Hyphenate=Yes; \
  LIndent='0.6"'; \
  Language="UKEnglish"; \
  Leading="2.0 pt"; \
  LetterSpace=0; \
  LineSpacing=Fixed; \
  Locked=0; \
  MaxWordSpace=110; \
  MinWordSpace=90; \
  NextTag=""; \
  OptWordSpace=100; \
  Placement=Anywhere; \
  PlacementStyle=Normal; \
  RIndent='0.25"'; \
  RunInDefaultPunct=". "; \
  SpAfter="0.0 pt"; \
  SpBefore="3.0 pt"; \
  TabStop=""; \
  TopSepAtIndent=0; \
  TopSepOffset='0.0"'; \
  TopSeparator=""; \
  UseNextTag=0; \
  WithNext=0; \
  WithPrev=0

!targetobject "Para"; "tt_TableTitle"; "b0_Body"; \
  AutoNum=Yes; \
  FIndent='0.6"'; \
  FontSize="11.0 pt"; \
  Hyphenate=0; \
  LIndent='1.2"'; \
  NumAtEnd=0; \
  NumFormat='T:TABLE . '; \
  SpAfter="0.0 pt"; \
  SpBefore="11.0 pt"; \
  TabStop=""


################ Miscellaneous paragraph formats ###################

!targetobject "Para"; "e0_Example"; "b0_Body"; \
  FontFamily=Courier; \
  FontPairKern=0; \
  FontSize="18.0 pt"; \
  Hyphenate=0; \
  Language="NoLanguage"; \
  Leading="0.0 pt"; \
  MaxWordSpace=100; \
  MinWordSpace=100; \
  SpAfter="0.0 pt"; \
  SpBefore="0.0 pt"

!targetobject "Para"; "et_ExampleTitle"; "b0_Body"; \
  AutoNum=Yes; \
  BotSeparator="Table Rule"; \
  FIndent='0.6"'; \
  FontSize="11.0 pt"; \
  Hyphenate=0; \
  LIndent='0.6"'; \
  Leading="0.0 pt"; \
  NumAtEnd=0; \
  NumFormat='E:Example . '; \
  NumberFont=Bold; \
  SpAfter="18.0 pt"; \
  SpBefore="13.0 pt"; \
  TabStop=""

!targetobject "Para"; "gl_Glossary"; "b0_Body"; \
  FontFamily=Helvetica; \
  FontSize="10.0 pt"; \
  LIndent='1.5"'; \
  SpAfter="2.0 pt"; \
  SpBefore="0.0 pt"; \
  TabStop='1.5"'

!targetobject "Para"; "si_StepInit"; "oi0_OrderedInit"; \
  FontFamily=Times; \
  FontSize="12.0 pt"; \
  NumFormat='S:.\\t'; \
  SpAfter="0.0 pt"; \
  SpBefore="6.0 pt"; \
  TabStop='0.7"'

!targetobject "Para"; "sn_StepNext"; "si_StepInit"; \
  NumFormat='S:.\\t'

!targetobject "Para"; "st_StepTitle"; "sn_StepNext"; \
  AutoNum=0; \
  FontWeight=Bold; \
  NumAtEnd=""; \
  NumFormat=""; \
  NumberFont=""


################ Cover page & title block paragraph formats ###################

!targetobject "Para"; "da_DocAction"; "b0_Body"; \
  FontSize="14.0 pt"; \
  FontWeight=Bold; \
  SpAfter="10.0 pt"; \
  SpBefore="20.0 pt"; \
  TabStop=""

!targetobject "Para"; "dc_DocCode"; "da_DocAction"; \
  Alignment=Center; \
  AutoNum=Yes; \
  FontSize="18.0 pt"; \
  NumAtEnd=0; \
  NumFormat="Document No: "; \
  SpAfter="200.0 pt"; \
  SpBefore="40.0 pt"

!targetobject "Para"; "dn_DocName"; "dk_DocSkip"; \
  Alignment=Center; \
  AutoNum=0; \
  BlockSize=2; \
  BotSepAtIndent=0; \
  BotSepOffset='0.0"'; \
  BotSeparator=""; \
  CellAlignment=Top; \
  CellBMarginFixed=0; \
  CellLMarginFixed=0; \
  CellMargins="0.0 pt 0.0 pt 0.0 pt 0.0 pt"; \
  CellRMarginFixed=0; \
  CellTMarginFixed=0; \
  FIndent='0.5"'; \
  FIndentOffset='0.0"'; \
  FIndentRelative=0; \
  FontAngle=Regular; \
  FontCase="FAsTyped"; \
  FontChangeBar=0; \
  FontColor=Black; \
  FontDW="0.0%"; \
  FontDX="0.0%"; \
  FontDY="0.0%"; \
  FontFamily=Helvetica; \
  FontLocked=0; \
  FontOutline=0; \
  FontOverline=0; \
  FontPairKern=Yes; \
  FontPosition="FNormal"; \
  FontSeparation=0; \
  FontShadow=0; \
  FontSize="18.0 pt"; \
  FontStrike=0; \
  FontUnderlining="FNoUnderlining"; \
  FontVar=Regular; \
  FontWeight=Bold; \
  HyphenMaxLines=2; \
  HyphenMinPrefix=3; \
  HyphenMinSuffix=3; \
  HyphenMinWord=5; \
  Hyphenate=Yes; \
  LIndent='0.5"'; \
  Language="UKEnglish"; \
  Leading="2.0 pt"; \
  LetterSpace=0; \
  LineSpacing=Fixed; \
  Locked=0; \
  MaxWordSpace=110; \
  MinWordSpace=90; \
  NextTag=""; \
  OptWordSpace=100; \
  Placement=Anywhere; \
  PlacementStyle=Normal; \
  RIndent='0.0"'; \
  RunInDefaultPunct=". "; \
  SpAfter="80.0 pt"; \
  SpBefore="20.0 pt"; \
  TabStop='0.5",1.0",1.5",2.0",2.5",3.0",3.5"'; \
  TopSepAtIndent=0; \
  TopSepOffset='0.0"'; \
  TopSeparator=""; \
  UseNextTag=0; \
  WithNext=0; \
  WithPrev=0

!targetobject "Para"; "dp_DocProject"; "dn_DocName"; \
  FontFamily=Times; \
  SpAfter="40.0 pt"; \
  SpBefore="0.0 pt"; \
  TabStop=""

!targetobject "Para"; "ds_DocStatus"; "dp_DocProject"; \
  SpAfter="20.0 pt"; \
  SpBefore="20.0 pt"

!targetobject "Para"; "dt_DocType"; "ds_DocStatus"; \
  SpAfter="6.0 pt"; \
  SpBefore="12.0 pt"

!targetobject "Para"; "du_DocAuthor"; "dt_DocType"; \
  FontAngle=Italic; \
  FontWeight=Regular; \
  SpAfter="40.0 pt"; \
  SpBefore="40.0 pt"

!targetobject "Para"; "dw_DocWho"; "du_DocAuthor"; \
  Alignment=Left; \
  AutoNum=Yes; \
  FIndent='1.0"'; \
  FontAngle=Regular; \
  FontSize="12.0 pt"; \
  FontWeight=Bold; \
  LIndent='1.0"'; \
  NumAtEnd=Yes; \
  NumFormat="............................ ...................."; \
  SpAfter="10.0 pt"; \
  SpBefore="10.0 pt"; \
  TabStop='2.0"'

!targetobject "Para"; "dg_DocGeneral"; "b0_Body"; \
  Alignment=Center; \
  FIndent='1.0"'; \
  FontSize="14.0 pt"; \
  LIndent='1.0"'; \
  SpAfter="15.0 pt"; \
  SpBefore="15.0 pt"; \
  TabStop='2.0"'

!targetobject "Para"; "dg_DocText"; "dg_DocGeneral"; \
  FIndent='0.5"'; \
  FontFamily=Helvetica; \
  LIndent='0.5"'; \
  TabStop='0.5",1.0",1.5",2.0",2.5",3.0",3.5"'

!targetobject "Para"; "j2_Heading"; "dg_DocText"; \
  Alignment=Right; \
  Hyphenate=0; \
  SpAfter="8.0 pt"; \
  SpBefore="32.0 pt"; \
  TabStop='1.5"'; \
  WithNext=Yes

# This definition currently causes problems as SDF's escaping
# mechanisms cannot yet handle the embedded ] in the NumFormat attribute
#!targetobject "Para"; "re_Reference"; "j2_Heading"; \
#  Alignment=Left; \
#  AutoNum=Yes; \
#  FontSize="10.0 pt"; \
#  LIndent='1.0"'; \
#  NumAtEnd=0; \
#  NumFormat='R:[]\\t'; \
#  SpBefore="8.0 pt"; \
#  TabStop='1.0",1.5",2.0",2.5",3.0"'; \
#  WithNext=0

!targetobject "Para"; "t3_TableRow"; "b0_Body"; \
  FontFamily=Helvetica; \
  FontSize="18.0 pt"; \
  LIndent='2.5"'; \
  SpAfter="2.0 pt"; \
  SpBefore="0.0 pt"; \
  TabStop='2.5",3.5",4.5",5.5"'

!targetobject "Para"; "tg_TableGroup"; "t3_TableRow"; \
  FontWeight=Bold; \
  LIndent='1.5"'; \
  Leading="4.0 pt"; \
  SpAfter="4.0 pt"; \
  TabStop='1.5",2.5",3.5",4.5",5.5"'

!targetobject "Para"; "th_TableHeader"; "tg_TableGroup"; \
  FontUnderlining="FSingle"; \
  LIndent='0.5"'; \
  Leading="2.0 pt"; \
  SpAfter="6.0 pt"; \
  SpBefore="14.0 pt"; \
  TabStop='2.5",3.5",4.5",5.5"'; \
  WithNext=Yes

!targetobject "Para"; "xt_ExerciseTitle"; "th_TableHeader"; \
  AutoNum=Yes; \
  FIndent='0.0"'; \
  FontUnderlining="FNoUnderlining"; \
  FontWeight=Regular; \
  Hyphenate=0; \
  NumAtEnd=0; \
  NumFormat='X:Exercise .\\t'; \
  NumberFont=Normal; \
  Placement="RPageTop"; \
  SpAfter="8.0 pt"; \
  SpBefore="32.0 pt"; \
  TabStop='1.25"'

!targetobject "Para"; "xt_Extract"; "b0_Body"; \
  FIndent='1.0"'; \
  FontAngle=Italic; \
  LIndent='1.0"'; \
  RIndent='1.0"'; \
  SpAfter="14.0 pt"; \
  SpBefore="14.0 pt"


################ Phrase formats ###################

# Define the root 'Phrase' format
!targetobject "Phrase"; "Emphasis";; \
  Angle=Italic; \
  Locked=0; \
  PairKern=Yes


# Define the other 'Phrase' formats
!targetobject "Phrase"; "Bold"; "Emphasis"; \
  Angle=""; \
  ChangeBar=0; \
  Color=Black; \
  DW="0.0%"; \
  Overline=0; \
  Position="FNormal"; \
  Separation=0; \
  Strike=0; \
  Weight=Bold

!targetobject "Phrase"; "Bold 9 pt"; "Bold"; \
  Angle=Regular; \
  Size="9.0 pt"

!targetobject "Phrase"; "Bold helvetica"; "Bold 9 pt"; \
  Size="12.0 pt"

!targetobject "Phrase"; "Bold italic"; "Bold helvetica"; \
  Angle=Italic; \
  Size="11.0 pt"; \
  Weight=Regular

!targetobject "Phrase"; "Bullet Symbol"; "Bold italic"; \
  Angle=Regular; \
  Outline=0; \
  Shadow=0; \
  Size="12.0 pt"; \
  Weight=Bold

!targetobject "Phrase"; "Callout"; "Bullet Symbol"; \
  Size="10.0 pt"; \
  Weight=Regular

!targetobject "Phrase"; "DiagramBold"; "Callout"; \
  Outline=""; \
  Shadow=""; \
  Size="11.0 pt"; \
  Underlining="FNoUnderlining"; \
  Weight=Bold

!targetobject "Phrase"; "DiagramStd"; "DiagramBold"; \
  Weight=Regular

!targetobject "Phrase"; "Emphasis 9 pt"; "Emphasis"; \
  ChangeBar=0; \
  Color=Black; \
  DW="0.0%"; \
  Overline=0; \
  Position="FNormal"; \
  Separation=0; \
  Size="9.0 pt"; \
  Strike=0; \
  Weight=Regular

!targetobject "Phrase"; "EquationVariables"; "Emphasis"; \
  PairKern=""

!targetobject "Phrase"; "Italic"; "Emphasis"

!targetobject "Phrase"; "Reference document"; "Emphasis"; \
  ChangeBar=0; \
  Color=Black; \
  DW="0.0%"; \
  Overline=0; \
  Position="FNormal"; \
  Separation=0; \
  Size="11.5 pt"; \
  Strike=0; \
  Weight=Regular

!targetobject "Phrase"; "Run-In Heading"; "Reference document"; \
  Angle=Regular; \
  Outline=0; \
  Shadow=0; \
  Size="11.0 pt"; \
  Weight=Bold

!targetobject "Phrase"; "Subscript"; "Emphasis"; \
  Angle=""; \
  Position="FSubscript"

!targetobject "Phrase"; "Superscript"; "Subscript"; \
  Position="FSuperscript"

!targetobject "Phrase"; "Symbol"; "Superscript"; \
  Angle=Regular; \
  ChangeBar=0; \
  Color=Black; \
  DW="0.0%"; \
  Overline=0; \
  Position="FNormal"; \
  Separation=0; \
  Size="11.0 pt"; \
  Strike=0; \
  Weight=Regular

!targetobject "Phrase"; "Fixed"; "Underline"; \
  Size="12.0 pt"; \
  Underlining="FNoUnderlining"

!targetobject "Phrase"; "Normal"; "Fixed"; \
  Size=""


################ Table formats ###################

# Define the root 'Table' format
!targetobject "Table"; "Format A";; \
  Alignment=Left; \
  AltShadePeriod=2; \
  BRuling=""; \
  BlockSize=2; \
  BodyColor=Black; \
  BodyFill=15; \
  BodyRowRuling=""; \
  BodySeparation=0; \
  CellMargins="6.0 pt 4.0 pt 6.0 pt 2.0 pt"; \
  ColumnRuling=""; \
  HFColor=Black; \
  HFFill=15; \
  HFRowRuling=""; \
  HFSeparation=0; \
  InitNumBodyRows=3; \
  InitNumColumns=3; \
  InitNumFRows=0; \
  InitNumHRows=1; \
  LIndent='0.117"'; \
  LRuling=""; \
  LastBRuling=0; \
  Locked=0; \
  NumByColumn=0; \
  Placement=Anywhere; \
  RIndent='0.0"'; \
  RRuling=""; \
  RulingPeriod=4; \
  SeparatorRuling=""; \
  ShadeByColumn=0; \
  ShadePeriod=2; \
  SpAfter="2.0 pt"; \
  SpBefore="12.0 pt"; \
  TRuling=Thin; \
  TitleGap="3.0 pt"; \
  TitlePlacement="InHeader"; \
  XColor=Black; \
  XColumnNum=1; \
  XColumnRuling=""; \
  XFill=15; \
  XRowRuling=""; \
  XSeparation=0


# Define the other 'Table' formats
!targetobject "Table"; "Columns"; "Box"; \
  Alignment=Left; \
  AltShadePeriod=2; \
  BRuling="Very Thin"; \
  BlockSize=4; \
  BodyColor=Black; \
  BodyFill=15; \
  BodyRowRuling=""; \
  BodySeparation=0; \
  CellMargins="6.0 pt 4.0 pt 6.0 pt 2.0 pt"; \
  ColumnRuling="Very Thin"; \
  HFColor=Black; \
  HFFill=15; \
  HFRowRuling=""; \
  HFSeparation=0; \
  InitNumBodyRows=5; \
  InitNumColumns=3; \
  InitNumFRows=0; \
  InitNumHRows=1; \
  LIndent='0.5"'; \
  LRuling="Very Thin"; \
  LastBRuling=0; \
  Locked=0; \
  NumByColumn=0; \
  Placement=Anywhere; \
  RIndent='0.0"'; \
  RRuling="Very Thin"; \
  RulingPeriod=4; \
  SeparatorRuling="Very Thin"; \
  ShadeByColumn=0; \
  ShadePeriod=2; \
  SpAfter="2.0 pt"; \
  SpBefore="4.0 pt"; \
  TRuling="Very Thin"; \
  TitleGap="3.0 pt"; \
  TitlePlacement=None; \
  XColor=Black; \
  XColumnNum=1; \
  XColumnRuling="Very Thin"; \
  XFill=15; \
  XRowRuling=""; \
  XSeparation=0

!targetobject "Table"; "Format B"; "Format A"; \
  SpBefore="4.0 pt"; \
  TRuling=""; \
  TitlePlacement=None

!targetobject "Table"; "Format IC1"; "Format A"; \
  BRuling=Medium; \
  BodyRowRuling="Very Thin"; \
  InitNumBodyRows=14; \
  InitNumColumns=2; \
  LIndent='0.55"'; \
  LRuling=Thin; \
  LastBRuling=Yes; \
  RRuling=Thin; \
  SeparatorRuling=Medium; \
  TRuling=Medium; \
  XColumnRuling=Thin; \
  XRowRuling="Very Thin"

!targetobject "Table"; "Grid"; "Format IC1"; \
  BRuling="Very Thin"; \
  BlockSize=4; \
  ColumnRuling="Very Thin"; \
  InitNumBodyRows=5; \
  InitNumColumns=3; \
  LIndent='0.5"'; \
  LRuling="Very Thin"; \
  LastBRuling=0; \
  RRuling="Very Thin"; \
  SeparatorRuling=Double; \
  SpBefore="4.0 pt"; \
  TRuling="Very Thin"; \
  TitlePlacement=None; \
  XColumnRuling="Very Thin"

!targetobject "Table"; "Plain"; "Format A"; \
  BRuling="Very Thin"; \
  BlockSize=4; \
  InitNumBodyRows=5; \
  LIndent='0.5"'; \
  SeparatorRuling="Very Thin"; \
  SpBefore="4.0 pt"; \
  TRuling="Very Thin"; \
  TitlePlacement=None

!targetobject "Table"; "Rows"; "Plain"; \
  BodyRowRuling="Very Thin"; \
  SeparatorRuling=Thin; \
  XRowRuling="Very Thin"

!targetobject "Table"; "Shade"; "Rows"; \
  BodyRowRuling=""; \
  ColumnRuling="Very Thin"; \
  HFFill=5; \
  LRuling="Very Thin"; \
  RRuling="Very Thin"; \
  SeparatorRuling="Very Thin"; \
  XColumnRuling="Very Thin"; \
  XRowRuling=""

!targetobject "Table"; "Shade1"; "Shade"; \
  AltShadePeriod=1; \
  ShadePeriod=1; \
  XFill=6

!targetobject "Table"; "Shade2"; "Shade1"; \
  BRuling=Thin; \
  ColumnRuling=Thin; \
  HFFill=4; \
  LRuling=Thin; \
  RRuling=Thin; \
  SeparatorRuling=Thin; \
  TRuling=Thin; \
  XColumnRuling=Thin; \
  XFill=5

inFixed=0; \
  CellLMarginFixed=0; \
  CellMargins="0.0 pt 0.0 pt 0.0 pt 0.0 pt"; \
  CellRMarginFixed=0; \
  CellTMarginFixed=0; \
  FIndent='0.5"'; \
  FIndentOffset='0.0"'; \
  FIndentRelative=0; \
  FontAngle=Regular; \
  FontCase="FAsTyped"; \
  FontChangeBar=0; \
  FontColor=Black; \
  FontDW="0.0%"; \
  FontDX="0.0%"; \
  FontDY="0.0%"; \
  FontFamily=Helsdf-2.001/perllib/sdf/home/look/fancy/004075500042570001753000000000000672243775200173405ustar00iancmtr00000400000236sdf-2.001/perllib/sdf/home/look/fancy/pages.sdm010064400042570001753000000026440631157627200211420ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Pages Module
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 08-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{pages}} is an [[SDF]] module containing configuration data
# common to styles in the {{fancy}} look.
#
# >>Description::
#
# >>Limitations::
#

# Inherit what we can from the simple look
!use "look/simple/pages"

# Adjust the header/footer size and positioning
!define PAGE_FIRST_FOOTER_HEIGHT  '0.50in'
!define PAGE_FIRST_FOOTER_GAP     '0.25in'
!define PAGE_RIGHT_HEADER_HEIGHT  '0.50in'
!define PAGE_RIGHT_HEADER_GAP     '0.25in'
!define PAGE_RIGHT_FOOTER_HEIGHT  '0.50in'
!define PAGE_RIGHT_FOOTER_GAP     '0.25in'

# Define the header/footer borders
!macro build_borders
!if $var{'OPT_BORDERS'} == 0
!define PAGE_RIGHT_HEADER_BORDER  ''
!define PAGE_RIGHT_FOOTER_BORDER  ''
!elsif $var{'OPT_BORDERS'} == 1
!define PAGE_RIGHT_HEADER_BORDER  "bottom=0.5"
!define PAGE_RIGHT_FOOTER_BORDER  "top=0.5"
!else
!define PAGE_RIGHT_HEADER_BORDER  "top=0.5,bottom=0.25"
!define PAGE_RIGHT_FOOTER_BORDER  "top=0.5"
!endif
!endmacro

# Adjust the sidehead size
!define OPT_SIDEHEAD_WIDTH "108pt"
!define OPT_SIDEHEAD_GAP   "36pt"
sdf-2.001/perllib/sdf/home/look/fancy/manual.sds010064400042570001753000000011750631614037600213210ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Manual Style
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 01-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{manual}} is an [[SDF]] style for manuals.
#
# >>Description::
#
# >>Limitations::
#

# Assume component cover pages
!default OPT_COMPONENT_COVER

# Inherit the rest from simple manuals
!use "look/simple/manual.sds"
sdf-2.001/perllib/sdf/home/look/fancy/fancy.sdm010064400042570001753000000010630630543154600211320ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Fancy Look
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 09-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{fancy}} is an [[SDF]] look for user documentation.
#
# >>Description::
#
# >>Limitations::
#

# Inherit the simple look
!inherit "look/simple"
sdf-2.001/perllib/sdf/home/look/fancy/mif.sdn010064400042570001753000000203510652670756400206220ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Fancy MIF Tuning
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 15-May-98 ianc    Commented out generated list headings
# 01-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# This template provides the mif objects required for the fancy look.
#
# >>Description::
#
# >>Limitations::
#

# Change the base font size
!default _BASE_SIZE 11.5

# Change the default list indent (1 cm)
!default OPT_LIST_INDENT 28.3

# Inherit what we can from the simple look
!use "look/simple/mif.sdn"

################ Override the heading paragraph formats ###################

!targetobject "Para"; "h2_Heading"; "b0_Body"; \
  AcrobatLevel=4; \
  BlockSize=3; \
  BotSeparator="H2 Below"; \
  FontFamily=Helvetica; \
  FontSize="18.0 pt"; \
  FontWeight=Bold; \
  Leading="2.0 pt"; \
  Placement="PageTop"; \
  PlacementStyle=Straddle; \
  SpAfter="8.0 pt"; \
  SpBefore="12.0 pt"; \
  WithNext=Yes

!targetobject "Para"; "h3_Heading"; "h2_Heading"; \
  AcrobatLevel=7; \
  BotSeparator="H3 Below"; \
  FontSize="16.0 pt"; \
  Placement=Anywhere; \
  SpAfter="10.0 pt"; \
  SpBefore="25.0 pt"

!targetobject "Para"; "h4_Heading"; "h3_Heading"; \
  AcrobatLevel=10; \
  BotSeparator="H4 Below"; \
  FontSize="12.0 pt"; \
  PlacementStyle=Normal; \
  SpAfter="5.0 pt"; \
  SpBefore="20.0 pt"

!targetobject "Para"; "h5_Heading"; "h4_Heading"; \
  AcrobatLevel=13; \
  BlockSize=2; \
  BotSeparator=""; \
  SpAfter="8.0 pt"; \
  SpBefore="12.0 pt"

# Appendix and plain headings look the same as normal headings for levels 2 ..
!targetobject "Para"; "a2_Appendix"; "h2_Heading"
!targetobject "Para"; "a3_Appendix"; "h3_Heading"
!targetobject "Para"; "a4_Appendix"; "h4_Heading"
!targetobject "Para"; "a5_Appendix"; "h5_Heading"
!targetobject "Para"; "p2_PlainHeading"; "h2_Heading"
!targetobject "Para"; "p3_PlainHeading"; "h3_Heading"
!targetobject "Para"; "p4_PlainHeading"; "h4_Heading"
!targetobject "Para"; "p5_PlainHeading"; "h5_Heading"

# NoTOC versions for headings excluding from the contents
!targetobject "Para"; "h1_HeadingNoTOC"; "h1_Heading"; AcrobatLevel=0
!targetobject "Para"; "h2_HeadingNoTOC"; "h2_Heading"; AcrobatLevel=0
!targetobject "Para"; "h3_HeadingNoTOC"; "h3_Heading"; AcrobatLevel=0
!targetobject "Para"; "h4_HeadingNoTOC"; "h4_Heading"; AcrobatLevel=0
!targetobject "Para"; "h5_HeadingNoTOC"; "h5_Heading"; AcrobatLevel=0
!targetobject "Para"; "a1_AppendixNoTOC"; "a1_Appendix"; AcrobatLevel=0
!targetobject "Para"; "a2_AppendixNoTOC"; "a2_Appendix"; AcrobatLevel=0
!targetobject "Para"; "a3_AppendixNoTOC"; "a3_Appendix"; AcrobatLevel=0
!targetobject "Para"; "a4_AppendixNoTOC"; "a4_Appendix"; AcrobatLevel=0
!targetobject "Para"; "a5_AppendixNoTOC"; "a5_Appendix"; AcrobatLevel=0
!targetobject "Para"; "p1_PlainHeadingNoTOC"; "p1_PlainHeading"; AcrobatLevel=0
!targetobject "Para"; "p2_PlainHeadingNoTOC"; "p2_PlainHeading"; AcrobatLevel=0
!targetobject "Para"; "p3_PlainHeadingNoTOC"; "p3_PlainHeading"; AcrobatLevel=0
!targetobject "Para"; "p4_PlainHeadingNoTOC"; "p4_PlainHeading"; AcrobatLevel=0
!targetobject "Para"; "h5_PlainHeadingNoTOC"; "p5_PlainHeading"; AcrobatLevel=0


############# Override the generated list paragraph formats ################

#!targetobject "Para"; "h1_HeadingTOC"; "b0_Body"; \
#  BlockSize=1; \
#  FIndent='0.5"'; \
#  FontPairKern=0; \
#  FontSize="11.5 pt"; \
#  HyphenMinPrefix=2; \
#  HyphenMinSuffix=2; \
#  Hyphenate=Yes; \
#  LIndent='0.625"'; \
#  MaxWordSpace=125; \
#  MinWordSpace=75; \
#  PlacementStyle=Straddle; \
#  RIndent='0.246"'; \
#  SpAfter="0.0 pt"; \
#  SpBefore="4.0 pt"; \
#  TabStop="$var{'_TABR'}/Right/. "
#
#!targetobject "Para"; "h2_HeadingTOC"; "h1_HeadingTOC"; \
#  BlockSize=2; \
#  FIndent='0.75"'; \
#  LIndent='0.875"'; \
#  SpBefore="0.0 pt"
#
#!targetobject "Para"; "h3_HeadingTOC"; "h2_HeadingTOC"; \
#  BlockSize=1; \
#  FIndent='1.0"'; \
#  LIndent='1.125"'
#
#!targetobject "Para"; "h4_HeadingTOC"; "h3_HeadingTOC"; \
#  BlockSize=2; \
#  FIndent='0.0"'; \
#  FontPairKern=Yes; \
#  LIndent='0.0"'; \
#  MaxWordSpace=110; \
#  MinWordSpace=90; \
#  RIndent='0.0"'; \
#  SpBefore="2.0 pt"; \
#  TabStop="1.0in,$var{'_TABR'}/Right/. "
#
#!targetobject "Para"; "h5_HeadingTOC"; "h4_HeadingTOC"; \
#  TabStop="1.25in,$var{'_TABR'}/Right/. "
#
#!targetobject "Para"; "a1_AppendixTOC"; "h1_HeadingTOC"
#!targetobject "Para"; "a2_AppendixTOC"; "h2_HeadingTOC"
#!targetobject "Para"; "a3_AppendixTOC"; "h3_HeadingTOC"
#!targetobject "Para"; "a4_AppendixTOC"; "h4_HeadingTOC"
#!targetobject "Para"; "a5_AppendixTOC"; "h5_HeadingTOC"
#
#!targetobject "Para"; "p1_PlainHeadingTOC"; "h1_HeadingTOC"
#!targetobject "Para"; "p2_PlainHeadingTOC"; "h2_HeadingTOC"
#!targetobject "Para"; "p3_PlainHeadingTOC"; "h3_HeadingTOC"
#!targetobject "Para"; "p4_PlainHeadingTOC"; "h4_HeadingTOC"
#!targetobject "Para"; "p5_PlainHeadingTOC"; "h5_HeadingTOC"

################ Other paragraph formats overrides ###################

!targetobject "Para"; "gh_GlossaryHeading"; "b0_Body"; \
  FontFamily=Helvetica; \
  FontWeight=Bold; \
  PlacementStyle="SideheadTop"; \
  SpAfter="8.0 pt"; \
  SpBefore="16.0 pt"; \
  TabStop='0.5",1.0",1.5",2.0",2.5",3.0"'; \
  WithNext=Yes

!targetobject "Para"; "gl_Glossary"; "b0_Body"; \
  FontFamily=Helvetica; \
  FontSize="10.0 pt"; \
  Hyphenate=Yes; \
  LIndent='1.5"'; \
  SpAfter="2.0 pt"; \
  SpBefore="0.0 pt"; \
  TabStop='1.5"'


################ Look specific paragraph formats ###################

!targetobject "Para"; "LFI left footer inside"; "b0_Body"; \
  Alignment=Right; \
  BlockSize=1; \
  FontFamily=Helvetica; \
  FontPairKern=0; \
  FontSize="7.0 pt"; \
  HyphenMinPrefix=2; \
  HyphenMinSuffix=2; \
  Hyphenate=Yes; \
  MaxWordSpace=125; \
  MinWordSpace=75; \
  SpAfter="0.0 pt"; \
  SpBefore="0.0 pt"; \
  TabStop='2.85453"/Center,5.70905"/Right'

!targetobject "Para"; "LFO left footer outside"; "LFI left footer inside"; \
  Alignment=Left; \
  FontSize="10.0 pt"; \
  FontWeight=Bold

!targetobject "Para"; "LH1 left header 1"; "LFO left footer outside"; \
  FontPairKern=Yes; \
  FontSize="12.0 pt"; \
  SpAfter="6.0 pt"

!targetobject "Para"; "LH2 left header 2"; "LH1 left header 1"; \
  FontSize="11.5 pt"; \
  FontWeight=Regular; \
  SpAfter="0.0 pt"

!targetobject "Para"; "RFI right footer inside"; "LH2 left header 2"; \
  FontPairKern=0; \
  FontSize="7.0 pt"

!targetobject "Para"; "RFO right footer outside"; "RFI right footer inside"; \
  Alignment=Right; \
  FontSize="10.0 pt"; \
  FontWeight=Bold

!targetobject "Para"; "RH1 right header 1"; "RFO right footer outside"; \
  FontPairKern=Yes; \
  FontSize="12.0 pt"; \
  SpAfter="6.0 pt"

!targetobject "Para"; "RH2 right header 2"; "RH1 right header 1"; \
  FontSize="11.5 pt"; \
  FontWeight=Regular; \
  SpAfter="0.0 pt"

!targetobject "Para"; "ed_EndDocument"; "b0_Body"; \
  BotSeparator="End Section"; \
  FIndent='1.0"'; \
  FontFamily=Helvetica; \
  FontSize="9.0 pt"; \
  LIndent='1.0"'; \
  Leading="4.0 pt"; \
  SpBefore="0.0 pt"; \
  WithPrev=Yes


################ Reference page frames ###################

!targetobject "Frame"; "End Section";; \
  Width=481; \
  Height=23; \
  Objects=\
'  \
   \
   \
   \
   \
  > # end of PolyLine\
  \
   \
   \
   \
   \
   \
   \
   \
   \
  > # end of Polygon'

!targetobject "Frame"; "H2 Below";; \
  Height=14;\
  Pen=3; \
  PenWidth=3.0; \
  LineLength=DOC_FULL_WIDTH

!targetobject "Frame"; "H3 Below";; \
  Height=8;\
  Pen=3; \
  PenWidth=0.25; \
  LineLength=DOC_FULL_WIDTH

!targetobject "Frame"; "H4 Below";; \
  Height=8;\
  PenWidth=0.1; \
  LineLength=DOC_FULL_WIDTH

!targetobject "Frame"; "Note Above";; \
  Height=17;\
  Pen=4; \
  PenWidth=0.5; \
  LineY=6; \
  LineLength=DOC_FULL_WIDTH

!targetobject "Frame"; "Note Below";; \
  Height=17;\
  Pen=4; \
  PenWidth=0.5; \
  LineY=6; \
  LineLength=DOC_FULL_WIDTH
sdf-2.001/perllib/sdf/home/look/infomap/004075500042570001753000000000000672243773700176745ustar00iancmtr00000400000236sdf-2.001/perllib/sdf/home/look/infomap/pages.sdm010064400042570001753000000020170631157664400214700ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Pages Module
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 08-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{pages}} is an [[SDF]] module containing configuration data
# common to styles in the {{infomap}} look.
#
# >>Description::
#
# >>Limitations::
#

# Inherit what we can from the simple look
!use "look/simple/pages"

# Adjust the header/footer size and positioning
!define PAGE_FIRST_FOOTER_HEIGHT  '0.50in'
!define PAGE_FIRST_FOOTER_GAP     '0.25in'
!define PAGE_RIGHT_HEADER_HEIGHT  '0.50in'
!define PAGE_RIGHT_HEADER_GAP     '0.25in'
!define PAGE_RIGHT_FOOTER_HEIGHT  '0.50in'
!define PAGE_RIGHT_FOOTER_GAP     '0.25in'

# Adjust the sidehead size
!define OPT_SIDEHEAD_WIDTH "90pt"
!define OPT_SIDEHEAD_GAP   "10pt"
sdf-2.001/perllib/sdf/home/look/infomap/mif.sdn010064400042570001753000000123560636603141200211410ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Infomap MIF Tuning
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 01-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# This module provides the mif objects required for the infomap look.
#
# >>Description::
#
# >>Limitations::
#

# Inherit what we can from the simple look
!use "look/simple/mif.sdn"

# Tune the change bar positioning
!define MIF_CH_BAR_POSITION "NearestEdge"

################ General formatting rules ###################

# Place lines above each information block (level 3 heading).
# Note that we have to tranfer the top attribute so that the
# line stays on the same page as the heading.
!on paragraph '[HAP]3'   ;; \
    if ($attr{'top'}) { \
        &PrependText("Line[keep_next;top=$attr{'top'}]"); \
        delete $attr{'top'}; \
    } \
    else { \
        &PrependText("Line[keep_next]"); \
    }

# Place lines at the end of each information map (level 2 section)
!if MIF_BOOK_MODE
    !on paragraph '[HAP]2';; if ($level >= 3 && !$attr{'component'}) \
        {&PrependText("Line[keep_prev]")}
    !macro DOC_COMPONENT_END
        !if $var{'DOC_COMPONENT'} eq 'pretoc'
            Line[keep_prev; wide]
        !else
            Line[keep_prev]
        !endif
    !endmacro
!else
    !on paragraph '[HAP][12]';; if ($level >= 3) {&PrependText("Line[keep_prev]")}
    !block end
    !if $level >= 3
    Line[keep_prev]
    !endif
    !endblock
!endif

# Place level 2 headings at the start of a new page unless the
# previous heading was level 1. Also prepend "continued on next page"
# if this heading simply contines a previous one.
!on paragraph '[HAP]2';; \
    if (!defined($attr{'top'})) {\
        $attr{'top'} = 1 unless $level == 1; \
    } \
    if ($attr{'continued'}) { \
        &PrependText("CONTINUED:Continued on next page"); \
    }



################ Override the heading paragraph formats ###################

!targetobject "Para"; "h1_Heading"; "h1_Heading"; \
  Alignment=Center; \
  LIndent=0; \
  NumFormat='H:Chapter . '; \
  SpAfter="12.0 pt"

!targetobject "Para"; "h2_Heading"; "h2_Heading"; \
  AutoNum=0; \
  FontSize="16.0 pt"; \
  LIndent=0; \
  NumFormat=""; \
  SpBefore="12.0 pt"

!targetobject "Para"; "h3_Heading"; "h3_Heading"; \
  AutoNum=0; \
  FontFamily=Times; \
  FontSize="11.0 pt"; \
  LIndent=0; \
  NumFormat=""; \
  PlacementStyle="SideheadTop"; \
  SpAfter="10.0 pt"; \
  SpBefore="10.0 pt"

!targetobject "Para"; "h4_Heading"; "h3_Heading"; \
  PlacementStyle=Normal; \
  SpAfter="6.0 pt"

!targetobject "Para"; "h5_Heading"; "b0_Body"; \
  FontUnderlining="FSingle"; \
  PlacementStyle="RunIn"; \
  RunInDefaultPunct=": "

!targetobject "Para"; "a1_Appendix"; "a1_Appendix"; \
  Alignment=Center; \
  LIndent=0; \
  NumFormat='A:Appendix . '; \
  SpAfter="12.0 pt"

!targetobject "Para"; "p1_PlainHeading"; "p1_PlainHeading"; \
  Alignment=Center; \
  SpAfter="12.0 pt"

# Other than the first level, appendix and plain headings are the same as
# the normal headings
!targetobject "Para"; "a2_Appendix";     "h2_Heading"
!targetobject "Para"; "a3_Appendix";     "h3_Heading"
!targetobject "Para"; "a4_Appendix";     "h4_Heading"
!targetobject "Para"; "p2_PlainHeading"; "h2_Heading"
!targetobject "Para"; "p3_PlainHeading"; "h3_Heading"
!targetobject "Para"; "p4_PlainHeading"; "h4_Heading"

# NoTOC versions for headings excluding from the contents
!targetobject "Para"; "h1_HeadingNoTOC";      "h1_Heading"; AcrobatLevel=0
!targetobject "Para"; "h2_HeadingNoTOC";      "h2_Heading"; AcrobatLevel=0
!targetobject "Para"; "h3_HeadingNoTOC";      "h3_Heading"; AcrobatLevel=0
!targetobject "Para"; "h4_HeadingNoTOC";      "h4_Heading"; AcrobatLevel=0
!targetobject "Para"; "a1_AppendixNoTOC";     "a1_Appendix"; AcrobatLevel=0
!targetobject "Para"; "a2_AppendixNoTOC";     "a2_Appendix"; AcrobatLevel=0
!targetobject "Para"; "a3_AppendixNoTOC";     "a3_Appendix"; AcrobatLevel=0
!targetobject "Para"; "a4_AppendixNoTOC";     "a4_Appendix"; AcrobatLevel=0
!targetobject "Para"; "p1_PlainHeadingNoTOC"; "p1_PlainHeading"; AcrobatLevel=0
!targetobject "Para"; "p2_PlainHeadingNoTOC"; "p2_PlainHeading"; AcrobatLevel=0
!targetobject "Para"; "p3_PlainHeadingNoTOC"; "p3_PlainHeading"; AcrobatLevel=0
!targetobject "Para"; "p4_PlainHeadingNoTOC"; "p4_PlainHeading"; AcrobatLevel=0


################ Override phrase formats ###################

# Make attribute labels the same as level 3 headings
!targetobject "Phrase"; "AttributeLabel"; "AttributeLabel"; \
  Family=Times; \
  Size="11.0 pt"


################ Override reference page frames ###################

!targetobject "Frame"; "Note Above";; \
  Height=17;\
  Pen=4; \
  PenWidth=0.5; \
  LineY=6; \
  LineLength=DOC_FULL_WIDTH

!targetobject "Frame"; "Note Below";; \
  Height=17;\
  Pen=4; \
  PenWidth=0.5; \
  LineY=6; \
  LineLength=DOC_FULL_WIDTH


################ Template specific stuff ###################

!block parastyles
Name        To
CONTINUED   Continued
!endblock

!targetobject "Para"; "Continued"; "b0_Body"; \
  Alignment=Right; \
  FontAngle=Italic; \
  FontSize=10; \
  WithPrev=1
sdf-2.001/perllib/sdf/home/look/infomap/infomap.sdm010064400042570001753000000012200631336637600220160ustar00iancmtr00000400000236# $Id$
#
# >>Title::	Infomap Look
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 09-Oct-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{infomap}} is an [[SDF]] look for user documentation.
#
# >>Description::
#
# >>Limitations::
#

# To remove the header/footer borders, uncomment the line below
#!default OPT_BORDERS 0

# Inherit the simple look
!inherit "look/simple"
sdf-2.001/perllib/sdf/home/sdfbatch.ini010064400042570001753000000007430614356170200175420ustar00iancmtr00000400000236# $Id$
#
# >>Title::     sdfbatch Configuration
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

[Alias fm2ps: convert Frame files to PostScript]
print_doc=file
sdf-2.001/perllib/sdf/home/sdf/004075500042570001753000000000000672243775200160505ustar00iancmtr00000400000236sdf-2.001/perllib/sdf/home/sdf/document.reg010064400042570001753000000031430661304543500203530ustar00iancmtr00000400000236# $Id$
#
# >>Title::     SDF Document Register
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{FILE:document.reg}} is the reference table for [[SDF]] documents.
# This table is used to lookup document properties.
# It can also be used to generate a catalog of project documents.
#
# >>Description::
# The fields used are given below.
#
# !block table
# Field     Description
# Reference the document code
# Document  the document title
# Jump      the filename of the document
# Version   the document version number
# Status    the document status (e.g. Draft, Review or Final)
# !endblock
#
Reference    Version Status  Jump                 Document
MTR-SDF-0001 001     Final   paper/sdfintro.html  The SDF Document Development System
MTR-SDF-0002 001     Final   user/ug_sdf.html     SDF User Guide
MTR-SDF-0003 002     Draft   quickref/qr_sdf.html SDF Quick Reference
MTR-SDF-0004 001     Final   ref/re_sdf.html      SDF Reference
MTR-SDF-0005 001     Final   guru/gg_sdf.html     SDF Guru Guide
MTR-SDF-0008 001     Final   release/rn_sdf.html  SDF Release Notes
MTR-SDF-0011 001     Final   genhtml/index.html   Generating HTML Using SDF
MTR-SDF-0012 001     Final   podusers/index.html  SDF for POD Users
SDF-FAQ      001     Final   faq/faq.html         SDF Frequently Asked Questions
tworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{FILE:document.reg}} is the reference table for [[SDF]] documents.
# This tablsdf-2.001/perllib/sdf/home/sdf/sdf.sdm010064400042570001753000000164700672235456400173350ustar00iancmtr00000400000236# $Id$
#
# >>Title::     SDF Module
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{MOD:sdf}} is the [[SDF]] library module for building
# the [[SDF]] documentation suite.
#
# >>Description::
# The SDF_ROOT variable is prepended to relative paths, so that
# documents in different directories can access files in a relative
# manner.
#
# >>Limitations::
#

# The default SDF_ROOT is the current directory
#!default SDF_ROOT           './'
!default SDF_ROOT           ''

# Set up the default location for images
#!define IMAGES_BASE "/images/"

# Logos
!define DOC_LOGO            "sdflogo"
!define DOC_LOGO_BASE       SDF_ROOT
!define DOC_TITLE_LOGO      "sdfbig"

# Title page details
!define DOC_DISTRIBUTION    "UNLIMITED CIRCULATION"
!define DOC_PRODUCT         "Simple Document Format"
!define DOC_PROJECT         "SDF $var{'SDF_VERSION'}"
!define DOC_OWNER           "Ian Clatworthy"

# HTML configuration variables
!define HTML_BG_COLOR       COLOR_WHITE
#!define HTML_LINK_COLOR     COLOR_BLUE
#!define HTML_VLINK_COLOR    COLOR_RED
!define HTML_URL_HOME       $var{'SDF_ROOT'} . "index.html"
!define HTML_URL_CATALOG    $var{'SDF_ROOT'} . "catalog.html"
#!define HTML_URL_SEARCH     $var{'SDF_ROOT'} . "search.html"

# Define the documents within this documentation suite.
!include "document.reg"; references; data; root=SDF_ROOT

# Add technical papers as references
!block references; data; root=SDF_ROOT
Reference,Jump,Document
Clatworthy 96,qauug96/qauug96.html,SDF - A Documentation System for Software Developers
!endblock

# Add the bugs database, etc. as references
!block references; data; root="http://www.mincom.com/mtr/sdf/"
Reference       Jump                    Document
SDF-HOME        index.html              SDF Web Site
SDF-DOCS        catalog.html            SDF Document Catalog
#SDF-DOWNLOAD    download.html           SDF Download Page
SDF-BUGS        bugs/index.html         SDF Bug Database
SDF-SAMPLES     samples/index.html      SDF Sample Showcase
SDF-RESOURCES   resources/index.html    SDF Resource Center
SDF-TEMPLATES   templates/index.html    SDF Template Catalog
SDF-NEWS        news/index.html         SDF Latest News
!endblock

# Make some things easier to reference
!define SDF_DOWNLOAD "http://www.mincom.com/mtr/sdf/download.html"

# Include commonly referenced objects
!use "objects"

# Commonly used phrase styles
!block phrasestyles
Name            To
CLASS           =1
DSTYLE          =1
VAR             =1
FMT             =1
FILT            =1
MAC             =1
MOD             =1
SUBR            =1
OATTR           =1
OSTYLE          =N
PATTR           =1
PSTYLE          =N
TSTYLE          =N
TPARAM          =1
RPARAM          =1
CPARAM          =1
!endblock

# Commonly referenced organisations
!block organisations; data
Name            Long                                    Jump
!endblock

# Commonly referenced products
!block products; data
Name            Jump
Acrobat         http://www.adobe.com/prodindex/acrobat/
Emacs
HTMLDOC         http://www.easysw.com/~mike/htmldoc/
MIF             http://www.frame.com
PDF             http://www.adobe.com
PDF Distiller   http://www.adobe.com
RTF             http://www.microsoft.com
pod2ps          http://www.oasis.leo.org/perl/scripts/textproc/pod2ps.dsc.html
SGML-Tools      http://www.xs4all.nl/~cg/sgmltools/
Ultimate        http://www.ufs.com.au/
Visio           http://www.visio.com
!endblock

# Make the most commonly referenced objects variables
!define MIF             "{{PRD:MIF}}"
!define PDF             "{{PRD:PDF}}"
!define RTF             "{{PRD:RTF}}"
!define SDF             "{{PRD:SDF}}"
!define SDFAPI          "{{SECT:SDFAPI}}"
!define SDF_DRIVER      "{{SDF driver}}"
!define Visio           "{{PRD:Visio}}"

# Document summary variables
!define SDF_DOC_WP  "{{DOC:The SDF Document Development System}} - an overview of the architecture and features"
!define SDF_DOC_QR  "{{DOC:SDF Quick Reference}} - a concise summary of the most frequently used {{PRD:SDF}} features"
!define SDF_DOC_UG  "{{DOC:SDF User Guide}} - a tutorial style introduction to the key features"
!define SDF_DOC_GG  "{{DOC:SDF Guru Guide}} - information on extending {{PRD:SDF}}"
!define SDF_DOC_REF "{{DOC:SDF Reference}} - detailed reference material on all {{PRD:SDF}} features"
!define SDF_DOC_MIG "{{DOC:SDF 2.000 Migration Guide}} - information on the features added in version 2.000"
!define SDF_DOC_REL "{{DOC:SDF Release Notes}} - information on the latest enhancements and bug fixes"

# Copyright stuff
!macro DOC_COPYRIGHT
    Copyright [[c]] [[_DOC_YEAR]], [[DOC_OWNER]]

    All rights reserved.

    You are free to copy and distribute this manual as often as you like.
    If parts of this manual are included in commercial products such as
    books and magazine articles, credit {{must}} be given to the author.
!endmacro

# Trademark stuff
!macro  DOC_TRADEMARKS
[[FrameMaker]], [[FrameViewer]], {{PRD:Acrobat}},
[[PDF]] and [[PostScript]] are registered trademarks of {{ORG[expand]Adobe}}.

[[Windows]] is a registered trademark of
{{ORG[expand] Microsoft}}.

[[Unix]] is a registered trademark of
{{ORG[expand] X/Open}}.

Infomation Mapping is a registered trademark of
Information Mapping, Incorporated.

Other trademarks are the property of their respective owners.
!endmacro

# Admendments advice
!macro SDF_AMENDMENTS
Suggested enhancements and corrections to [[SDF]] and its documentation
can be forwarded to [[SDF_BUGS]].

Note: This manual documents version [[SDF_VERSION]] of [[SDF]].
!endmacro

################# Hypertext Generation Stuff #####################

!if $var{'OPT_TARGET'} eq 'html'
    # the Reference Guide is broken into topics for HTML
    !on phrase 'CMD' ;; \
        if ($text =~ /^sd[fn]/) {\
            $attr{'jump'} = sprintf("%sref/%s.html", $var{'SDF_ROOT'}, \
              $text =~ /^sdfcvt$|^sdf2/ ? 'sdf' : $text); \
        }
    !on phrase 'FMT' ;; \
        $attr{'jump'} = $text; \
        $attr{'jump'} =~ tr/A-Z/a-z/; \
        $attr{'jump'} = $var{'SDF_ROOT'} . "ref/fmt_" . $attr{'jump'} . ".html"
    !on phrase 'CLASS';; $attr{'jump'} = $var{'SDF_ROOT'} . "ref/c".substr($text,0,7).".html"
    !on phrase 'FILT' ;; $attr{'jump'} = $var{'SDF_ROOT'} . "ref/f".substr($text,0,7).".html"
    !on phrase 'MAC'  ;; $attr{'jump'} = $var{'SDF_ROOT'} . "ref/m".substr($text,0,7).".html"
!else
    # normal mode
    !on phrase 'CMD' ;; \
        if ($text =~ /^sd[ft]/) { \
            $attr{'jump'} = "../ref/re_sdf.html#" . \
              ($text =~ /^sdfcvt$|^sdf2/ ? 'sdf' : $text); \
        }
    !on phrase 'CLASS';; $attr{'jump'} = $var{'SDF_ROOT'} . "ref/re_sdf.html#$text Class"
    !on phrase 'FMT'  ;; $attr{'jump'} = $var{'SDF_ROOT'} . "ref/re_sdf.html#$text Format"
    !on phrase 'FILT' ;; $attr{'jump'} = $var{'SDF_ROOT'} . "ref/re_sdf.html#$text Filter"
    !on phrase 'MAC'  ;; $attr{'jump'} = $var{'SDF_ROOT'} . "ref/re_sdf.html#$text Macro"
!endif

################# Index Generation Stuff #####################

# A poor man's index :-)
!on phrase ''       ;; if (length($text) < 50) {$attr{'index'} = $text}
!on phrase '[HAP]\d';; $attr{'index'} = $text
sdf-2.001/perllib/sdf/home/sdf.ini010064400042570001753000000261040672213160200165320ustar00iancmtr00000400000236# $Id$
#
# >>Title::     SDF Configuration
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

[Product]
version=2.001

#
# Update the variables below to reflect your configuration.
# The variables are:
#
# * SDF_DOSHOME - the dos directory in which SDF is installed
# * DEFAULT_LOOK - the default look library to use
# * DEFAULT_LOCALE - the default locale/xx.sdl file to use
# * HTML_EXT - the extension used for jumps to generated HTML files.
#
# Note: SDF_DOSHOME is only needed when generating HPJ files
# on Unix for later compilation on DOS.
# 
[Variables]
SDF_DOSHOME=C:\SDF
DEFAULT_LOOK=simple
DEFAULT_LOCALE=en_au
#HTML_EXT=htm

# FrameMaker configuration things
[Frame]
fm_batch=fmbatch -i
fm_ext=fm5

#
# Update the mappings below to reflect your configuration.
# See the alias declarations below for meaningful values.
# Generally speaking, a value of xxx_yyy means format xxx via yyy.
# Likewise, a value of xxx_ means format xxx directly.
#
[FormatMappings]
_dir    =html_dir
book    =ps_fmbook
doc     =doc_fm
dvi     =dvi_sgml
expand  =sdf_expand
fvo     =fvo_fm
hlp     =hlp_mif
html    =html_
htx     =htx_
info    =info_sgml
latex   =latex_sgml
lyx     =lyx_sgml
man     =man_pod
mf6     =mf6_
mif     =mif_
pdf     =pdf_mif
pod     =pod_
ps      =ps_fm
raw     =sdf_raw
rtf     =rtf_fm
sgml    =sgml_
topics  =html_topics
txt     =txt_

#
# To automatically convert figure formats, add an entry to the table below.
# The fields are:
#
# * {{Context}} - the driver for which this conversion applies
# * {{To}} - the destination figure format
# * {{From}} - the original figure format
# * {{Action}} - the command to use to do the conversion.
#
# Useful variables in the action are:
#
# * $source - the name of the source file
# * $dest - the name of the destination file
# * $base - the base component (no directory or extension) of the filename.
#
# Rules do not chain, so defining rules for A->B and B->C do not
# imply that A will be converted to C.
#
[Conversions]
Context To      From    Action
html    gif     eps     ps2gif -crop $source
html    gif     ps      ps2gif -crop $source
html    gif     prn     prn2ps -ops $source; ps2gif -crop $base.ps; rm $base.ps
ps      eps     ps      ps2epsi $source $dest
ps      eps     prn     prn2ps -ops $source; ps2epsi $base.ps $dest; rm $base.ps

#
# To add a new pre-filter, add an entry to the table below.
# The fields are:
#
# * {{Name}} - the filter name
# * {{Aliases}} - comma-separated list of alternate names, if any.
#
# As the default prefilter is taken from the file extension,
# file extensions are often listed as aliases.
#
[PreFilters]
Name            Aliases
table           tbl
template        sdt
module          sdm
pod             pm,PL

#
# To add a new page size, add an entry to the table below.
# The fields are:
#
# * {{Name}} - the logical name
# * {{Width}} - width of page
# * {{Height}} - height of page
# * {{Comment}} - arbitary explanatory text.
#
# A rotated version is automatically added for each page size.
# Rotated sizes are named with an appended R, so naming sizes
# with a trailing R below is not recommended.
# The default units are points (pt).
#
[PageSizes]
Name    Width   Height  Comment
global  21.0cm  11.0in  will fit on either A4 or letter
A3      29.7cm  42.0cm 
A4      21.0cm  29.7cm
A5      14.8cm  21.0cm
B4      25.7cm  36.4cm
B5      17.6cm  25.0cm
letter  8.5in   11.0in
legal   8.5in   14.0in
tabloid 11.0in  17.0in

#
# To add a new format driver, add an entry to the table below.
# The fields are:
#
# * {{Name}} - the driver name
# * {{Library}} - the library containing the subroutine(s)
# * {{Subroutine}} - the subroutine name
#
[Drivers]
Name    Library         Subroutine
expand  sdf/toexpand.pl ExpandFormat
raw     sdf/toraw.pl    RawFormat
mif     sdf/tomif.pl    MifFormat
html    sdf/tohtml.pl   HtmlFormat
pod     sdf/topod.pl    PodFormat
txt     sdf/totxt.pl    TxtFormat
sgml    sdf/tosgml.pl   SgmlFormat
latex   sdf/tolatex.pl  LatexFormat

#
# Post processing actions are configured below.
# Each action maps a symbolic name to a set of commands to execute.
# Commands should be called via the Perl subroutines below:
#
# * {{SdfBatch}} - execute sdfbatch with the options specified
# * {{SdfHtmldoc}} - convert arg1 to arg2 via the HTMLDOC program
# * {{SdfDelete}} - delete the file specified if it exists
# * {{SdfExecute}} - execute the system command specified.
#
# Within the commands, the following Perl symbols can be used:
#
# * {{$long}} - the directory and base component of the filename
# * {{$short}} - the base component of the filename
# * {{$out_ext}} - the output extension used (i.e. the -o option)
# * {{%var}} - the associative array of variables.
#
# AVOID using $short as it assumes the current directory is the
# output directory. Use $long instead.
#
# Note: If HTML is generated via fm2html, then an existing
# mif file confuses it. Therefore, we need to delete the mif
# file (if it exists) as part of the html action.
#
[PostProcessing]
update = &SdfBatch("-u"); &SdfBookClean("doc.backup")
ps     = &SdfDelete("$long.$out_ext.ps"); &SdfBatch("-pfile -PA4")
pdf    = &SdfSystem("distill -quiet $long.ps")
clean  = &SdfDelete("$long.$out_ext"); &SdfBookClean("doc")
doc    = &SdfBatch("-sdoc -Sd")
fvo    = &SdfBatch("-sfvo -Sl")
txt    = &SdfBatch("-stxt -Sa")
html   = &SdfDelete("$long.mif"); &SdfBatch("-shtml"); &SdfDelete("$long.mif"); &SdfDelete("$long.html.backup")
fmrtf  = &SdfBatch("-smif -Sm"); &SdfSystem("miftortf < $long.mif > $long.rtf"); &SdfDelete("$long.mif")
fmwp   = &SdfBatch("-smif -Sm"); &SdfSystem("miftowp  < $long.mif > $long.wp")
#rtf    = &SdfBatch("-smif -Sm"); &SdfSystem("mif2rtf -o $long.rtf $long.mif")
#hlp    = &SdfBatch("-smif -Sm"); &SdfSystem("mif2rtf -m help -o $long.rtf $long.mif")
rtf    = &SdfSystem("mif2rtf -o $long.rtf $long.$out_ext")
hlp    = &SdfSystem("mif2rtf -m help -o $long.rtf $long.$out_ext")
rename = rename("$long.$out_ext", "${long}_$out_ext.html")
pod2man = &SdfSystem("pod2man --lax --release='$project ' --center='$product ' --section=$section $long.$out_ext")
pod2latex = &SdfSystem("pod2latex $long.$out_ext")
pod2text = &SdfSystem("pod2text $long.$out_ext")
pod2ps = &SdfSystem("pod2ps -o $long.ps -t '$title' $long.$out_ext")
sgml2latex = &SdfSystem("sgml2latex $long.$out_ext")
sgml2ps = &SdfSystem("sgml2latex -o ps $long.$out_ext")
sgml2dvi = &SdfSystem("sgml2latex -o dvi $long.$out_ext")
sgml2info = &SdfSystem("sgml2info $long.$out_ext")
sgml2lyx = &SdfSystem("sgml2lyx $long.$out_ext")
sgml2rtf = &SdfSystem("sgml2rtf $long.$out_ext")
html2ps = &SdfHtmldoc("$long.$out_ext", "$long.ps")
html2pdf = &SdfDelete("$long.pdf"); &SdfHtmldoc("$long.$out_ext", "$long.pdf")

#
# Aliases are configured below.
# Aliases are a convenient way of specifying several options at once.
# To specify an alias, use the + character. For example:
#
# =     sdf +sdf2mif myfile.sdf
#
# Aliases should be named using the convention sdf2xxx_yyy where
# xxx is the final format and yyy is the intermediate format, if any.
# If there is no intermediate format, use the convention xxx_.
# Aliases should be declared in alphabetical order to make it
# easier to  manage them.
#

[Alias sdf2doc_fm:generate Frame binary format via FrameMaker]
driver=mif
out_ext=out
post_process=doc,clean

[Alias sdf2dvi_sgml:generate DVI format via SGML]
driver=sgml
out_ext=out
post_process=sgml2dvi,clean

[Alias sdf2fvo_fm:generate FrameViewer format via FrameMaker]
driver=mif
out_ext=out
post_process=fvo,clean

[Alias sdf2hlp_mif:generate Windows Help input files via MIF]
driver=mif
out_ext=out
post_process=hlp,clean

[Alias sdf2html_:generate a HTML document]
driver=html
out_ext=html

[Alias sdf2html_dir:generate an SDF directory in HTML]
driver=html
out_ext=dir
report=sdf_dir
post_process=rename

[Alias sdf2html_fm:generate a HTML document via FrameMaker]
driver=mif
out_ext=out
post_process=html,clean

[Alias sdf2html_topics:generate HTML topics]
driver=html
out_ext=html
split_level=1
variable=HTML_TOPICS_MODE

[Alias sdf2htx_:generate MIMS HTX format]
driver=txt
post_filter=htx
out_ext=htx
config=mincom/mims
variable=TXT_HDG_UL_OFF,MIMS_HTX,MIMS_ROOT=../

[Alias sdf2info_sgml:generate GNU info format via SGML]
driver=sgml
out_ext=out
post_process=sgml2info,clean

[Alias sdf2latex_pod:generate LaTeX format via POD]
driver=pod
out_ext=out
post_process=pod2latex,clean

[Alias sdf2latex_sgml:generate LaTeX format via SGML]
driver=sgml
out_ext=out
#post_process=sgml2latex,clean
post_process=sgml2latex

[Alias sdf2lyx_sgml:generate a LyX file via SGML]
driver=sgml
out_ext=out
post_process=sgml2lyx,clean

[Alias sdf2man_pod:generate Man page format via POD]
driver=pod
out_ext=out
post_process=pod2man,clean
verbose=-1

[Alias sdf2mf6_:generate MIMS F6 help format]
driver=txt
post_filter=mf6
out_ext=mf6
variable=TXT_HDG_UL_OFF,MIMS_HELP

[Alias sdf2mif_:generate Frame MIF format]
driver=mif
out_ext=mif

[Alias sdf2pdf_mif:generate PostScript and PDF via FrameMaker]
driver=mif
out_ext=out
post_process=ps,clean,pdf

[Alias sdf2pdf_html:generate PDF via HTML]
driver=html
out_ext=out
post_process=html2pdf,clean
variable=HTMLDOC,DOC_PAGED

[Alias sdf2pod_:generate POD format]
driver=pod
out_ext=pod

[Alias sdf2ps_fm:generate PostScript via FrameMaker]
driver=mif
out_ext=out
post_process=ps,clean

[Alias sdf2ps_fmbook:generate PostScript via a FrameMaker book]
driver=mif
out_ext=out
post_process=update,ps,clean
variable=MIF_BOOK_MODE

[Alias sdf2ps_pod:generate PostScript via POD]
driver=pod
out_ext=out
post_process=pod2ps,clean

[Alias sdf2ps_sgml:generate PostScript via SGML]
driver=sgml
out_ext=out
post_process=sgml2ps,clean

[Alias sdf2ps_html:generate PostScript via HTML]
driver=html
out_ext=out
post_process=html2ps,clean
variable=HTMLDOC,DOC_PAGED

[Alias sdf2rtf_fm:generate RTF format via FrameMaker]
driver=mif
out_ext=out
target=rtf
post_process=fmrtf,clean

[Alias sdf2rtf_mif:generate RTF format via MIF]
driver=mif
out_ext=out
post_process=rtf,clean

[Alias sdf2rtf_sgml:generate RTF format via SGML format]
driver=sgml
out_ext=out
post_process=sgml2rtf,clean

[Alias sdf2sdf_expand:generate expanded SDF]
driver=expand

[Alias sdf2sdf_raw:generate raw SDF]
driver=raw
out_ext=raw

[Alias sdf2sgml_:generate SGML format]
driver=sgml
out_ext=sgml

[Alias sdf2txt_:generate plain text format]
driver=txt
out_ext=txt

[Alias sdf2txt_fm:generate plain text format via FrameMaker]
driver=mif
out_ext=out
post_process=txt,clean
flag=sidehead:2

[Alias sdf2txt_pod:generate plain text format via POD]
driver=pod
out_ext=out
post_process=pod2text,clean
verbose=-1

[Alias sdf2latex_:generate LaTeX]
driver=latex
out_ext=tex


# Company-specific aliases go here ...

[Alias mt:generate a MIMS topic]
config=mincom/mims
variable=MIMS_ROOT=../
look=infomap
style=manual
head_level=2

[Alias mc:generate a MIMS chapter]
config=mincom/mims
variable=MIMS_ROOT=../
look=infomap
style=manual

[Alias ms:generate a MIMS spec]
config=mincom/mims
variable=MIMS_ROOT=../

# See the alias declarations below for meaningful values.
# Generally speaking, a value of xxx_yyy means format xxx via yyy.
# Likewise, a value of xxx_ means format xxx directly.
#
[FormatMappings]
_dir    =html_dir
book    =ps_fmbook
doc     =doc_fm
dvi     =dvi_sgml
expand  =sdf_expand
fvo     =fvo_fm
hlp     =hlp_mif
html    =html_
htx     =htx_
info    =info_sgml
latex   =latex_sgml
lyx     =lyx_sgml
man     =man_pod
mf6     =mf6_
mifsdf-2.001/perllib/sdf/app.sdf010064400042570001753000000145200635362374000156130ustar00iancmtr00000400000236H3: Overview

This library provides routines for:

* option processing
* argument processing
* message handling
* exiting a script

In principle, scripts using this library have a consistent
user interface and internal structure, making them easier to
use and maintain. A typical script looks like:

!block verbatim
     require "sdf/app.pl";

     # define configuration
     %app_config = (
             'inifile',      'abc.ini',
     );

     # define options
     push(@app_option, (
             'str|STR|my string parameter',
     ));

     # handle options
     &AppInit('file ...', 'do things to files') || &AppExit();

     # my post init stuff. e.g.
     # * act on options
     # * pop leading/trailing argument

     &AppProcess('argProcess');

     # my pre exit stuff. e.g.
     # * print summary information

     &AppExit();
!endblock

To summarise the framework:
* {{S:%app_config}} is an optional set of configuration parameters
* {{S:@app_option}} is the set of options supported
* {{S:AppInit}} processes options and checks the argument count
* {{S:AppProcess}} processes arguments (i.e. for each one,
  calls a user defined subroutine typically called {{argProcess}})
* {{argProcess}} outputs messages using {{S:AppMsg}}
* {{S:AppExit}} exits and returns an error code to the
  operating system based on the severity of the messages output
  via {{S:AppMsg}}

H3: Option Definitions

Each option is defined by the fields in the table below.

!block table
Field    Description
Option   option name
Spec     option specification (type, etc.)
Help     short description of option
!endblock

The name of the option is used in several ways:
* as the name of the Perl variable (e.g. $help)
* as the name of the long option (e.g. --help)

If short format is enabled (e.g. -h), by default, the first
character of the option name is used as the option code.
Alternatively, the code to use can be explicitly specified
using the {{Option}} syntax:

V:      name";"code

This should be done if the default codes are not unique.
To specify an option without a parameter,
use the following {{Spec}} syntax:

V:     BOOL

If no {{Spec}} field is specified, this is the default.
The value of a parameter-less option is 1 if the option
if supplied on the command-line.

To specify an option with a parameter, use the following
{{Spec}} syntax:

V:     opt_type"-"validation";"initial_value";"default_value

Only the {{opt_type}} field is mandatory. The second semi-colon
must be present to nominate the parameter as
optional. Otherwise, the parameter is assumed to be required.
The list of supported opt_types is given in the table below.

!block table
Type  Validation      Description
STR   value list      text string
INT   min,max         integer number
NUM   min,max         real number
!endblock

{{min}} and {{max}} are optional in the validation of
numeric options. Typical STR definitions are given below.

V:     STR-(qwe,asd,zxc);qwe;asd       # in-lining of codes
V:     STR-@ok_array;qwe;asd           # array lookup
V:     STR-keys %ok_hash;qwe;asd       # hash validate
V:     STR-values %ok_hash;qwe;asd     # hash validate

An array of STR, INT or NUM can be requested by suffixing
the type with 'LIST' or 'HASH'. LIST create a normal array
and HASH create an associative array in Perl. Array options
can be specified multiple times on the command-line and
multiple items can be specified at once separated by commas.
For a LIST, the values supplied are appended to the current
list. For a HASH, values are treated as follows:

* if the format is 'x=y', the result is: $optname{'x'} = 'y'
* otherwise, the result is: $optname{'x'} = 1

In some cases, it is useful to give an array option an
initial value but permit the user to 'reset' the array back to
empty. This can be done by defining the option as having an
empty optional parameter. i.e. selecting the default value of
a parameter-optional LIST or HASH does not append the default
value - it initialises the array to the default value.

If finer control is required over processing an option, a
routine can be nominated to process an option. To do this,
use the following {{Spec}} syntax:

V:     ROUTINE"-"routine_name";"initial_value";"default_value

The parameter type is specified by the number of semi-colons:

* 0 - no parameter
* 1 - required parameter
* 2 - optional parameter

The parameter, if any, is passed as a string to the nominated
routine.

H3: Configuration Parameters

The configuration parameters supported are summarised below.

!block table
Parameter          Description
inifile            the name of the initialisation file to use, if any
version            the script version
product            the product to which this script belongs, if any
parts              display name & version of components (and exit)
time               display execution time (when exiting)
calltree           display the sequence of function calls causing the exit
!endblock

There are several ways to set configuration parameters:

^ by initialising {{S:%app_config}} before calling {{S:AppInit}}
+ by defining parameters in the '[Configuration]' section of an
  initialisation file
+ by setting parameters on the command line (using the . option)
+ for backwards compatibility, certain parameters can be set other ways:
- {{version}} can be set via $VERSION{'PUBLIC'}
- {{product}} can be set via {{S:AppInit}}

H3: Configuration Data

Configuration data can be stored in {{ini}} files and loaded during
the initialisation stage (i.e. while {{S:AppInit}} is running).
To do this, specify a subroutine as the {{ini_handler}} parameter
for {{S:AppInit}}. The routine is passed the name of the ini file
and an associative array containing the sections (after the standard
ones like 'Configuration' have been removed).
A warning will be produced for any sections not processed by your
routine, so delete each section after you have finished processing it.
A sample processing routine is given below.

!block verbatim
sub iniProcess {
    local($fname, *data) = @_;
#   local();
    local($section);
    local(@my_table, %my_values);

    for $section (sort keys %data) {
        if ($section eq 'MyTable') {
            @my_table = &TableParse($data{$section});
            delete $data{$section};
        }
        elsif ($section eq 'MyValues') {
            %my_values = &AppIniValues($data{$section});
            delete $data{$section};
        }
    }
}
!endblock

H3: Component Descriptions

sdf-2.001/perllib/sdf/tolatex.pl010075500042570001753000000735010661637624400163670ustar00iancmtr00000400000236# $Id: tolatex.pl,v 1.1.1.2 1998/03/22 09:39:20 valerio Exp valerio $
$VERSION{__FILE__} = '$Revision: 1.1.1.2 $';
#
# >>Title::     LaTeX Format Driver
#
# >>Copyright::
# Copyright (c) 1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 30-Oct-98 valerio First Beta release.
# 02-Apr-98 valerio Fixed List closing before Tables.
# 14-Mar-98 valerio Wrote List code.
# 20-Nov-97 valerio Initial rewriting for full use of LaTeX. 
# 12-Aug-97 ianc    Initial writing for Apache Documentation Project
# 14-May-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# This library provides an [[SDF_DRIVER]] which generates
# LaTeX files.
#
# >>Description::
#
# >>Limitations::
#
# >>Resources::
#
# >>Implementation::
#

##### Constants #####

# Default right margin
$_LATEX_DEFAULT_MARGIN = 70;

# Mapping of characters
%_LATEX_CHAR = (
    'backslash'.    '\\',
    'bullet',       '$\bullet$',
    'c',            '\copyright ',
    'cent',         'c',
    'dagger',       '\dagger',
    'doubledagger', '\ddagger',
    'emdash',       '--',
    'endash',       '---',
    'emspace',      '\ \ ',
    'enspace',      '\ ',
    'lbrace',       '{',
    'lbracket',     '[',
    'nbdash',       '-',
    'nbspace',      ' ',
    'nl',           "\n",
    'pound',        '\pounds ',
    'r',            '(r)',
    'rbrace',       '}',
    'rbracket',     ']',
    'tab',          "\t",
    'tm',           '$^{TM}$',
    'yen',          'y',

    # From pod2latex ...

    'amp'	=>	'\\&',	#   ampersand
    'lt'	=>	'$<$',	#   left chevron, less-than
    'gt'	=>	'$>$',	#   right chevron, greater-than
    'quot'	=>	'"',	#   double quote

    "Aacute"	=>	"\\'{A}",	#   capital A, acute accent
    "aacute"	=>	"\\'{a}",	#   small a, acute accent
    "Acirc"	=>	"\\^{A}",	#   capital A, circumflex accent
    "acirc"	=>	"\\^{a}",	#   small a, circumflex accent
    "AElig"	=>	'\\AE',		#   capital AE diphthong (ligature)
    "aelig"	=>	'\\ae',		#   small ae diphthong (ligature)
    "Agrave"	=>	"\\`{A}",	#   capital A, grave accent
    "agrave"	=>	"\\`{a}",	#   small a, grave accent
    "Aring"	=>	'\\u{A}',	#   capital A, ring
    "aring"	=>	'\\u{a}',	#   small a, ring
    "Atilde"	=>	'\\~{A}',	#   capital A, tilde
    "atilde"	=>	'\\~{a}',	#   small a, tilde
    "Auml"	=>	'\\"{A}',	#   capital A, dieresis or umlaut mark
    "auml"	=>	'\\"{a}',	#   small a, dieresis or umlaut mark
    "Ccedil"	=>	'\\c{C}',	#   capital C, cedilla
    "ccedil"	=>	'\\c{c}',	#   small c, cedilla
    "Eacute"	=>	"\\'{E}",	#   capital E, acute accent
    "eacute"	=>	"\\'{e}",	#   small e, acute accent
    "Ecirc"	=>	"\\^{E}",	#   capital E, circumflex accent
    "ecirc"	=>	"\\^{e}",	#   small e, circumflex accent
    "Egrave"	=>	"\\`{E}",	#   capital E, grave accent
    "egrave"	=>	"\\`{e}",	#   small e, grave accent
    "ETH"	=>	'\\OE',		#   capital Eth, Icelandic
    "eth"	=>	'\\oe',		#   small eth, Icelandic
    "Euml"	=>	'\\"{E}',	#   capital E, dieresis or umlaut mark
    "euml"	=>	'\\"{e}',	#   small e, dieresis or umlaut mark
    "Iacute"	=>	"\\'{I}",	#   capital I, acute accent
    "iacute"	=>	"\\'{i}",	#   small i, acute accent
    "Icirc"	=>	"\\^{I}",	#   capital I, circumflex accent
    "icirc"	=>	"\\^{i}",	#   small i, circumflex accent
    "Igrave"	=>	"\\`{I}",	#   capital I, grave accent
    "igrave"	=>	"\\`{i}",	#   small i, grave accent
    "Iuml"	=>	'\\"{I}',	#   capital I, dieresis or umlaut mark
    "iuml"	=>	'\\"{i}',	#   small i, dieresis or umlaut mark
    "Ntilde"	=>	'\\~{N}',	#   capital N, tilde
    "ntilde"	=>	'\\~{n}',	#   small n, tilde
    "Oacute"	=>	"\\'{O}",	#   capital O, acute accent
    "oacute"	=>	"\\'{o}",	#   small o, acute accent
    "Ocirc"	=>	"\\^{O}",	#   capital O, circumflex accent
    "ocirc"	=>	"\\^{o}",	#   small o, circumflex accent
    "Ograve"	=>	"\\`{O}",	#   capital O, grave accent
    "ograve"	=>	"\\`{o}",	#   small o, grave accent
    "Oslash"	=>	"\\O",		#   capital O, slash
    "oslash"	=>	"\\o",		#   small o, slash
    "Otilde"	=>	"\\~{O}",	#   capital O, tilde
    "otilde"	=>	"\\~{o}",	#   small o, tilde
    "Ouml"	=>	'\\"{O}',	#   capital O, dieresis or umlaut mark
    "ouml"	=>	'\\"{o}',	#   small o, dieresis or umlaut mark
    "szlig"	=>	'\\ss',		#   small sharp s, German (sz ligature)
    "THORN"	=>	'\\L',		#   capital THORN, Icelandic
    "thorn"	=>	'\\l',,		#   small thorn, Icelandic
    "Uacute"	=>	"\\'{U}",	#   capital U, acute accent
    "uacute"	=>	"\\'{u}",	#   small u, acute accent
    "Ucirc"	=>	"\\^{U}",	#   capital U, circumflex accent
    "ucirc"	=>	"\\^{u}",	#   small u, circumflex accent
    "Ugrave"	=>	"\\`{U}",	#   capital U, grave accent
    "ugrave"	=>	"\\`{u}",	#   small u, grave accent
    "Uuml"	=>	'\\"{U}',	#   capital U, dieresis or umlaut mark
    "uuml"	=>	'\\"{u}',	#   small u, dieresis or umlaut mark
    "Yacute"	=>	"\\'{Y}",	#   capital Y, acute accent
    "yacute"	=>	"\\'{y}",	#   small y, acute accent
    "yuml"	=>	'\\"{y}',	#   small y, dieresis or umlaut mark
);

# Directive mapping table
%_LATEX_HANDLER = (
    'tuning',           '_LatexHandlerTuning',
    'endtuning',        '_LatexHandlerEndTuning',
    'table',            '_LatexHandlerTable',
    'row',              '_LatexHandlerRow',
    'cell',             '_LatexHandlerCell',
    'endtable',         '_LatexHandlerEndTable',
    'import',           '_LatexHandlerImport',
    'inline',           '_LatexHandlerInline',
    'output',           '_LatexHandlerOutput',
    'object',           '_LatexHandlerObject',
);

# Phrase directive mapping table
%_LATEX_PHRASE_HANDLER = (
    'char',             '_LatexPhraseHandlerChar',
    'import',           '_LatexPhraseHandlerImport',
    'inline',           '_LatexPhraseHandlerInline',
    'variable',         '_LatexPhraseHandlerVariable',
);

# List states

$_LATEX_LISTLEVEL  = 0;
@_LATEX_LISTTYPES = ();

# Table states
$_LATEX_INTABLE = 1;
$_LATEX_INROW   = 2;
$_LATEX_INCELL  = 3;



##### Variables #####

# Right margin position
$_latex_margin = $SDF_USER'var{'LATEX_MARGIN'} || $_LATEX_DEFAULT_MARGIN;

# Counters for ordered lists - index is the level
@_latex_list_num = 0;

# Table states and row types
@_latex_tbl_state = ();
@_latex_row_type = ();

# Column number & starting positions for current table
$_latex_col_num = 0;
@_latex_col_posn = ();

# Current column number
$_latex_current_col = 1;

# Number of Table columns
$_latex_tab_cols = 0;

# Table column alignment
@_latex_colaligns = ();

# Location of the first line of the current row
$_latex_first_row = 0;

# The current cell text
$_latex_cell_current = '';

# The current verbatim escape char
$_latex_verbatim_open  = '';
$_latex_verbatim_close = '';

# Global in example;
$_latex_in_example = 0;

##### Routines #####

#
# >>Description::
# {{Y:LatexFormat}} is an SDF driver which outputs plain text files.
#
sub LatexFormat {
    local(*data) = @_;
    local(@result);
    local(@contents);

    # Initialise defaults
    $_latex_margin = $SDF_USER'var{'LATEX_MARGIN'} || $_LATEX_DEFAULT_MARGIN;

    # Format the paragraphs
    @contents = ();
    @result = &_LatexFormatSection(*data, *contents);

    # Turn into final form and return
    return &_LatexFinalise(*result, *contents);
}

#
# >>_Description::
# {{Y:_LatexFormatSection}} formats a set of SDF paragraphs into text.
# If a parameter is passed to contents, then that array is populated
# with a generated Table of Contents.
#
sub _LatexFormatSection {
    local(*data, *contents) = @_;
    local(@result);
    local($prev_tag, $prev_indent);
    local($para_tag, $para_text, %para_attrs);
    local($directive);


    # Process the paragraphs
    @result = ();
    $prev_tag = '';
    $prev_indent = '';
    while (($para_text, $para_tag, %para_attrs) = &SdfNextPara(*data)) {

        # handle directives
        if ($para_tag =~ /^__(\w+)$/) {
            $directive = $_LATEX_HANDLER{$1};
            if (defined &$directive) {
                &$directive(*result, $para_text, %para_attrs);
            }
            else {
                &AppMsg("warning", "ignoring internal directive '$1' in LATEX driver");
            }
            next;
        }

        # Add the paragraph
        &_LatexParaAdd(*result, $para_tag, $para_text, *para_attrs, $prev_tag,
          $prev_indent, *contents);
    }

    # Do this stuff before starting next loop iteration
    continue {
        unless ($para_tag eq 'PB') {
            $prev_tag = $para_tag;
            $prev_indent = $para_attrs{'in'};
        }
    }

    # Return result
    return @result;
}
       
#
# >>_Description::
# {{Y:_LatexParaAdd}} adds a paragraph.
#
sub _LatexParaAdd {
    local(*result, $para_tag, $para_text, *para_attrs, $prev_tag, $prev_indent, *contents) = @_;
#   local();
    local($in_example);
    local($para_fmt);
    local($para_override);
    local($para);
    local($hdg_level);
    local($toc_jump);
    local($label);

    # Set the example flag
    $in_example = $SDF_USER'parastyles_category{$para_tag} eq 'example';

    if ($in_example) {
       if ($_latex_in_example eq 0) {
          $_latex_in_example = 1;
          $para_text = "\\begin\{verbatim\}\n" . $para_text;
       }
    }
    else {
       if ($_latex_in_example eq 1) {
        $_latex_in_example = 0;
        &_LatexParaAppend(*result, "\n\\end\{verbatim\}\n");
       }
    }

    # Enumerated lists are the same as list paragraphs at the previous level
    if ($para_tag =~ /^LI(\d)$/) {
        $para_tag = $1 > 1 ? "L" . ($1 - 1) : 'N';
    }

    # Get the target format name
    $para_fmt = $SDF_USER'parastyles_to{$para_tag};
    $para_fmt = $para_tag if $para_fmt eq '';

    # Map the attributes
    &SdfAttrMap(*para_attrs, 'latex', *SDF_USER'paraattrs_to,
      *SDF_USER'paraattrs_map, *SDF_USER'paraattrs_attrs,
      $SDF_USER'parastyles_attrs{$para_tag});

    # Build the Table of Contents as we go

    if ($para_tag =~ /^[HAP](\d)$/) {
	$para_fmt = $para_tag;
    }

    # Handle lists (is this needed for text format?)
    elsif ($para_tag =~ /^(L[FUN]?)(\d)$/) {
        $para_attrs{'in'} = $2;
    }

    # Prepend the label, if any (replacing tabs with spaces)
    $label = $para_attrs{'label'};
    $label = 'Note: ' if ($para_tag eq 'Note' || $para_tag eq 'NB') &&
             $label eq '';
    $label =~ s/\\t/ /g;
    $para_text = "{{2:$label}}$para_text" if $label ne '';

    # Indent examples, if necessary
    if ($in_example) {
# do nothing
    }

    # Format the paragraph body
    if ($para_attrs{'verbatim'} || $in_example) {
        $para = $para_text;
        delete $para_attrs{'verbatim'};
    }
    else {
        $para = &_LatexParaText($para_text);
    }

    # If we're in a table, prepend the paragraph onto the current cell
    if (@_latex_tbl_state) {
        if ($para_fmt eq "Line") {
            $_latex_cell_current .= "-" x $_latex_cell_width;
            return;
        }
        $_latex_cell_current .= $para;
        return;
    }

    # Build result
    if ($para_tag eq 'PB') {
        $para = &_LatexElement($para_fmt, $para, %para_attrs);
        &_LatexParaAppend(*result, $para);
    }
    elsif ($in_example && $para_tag eq $prev_tag && !%para_attrs) {
        &_LatexParaAppend(*result, $para);
    }
    else {
        $para = &_LatexElement($para_fmt, $para, %para_attrs);
        push(@result, $para);
    }
}

#
# >>_Description::
# {{Y:_LatexParaText}} converts SDF paragraph text into LATEX.
# 
sub _LatexParaText {
    local($para_text) = @_;
    local($para);
    local($state);
    local($sect_type, $char_tag, $text, %sect_attrs);
    local($added_anchors);
    local(@char_fonts);
    local($char_font);
    local($directive);

    # Process the text
    $para = '';
    $state = 0;
    while (($sect_type, $text, $char_tag, %sect_attrs) =
      &SdfNextSection(*para_text, *state)) {

        # Build the paragraph
        if ($sect_type eq 'special') {
            $directive = $_LATEX_PHRASE_HANDLER{$char_tag};
            if (defined &$directive) {
                &$directive(*para, $text, %sect_attrs);
            }
            else {
                &AppMsg("warning", "ignoring special phrase '$1' in LATEX driver");
            }
	}
        elsif ($sect_type eq 'phrase') {
   

	    if ($char_tag eq 'L') {
                ($text, $url) = &SDF_USER'ExpandLink($text);
                $sect_attrs{'jump'} = $url;
            }

            if ($char_tag ne 'E' 
                && $SDF_USER'phrasestyles_to{$char_tag} ne 'SDF_VERBATIM') {
	      # Escape any special characters
	      $text = &_LatexEscape($text);
	    }

	  if ( $SDF_USER'phrasestyles_to{$char_tag} eq 'SDF_VERBATIM') {
	    _LatexCheckVerbatim($text);
	      $text = $_latex_verbatim_open . $text;
	  }

            # Expand non-breaking spaces, if necessary
	  if ($char_tag eq 'S') {
	    $text =~ s/ /~/g;
	  }
	  
	  
	  # Process formatting attributes
            &SdfAttrMap(*sect_attrs, 'latex', *SDF_USER'phraseattrs_to,
	       *SDF_USER'phraseattrs_map, *SDF_USER'phraseattrs_attrs,
	       $SDF_USER'phrasestyles_attrs{$char_tag});


            # Map the font
            $char_font = $SDF_USER'phrasestyles_to{$char_tag};


            # Add the text for this phrase
            push(@char_fonts, $char_font);
            if ($char_font ne '' && $char_font !~ /^SDF/) {
                $para .= "$char_font$text";
            }
            else {
                $para .= $text;
            }
        }

	  elsif ($sect_type eq 'phrase_end') {
	      $char_font = pop(@char_fonts);
	      $para .= "}}" if $char_font ne '' && $char_font !~ /^SDF/;
              if ($char_font eq 'SDF_VERBATIM') { $para .= $_latex_verbatim_close; }
	  }


        elsif ($sect_type eq 'string') {
            $text = &_LatexEscape($text);
            $para .= $text;
        }

        elsif ($sect_type eq 'phrase') {
        }

        elsif ($sect_type eq 'phrase_end') {
            # do nothing
        }

        else {
            &AppMsg("warning", "unknown section type '$sect_type' in LATEX driver");
        }
    }

    # Return result
    return $para;
}


#
# >>_Description::
# {{Y:_LatexElement}} formats a LATEX element from a
# tag, text and set of attributes.
#
sub _LatexElement {
    local($tag, $text, %attr) = @_;
    local($latex);
    local($prefix, $label);
    local($list_level, $close_list);
    local($cnt);

    # Handle page breaks
    if ($tag eq 'PB') {
        return "\\newpage";
    }

    # For examples, don't word wrap the lines
    if ($tag eq 'E') {
        $latex =  "$text";
    }

    # For lines, output a 'line'
    elsif ($tag eq 'Line') {
        $latex =  ("_" x $_latex_margin) . "\n";
    }

    # For headings, underline the text
    elsif ($tag =~ /^[HAP](\d)/) {
      while ($_LATEX_LISTLEVEL gt 0) {
	$close_list .= "\\end\{$_LATEX_LISTTYPES[$_LATEX_LISTLEVEL]\}\n";
	$_LATEX_LISTLEVEL--;
      }
        $latex = $close_list . "\n" . "$SDF_USER'parastyles_to{$tag}\{$text\}\n"; 
#	    . ($char x length("$SDF_USER'parastyles_to{$tag}\{$text\}\n")) . "\n";
    }


    # For list items, add the necessary "label"
    elsif ($tag =~ /^(L[FUN]?)(\d)$/) {
      
      $ list_level = $2;
      #>        $prefix = " " x ($2 * 5);
      #>        $label  = " " x (($2 - 1) * 5);
      
      if ($1 eq 'LU') {
	if ($_LATEX_LISTLEVEL lt $list_level) {
	  $label = "\\begin\{itemize\} \% Level $list_level\n";
	  $_LATEX_LISTLEVEL = $list_level;
	  @_LATEX_LISTTYPES[$list_level] = "itemize";
	}
	elsif ($_LATEX_LISTLEVEL gt $list_level) {
	  $label = "\\end\{$_LATEX_LISTTYPES[$_LATEX_LISTLEVEL]\}\n";
	  $_LATEX_LISTTYPES[$_LATEX_LISTLEVEL] = "";
	  $_LATEX_LISTLEVEL = $list_level;
	}
      $label .= "\\item ";
      }
        elsif ($1 eq 'L') {
	if ($_LATEX_LISTLEVEL lt $list_level) {
	  $label = "\\begin\{list\}\{\ \}\{\} \% Level $list_level\n";
	  $_LATEX_LISTLEVEL = $list_level;
	  @_LATEX_LISTTYPES[$list_level] = "list";
	}
	elsif ($_LATEX_LISTLEVEL gt $list_level) {
	  $label = "\\end\{$_LATEX_LISTTYPES[$_LATEX_LISTLEVEL]\}\n";
	  $_LATEX_LISTTYPES[$_LATEX_LISTLEVEL] = "";
	  $_LATEX_LISTLEVEL = $list_level;
	}

            $label .= "\\item ";
        }
        elsif ($1 eq 'LF') {
	if ($_LATEX_LISTLEVEL lt $list_level) {
	  $label = "\\begin\{enumerate\} \% Level $list_level\n";
	  $_LATEX_LISTLEVEL = $list_level;
	  @_LATEX_LISTTYPES[$list_level] = "enumerate";
	}
	elsif ($_LATEX_LISTLEVEL gt $list_level) {
	  $label = "\\end\{$_LATEX_LISTTYPES[$_LATEX_LISTLEVEL]\}\n";
	  $_LATEX_LISTTYPES[$_LATEX_LISTLEVEL] = "";
	  $_LATEX_LISTLEVEL = $list_level;
	}

            $label .= "\\item ";
        }
        else {
	if ($_LATEX_LISTLEVEL lt $list_level) {
	  $label = "\\begin\{enumerate\} \% Level $list_level\n";
	  $_LATEX_LISTLEVEL = $list_level;
	  @_LATEX_LISTTYPES[$list_level] = "enumerate";
	}
	elsif ($_LATEX_LISTLEVEL gt $list_level) {
	  $label = "\\end\{$_LATEX_LISTTYPES[$_LATEX_LISTLEVEL]\}\n";
	  $_LATEX_LISTTYPES[$_LATEX_LISTLEVEL] = "";
	  $_LATEX_LISTLEVEL = $list_level;
	}

            $label .= "\\item ";
        }
        $latex = &MiscTextWrap($label . $text, $_latex_margin, $prefix,
          '', 1) . "\n";
    }

    # Otherwise, format as a plain paragraph
    else {
      while ($_LATEX_LISTLEVEL gt 0) {
	$close_list .= "\\end\{$_LATEX_LISTTYPES[$_LATEX_LISTLEVEL]\}\n";
	$_LATEX_LISTLEVEL--;
      }
        $latex = &MiscTextWrap($close_list . "\n" . $text, $_latex_margin, '', '', 1) . "\n";
    }

    # Handle the top attribute
    return $para{'top'} ? "\f\n$latex" : $latex;
}

#
# >>_Description::
# {{Y:_LatexParaAppend}} merges {{para}} into the last paragraph
# in {{@result}}. Both paragraphs are assumed to be examples.
#
sub _LatexParaAppend {
    local(*result, $para) = @_;
#   local();

    $result[$#result] .= "$para\n";
}

#
# >>_Description::
# {{Y:_LatexHandlerTuning}} handles the 'tuning' directive.
#
sub _LatexHandlerTuning {
    local(*outbuffer, $style, %attr) = @_;
#   local();

    # do nothing
}

#
# >>_Description::
# {{Y:_LatexHandlerEndTuning}} handles the 'endtuning' directive.
#
sub _LatexHandlerEndTuning {
    local(*outbuffer, $style, %attr) = @_;
#   local();

    # do nothing
}

#
# >>_Description::
# {{Y:_LatexHandlerTable}} handles the 'table' directive.
#
sub _LatexHandlerTable {
    local(*outbuffer, $columns, %attr) = @_;
    local($tmp, $close_list, $coldim);
    local($tbl_title);

    $_latex_tab_cols = $columns; 
    $coldim = (1 / $columns) - 0.02;

    # Close all yet open lists
    $close_list = "";
    while ($_LATEX_LISTLEVEL gt 0) {
      $close_list .= "\\end\{$_LATEX_LISTTYPES[$_LATEX_LISTLEVEL]\}\n";
      $_LATEX_LISTLEVEL--;
    }
    push(@outbuffer, $close_list . "\n\n");
    

    # Update the state
    push(@_latex_tbl_state, $_LATEX_INTABLE);
    push(@_latex_row_type, '');

    # Calculate the column positions (rounded)

    @_latex_col_posn = &SdfColPositions($columns, $attr{'format'}, $_latex_margin);
    @_latex_colaligns = split(/,/, $attr{'colaligns'});

    # Add the title, if any
    $tbl_title = $attr{'title'};
    if ($tbl_title ne '') {
        push(@outbuffer, "\\begin\{table\}\[H\]\n\\caption\[$tbl_title\]\{$tbl_title\}\n");
    }
    else {
        push(@outbuffer, "\\begin\{table\}\[H\]\n");
      }
    push(@outbuffer, "\\begin\{center\}\n\\begin\{tabular\}");

    $outbuffer[$#outbuffer] .= "\{";
    if ($attr{'style'} ne 'plain' &&  $attr{'style'} ne 'rows') {
      $outbuffer[$#outbuffer] .= "|";
    }
    foreach $tmp (1..$_latex_tab_cols) {
      $outbuffer[$#outbuffer] .= 
	"c";
#	"\@\{\\hspace\{.01\\linewidth\}\}p\{$coldim\\linewidth\}\@\{\\hspace\{.01\\linewidth\}\}";
      if ($attr{'style'} ne 'plain' &&  $attr{'style'} ne 'rows') {
	$outbuffer[$#outbuffer] .= "|";
      }
    }
    $outbuffer[$#outbuffer] .= "\}";

    if ($attr{'style'} ne 'plain') {
      push(@outbuffer, "\\hline");
    }
    push(@outbuffer,"%% -> attribute format = $attr{'format'}");
    push(@outbuffer,"%% -> attribute colaligns = $attr{'colaligns'}");
}

#
# >>_Description::
# {{Y:_LatexHandlerRow}} handles the 'row' directive.
#
sub _LatexHandlerRow {
    local(*outbuffer, $text, %attr) = @_;
#   local();
    local($current_state);

    # Finalise the previous row, if any
    $current_state = $_latex_tbl_state[$#_latex_tbl_state];
    unless ($current_state eq $_LATEX_INTABLE) {
        &_LatexFinalisePrevRow(*outbuffer, $_latex_row_type[$#_latex_row_type]);
    }

    # Start the new row
    push(@outbuffer, "");
    $_latex_col_num = 0;
    $_latex_first_row = $#outbuffer;

    # Update the state
    $_latex_tbl_state[$#_latex_tbl_state] = $_LATEX_INROW;
    $_latex_row_type[$#_latex_row_type] = $text;
#    push(@outbuffer,"%% -> Starting row type $text\n");
}

#
# >>_Description::
# {{Y:_LatexHandlerCell}} handles the 'cell' directive.
#
sub _LatexHandlerCell {
    local(*outbuffer, $text, %attr) = @_;
#   local();
    local($state);
    local($padding);
    local($tmp);

    # Finalise the old cell, if any
    $state = $_latex_tbl_state[$#_latex_tbl_state];
    if ($state eq $_LATEX_INCELL) {
        &_LatexFinishCell(*outbuffer);
#        if ($_latex_col_num > 0) {
#            foreach $tmp ($_latex_first_row .. $#outbuffer) {
#                $padding = $_latex_col_posn[$_latex_col_num - 1] -
#                  length($outbuffer[$tmp]);
#                $padding = 1 if ($padding <= 0);
#                $outbuffer[$tmp] .= " " x $padding;
#            }
#        }
      }

    # Update the state
    $_latex_tbl_state[$#_latex_tbl_state] = $_LATEX_INCELL;
    $_latex_cell_margin = ($_latex_col_num>0?$_latex_col_posn[$_latex_col_num-1]:0);
    $_latex_col_num+=$attr{cols};
    if ($_latex_col_num > $#_latex_col_posn + 1) {
        $_latex_cell_width = $_latex_margin - $_latex_cell_margin - 1;
    } else {
        $_latex_cell_width = $_latex_col_posn[$_latex_col_num-1] -
             $_latex_cell_margin - 1;
    }
    %_latex_cell_attrs = %attr;
    $_latex_cell_current = "";
}

#
# >>_Description::
# {{Y:_LatexFinishCell}} adds the cell text to the output
#
sub _LatexFinishCell {
    local(*outbuffer) = @_;
    $_latex_cell_current =~ s/\s+/ /g;
    local @lines = split(/\n/,
        &MiscTextWrap($_latex_cell_current, $_latex_cell_width,"",'',1));
    local $tmp;
#    foreach $tmp ($#outbuffer+1..$_latex_first_row+$#lines) {
#        push(@outbuffer, " " x $_latex_cell_margin);
#    }

    if ($#lines == 0) {
	if ($_latex_cell_attrs{'align'} eq "Center") {
	  $outbuffer[$#outbuffer] .=
	    "\{\\centering $lines[$#lines]\}";
	} elsif ($_latex_cell_attrs{'align'} eq "Right") {
	  $outbuffer[$#outbuffer] .=
	    "\{\\raggedright  $lines[$#lines]\}";
	} else {
	  $outbuffer[$#outbuffer] .=
	    "\{\\raggedleft  $lines[$#lines]\}";
	}
	if ($_latex_col_num < $_latex_tab_cols) {
	  $outbuffer[$#outbuffer] .= " & ";
	}
    } else {
      if ($_latex_cell_attrs{'align'} eq "Center") {
	$outbuffer[$#outbuffer] .=
	  "\{\\centering ";
      } elsif ($_latex_cell_attrs{'align'} eq "Right") {
	$outbuffer[$#outbuffer] .=
	  "\{\\raggedright ";
      } else {
	  $outbuffer[$#outbuffer] .=
	    "\{\\raggedleft ";
	}
      foreach $tmp (0..$#lines) {
	$outbuffer[$#outbuffer] .= " $lines[$tmp] ";
      }
      $outbuffer[$#outbuffer] .= "\}";
      if ( $_latex_col_num < $_latex_tab_cols ) {
	$outbuffer[$#outbuffer] .= " \& ";
      }
    }
    $_latex_cell_current = "";
    $_latex_current_col++;
}

#
# >>_Description::
# {{Y:_LatexHandlerEndTable}} handles the 'endtable' directive.
#
sub _LatexHandlerEndTable {
    local(*outbuffer, $text, %attr) = @_;
#   local();
    local($state);
    local($row_type);

    # Finalise the table
    $state = pop(@_latex_tbl_state);
    $row_type = pop(@_latex_row_type);
    if ($state eq $_LATEX_INCELL) {
        &_LatexFinalisePrevRow(*outbuffer, $row_type);
        $outbuffer[$#outbuffer] .= "\n";
    }
    elsif ($state eq $_LATEX_INROW) {
        &_LatexFinalisePrevRow(*outbuffer, $row_type);
        $outbuffer[$#outbuffer] .= "\n";
    }
    if ($attr{'style'} ne 'plain') {
      push(@outbuffer,"\\hline\n");
    }
    push(@outbuffer, "\\end\{tabular\}\n\\end\{center\}\n\\end\{table\}\n");
    
}

#
# >>_Description::
# {{Y:_LatexFinalisePrevRow}} finalises the previous row, if any.
#
sub _LatexFinalisePrevRow {
    local(*outbuffer, $row_type) = @_;
#   local();
    local($line_row);
    local($prefix);
    local($tmp);
    local($_);

    &_LatexFinishCell(*outbuffer);
    foreach $tmp ($_latex_first_row..$#outbuffer) {
        $outbuffer[$tmp] =~ s/ *(\n*)$/$1/;
    }

    # If the last row was a heading, underline it
    $outbuffer[$#outbuffer] .= "\\\\";
    if ($row_type ne 'Heading') {
#      while (< $_latex_col_num) {
#	     $outbuffer[$#outbuffer] .= " \& \{\}";
#	     $_latex_col_num++;
#	   }   
    } else {
      $line_row = "";
      if ($attr{'style'} ne 'plain') {
	$line_row = "\\hline";
	if ($attr{'style'} eq 'grid') {
	  $line_row .= "\\hline";
	}
      }
      push(@outbuffer, $line_row);
    }
}

#
# >>_Description::
# {{Y:_LatexHandlerImport}} handles the import directive.
#
sub _LatexHandlerImport {
    local(*outbuffer, $filepath, %attr) = @_;
#   local();
    local($para);

    # Build the result
    &_LatexPhraseHandlerImport(*para, $filepath, %attr);
    push(@outbuffer, "$para\n");
}

#
# >>_Description::
# {{Y:_LatexHandlerInline}} handles the inline directive.
#
sub _LatexHandlerInline {
    local(*outbuffer, $text, %attr) = @_;
#   local();

    # Check we can handle this format
    my $target = $attr{'target'};
    return unless $target eq 'latex' || $target eq 'text';

    # Build the result
    push(@outbuffer, $text);
}

#
# >>_Description::
# {{Y:_LatexHandlerOutput}} handles the 'output' directive.
#
sub _LatexHandlerOutput {
    local(*outbuffer, $text, %attrs) = @_;
#   local();

    # do nothing
}

#
# >>_Description::
# {{Y:_LatexHandlerObject}} handles the 'object' directive.
#
sub _LatexHandlerObject {
    local(*outbuffer, $text, %attrs) = @_;
#   local();

    # Save the margin, if necessary
    if ($text eq 'Variable' && $attrs{'Name'} eq 'LATEX_MARGIN') {
        $_latex_margin = $attrs{'value'};
    }
}

#
# >>_Description::
# {{Y:_LatexPhraseHandlerChar}} handles the 'char' phrase directive.
#
sub _LatexPhraseHandlerChar {
    local(*para, $text, %attr) = @_;
#   local();

    # Map those we know about it
    if (defined($_LATEX_CHAR{$text})) {
        $para .= $_LATEX_CHAR{$text};
    }
    else {
        $para .= $text;
    }
}

#
# >>_Description::
# {{Y:_LatexPhraseHandlerImport}} handles the 'import' phrase directive.
#
sub _LatexPhraseHandlerImport {
    local(*para, $filepath, %attr) = @_;
#   local();
    local($name, $value);

    $para .= "** Unable to import figure $filepath **";
}

#
# >>_Description::
# {{Y:_LatexPhraseHandlerInline}} handles the 'inline' phrase directive.
#
sub _LatexPhraseHandlerInline {
    local(*para, $text, %attr) = @_;
#   local();

    # Build the result
    $para .= $text;
}

#
# >>_Description::
# {{Y:_LatexPhraseHandlerVariable}} handles the 'variable' phrase directive.
#
sub _LatexPhraseHandlerVariable {
    local(*para, $text, %attr) = @_;
#   local();

    # do nothing
}

#
# >>_Description::
# {{Y:_LatexFinalise}} generates the final LaTeX file.
#
sub _LatexFinalise {
    local(*body, *contents) = @_;
#   local(@result);
    local($title, @sdf_title, @title);
    local($version, @head);
    local($body);
    local($macro, @header, @footer);
    local(@dummy);
    local($rec, @html_contents, $toc_posn);

    # Convert the title
    $title = $SDF_USER'var{'DOC_NAME'};
    $author = $SDF_USER'var{'DOC_AUTHOR'};
    $date   = $SDF_USER'var{'DOC_DATE'};

    # Build the HEAD element (and append BODY opening)
    $version = $SDF_USER'var{'SDF_VERSION'};
    @head = (
        '%%% This file was generated using SDF $version by',
        '%%% Ian Clatworthy (ianc@mincom.com) and the 2latex_ driver', 
        '%%% $Id: tolatex.pl,v 1.1.1.2 1998/03/22 09:39:20 valerio Exp valerio $',
        '%%% written by Valerio Aimale .',
        '%%% SDF is freely available from http://www.mincom.com/mtr/sdf',
        ''
    );
    push(@head, '\author{'. $author . '}') if $author;
    push(@head, '\date{'. $date . '}') if $date;
    push(@head, '\title{'. $title . '}') if $title;
    push(@head, '','');
    push(@head, '\begin{document}', '');
    push(@head, '\maketitle') if $title;




    # If requested, provide a Table of Contents
    if (@contents) {
    push(@head, '\tableofcontents');
    }

    # Close eventually open lists
      while ($_LATEX_LISTLEVEL gt 0) {
	push(@body, '',  "\\end\{$_LATEX_LISTTYPES[$_LATEX_LISTLEVEL]\}\n");
	$_LATEX_LISTLEVEL--;
      }
    # Return result
    push(@body, '', '\end{document}');
    return (@head, @body);
}

#
# >>_Description::
# {{Y:_LatexEscape}} escapes special symbols in LaTeX text.
# 
sub _LatexEscape {
    local($text) = @_;
#   local($result);
    local($old_match_flag);

    # Enable multi-line matching
    $old_match_flag = $*;
    $* = 1;

    # Escape the special symbols. Note that it isn't exactly clear
    # from the SGML-Tools and/or QWERTZ DTD documentation as to
    # whether all of these are mandatory, but they shouldn't cause
    # any harm (I hope!)
    $text =~ s/\\/\\verb+\\+/g;
    $text =~ s/\&/\\\&/g;
    $text =~ s/\/\$>\$/g;
    $text =~ s/\"/"/g;
    $text =~ s/\$/\\\$/g;
    $text =~ s/\~/\\verb+~+/g;
    $text =~ s/\^/\\verb+^+/g;
    $text =~ s/\#/\\\#/g;
    $text =~ s/\%/\\\%/g;
    $text =~ s/_/\\\_/g;
    $text =~ s/\|/\|/g;
    $text =~ s/\[/\$[\$/g;
    $text =~ s/\]/\$]\$/g;
    $text =~ s/\{/\\\{/g;
    $text =~ s/\}/\\\}/g;

    # Reset multi-line matching flag
    $* = $old_match_flag;

    # Return result
    $text;
}

#
# >>_Description::
# {{Y:_LatexCheckVerbatim}} checks for un unsed che in the phrase
#
sub _LatexCheckVerbatim {
  local($text) = @_;
  local($match);
  #   local($_i);
  for (33..127) {
    $match = chr;
    if ($text =~ /$match/) {
      ;
    }
    else {
      $_latex_verbatim_open  = '\verb' . $match;
      $_latex_verbatim_close = $match;
      return;
    }
  }
      $_latex_verbatim_open  = '\begin{verbatim}';
      $_latex_verbatim_close = '\end{verbatim}';
      return;
}


# package return value
1;
texHandlerRow {
    local(*outbuffer, $text, %attr) = @_;
#   local();
    local($current_state);

    # Finalise the previous row, if any
    $current_state = $_latex_tbl_state[$#_latex_tbl_sdf-2.001/perllib/sdf/post_mf6.pl010064400042570001753000000246020661420514000164170ustar00iancmtr00000400000236# $Id$
$VERSION{''.__FILE__} = '$Revision$';
#
# >>Title::     mf6 Post Processing Filter
#
# >>Copyright::
# Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 08-Sep-97 ianc    Ported Craig Willis' stuff from gendoc
# -----------------------------------------------------------------------
#
# >>Purpose::
# {{mf6_PostFilter}} post filters plain text format to generate
# MIMS F6 Help format.
#

sub mf6_PostFilter {
    local(*text) = @_;
    local(@result);
    local($_);
    local($client_sw, $header_sw, $idx_k, $idx_s, $key_sw, $part1, $part2, 
          $print_sw, $screen_sw, $subtopic_sw);
    
    $ADD_SW    = $SPLIT_SW  = 0;
    $idx_k     = $idx_s     = -1;
    $CONT_TEXT = '';

    for (@text) {
        $_        =~ s/\n//;
        $line     = $_;
        $print_sw = 1;

        # If '&CLIENT' is found, it is the start of a new file
        if ( $_ =~ /^&CLIENT +/i ) {
            ( $part1 = $& ) =~ s/ +$//;

            if ( $client_sw ) {
                &End_File($subtopic_sw); 
                $header_sw   = 0;
                $key_sw      = 0;
                $screen_sw   = 0;
                $subtopic_sw = 0;
                $idx_k       = -1;
                $idx_s       = -1;
            }
            else {
                push(@result, "\\001\\001\n");
            }

            push(@result, " &BEGIN_TEXT_FILE\n");

            &Get_Client_Dets unless ( $client_sw );
            $client_sw++;
            $line = sprintf(" %-19s%-60s",$part1,$CLIENT);
        }
        # If client name, format line
        elsif ( $_ =~ /^&(CLIENT-NAME) +/i ) {
            ( $part1 = $& ) =~ s/ +$//;
            $line = sprintf(" %-19s%-60s",$part1,$CLIENT_NAME);
        }
        # If machine , format line
        elsif ( $_ =~ /^&MACHINE +/i ) {
            ( $part1 = $& ) =~ s/ +$//;
            $line = sprintf(" %-19s%-60s",$part1,$MACHINE);
        }
        # If you reach '&SUBTOPICS' and 1st one, it is the end of text area
        elsif ( $_ =~ /^&SUBTOPICS +/i ) {
            push(@result, " &END_TEXT\n") unless $subtopic_sw;
            $subtopic_sw++;
            ( $line = $_ ) =~ s/\n$//;
            $line = " $line";
        }
        # Format line for list of variables
        elsif ( $_ =~ /^&(MODULE|MODULE-NAME|TOPIC|TOPIC-GROUP|VERSION) +/ ||
               $_ =~ /^&(ENQUIRY|SAMPLE) */ ) {
            $part1 = $& ;
            ( $part2 = $' ) =~ s/^ +| *$//;
            $part1 =~ s/&//;
            $part1 =~ s/ +//;
            $line = sprintf(" &%-18s%-60s",$part1, $part2);
            $VARIABLES{"$part1"} = $part2;
            $header_sw++;
        }
        # If 'KEYWORD' save keyword to be processed after end of text
        elsif ( $_ =~ /^&KEYWORDS +/i ) {
            $KEYWORDS[++$idx_k] = $';

            # If a keyword continues onto more than one line
            if ( $KEYWORDS[$idx_k] =~ / >> *$/ ) {
                $key_sw++;
            }
            else {
                $key_sw = 0;
            }
            $print_sw = 0;
        }
        # There is a continuation of the KEYWORD over multiple lines
        elsif ( $key_sw ) {
            $KEYWORDS[$idx_k] .= $_;
            if ( $_ =~ / >> *$/ ) {
                $key_sw++;
            }
            else {
                $key_sw = 0;
            }
            $print_sw = 0;
        }           
        # Else TEXT
        else {
            # Start of text area if header_sw is set
            if ( $header_sw > 0 ) {
                if ( $line =~ /^ *$/ || $line eq '' ) {
                    $line = " &BEGIN_TEXT";
                }
                elsif ( $line =~ /^ +\d+(\.\d+)* *\w+/ ) {
                    $line = " &BEGIN_TEXT\n$line";
                }
                $header_sw = 0;
            }
            # If line defines a screen, replace line and set switch to store screen in array
            elsif ( $line =~ /^\d+(\.\d+)*\W+Screen MSM[0-9A-Z]+/ ) {
                if ( $line =~ /^\d+(\.\d+)*\W+Screen / ) {
                    ( $part2 = $' )  =~ s/ *$//;
                }
                else {
                    &AppMsg("warning", "can not file correct screen layout");
                }
                $line = " .INSERT_SCREEN $part2";
                $SCREEN[++$idx_s] = "                               Screen Layout - $part2";
                $screen_sw++;
            }
            elsif ( $line =~ /^\d+(\.\d+)* / ) { # Header line
                $line = sprintf(" %-83s",$line) if ( $client_sw );
                $print_sw = 1;
            }
            # If line is less than 80 and a normal text line and screen, set flag not to print
            else {
                $line = sprintf(" %-80s",$line) if ( $client_sw && length($line) < 75 );
                if ( $screen_sw ) {
                    $SCREEN[++$idx_s] = "$line";
                    $print_sw = 0;
                }
            }
        }
        # If we are printing this line, format it to 83 characters wide
        if ( $print_sw ) {
            $line = &Format_Line($line);
            push(@result, "$line\n");
        }
    }

    &End_File($subtopic_sw); 

    # Return result
    return @result;
}
# 
# Get_Client_Dets: Will ask for a client ID and get client name and machine
#
sub Get_Client_Dets {
    local( @client_array, $client_dir, $client_list, $found_sw);

    # Get the client code
    $CLIENT = $SDF_USER'var{'MIMS_CLIENT_CODE'};
    if ( $CLIENT eq '') {
        &AppExit('fatal', "MIMS_CLIENT_CODE variable must be specified");
    }

    $client_dir  = "/usr/m3conv/client/";
    $client_list = "${client_dir}client.codes";
    unless ( -d "$client_dir") {
        &AppExit('fatal', "Could not locate client directory '$client_dir'");
    }
    unless ( -r "$client_list") {
        &AppExit('fatal', "Could not locate client list '$client_list'");
    }

    open(CLIENT_FH, $client_list) ||
      &AppExit('fatal', "Could not open client list '$client_list'");
    while (  ) {
        @client_array = split(/,/,$_,4);
        if ( $client_array[0] eq $CLIENT) {
            $found_sw++;
            last;
        }
    }
    close ( CLIENT_FH );

    &AppExit('fatal', "$CLIENT is not a valid client code") unless $found_sw;
    
    $CLIENT_NAME = $client_array[$#client_array]; # Client name is last in array
    $CLIENT_NAME =~ s/^ *//;
    $CLIENT_NAME =~ s/\n//;
    $MACHINE     = $client_array[2]; # Client machine is always the 3rd array element
    $CLIENT      = 'MIMS';
    $CLIENT_NAME = 'MIMS';
    $MACHINE     = 'UNIX';
}

#
# End_File: Manipulates the EOF processing within the MIMS Online Help Generation
#
sub End_File {
    local( $end_sw, *result) = @_;
    local( $keyword);

    push(@result, " &END_TEXT\n") unless ( $end_sw );
    foreach $keyword (@KEYWORDS) {
        $keyword =~ s/ *$//;
        $line = sprintf (" %-19s%-62s",'&KEYWORDS',$keyword);
        push(@result, "$line\n");
    }
    undef(@KEYWORDS);
    push(@result, " &END_TEXT_FILE\n");

    if ( $SCREEN[0] ne '' ) {   # If a screen has been specified
        push(@result, " &BEGIN_TEXT_FILE\n");
        push(@result, sprintf(" %-19s%-62s\n",'&CLIENT',$CLIENT));
        push(@result, sprintf(" %-19s%-62s\n",'&CLIENT_NAME',$CLIENT_NAME));
        push(@result, sprintf(" %-19s%-62s\n",'&MACHINE',$MACHINE));
        foreach $key (keys (%VARIABLES)) {
            $VARIABLES{$key} = 'SCREEN' if ( $key eq 'TOPIC' ) ;
            push(@result, sprintf(" &%-18s%-63s\n",$key,$VARIABLES{"$key"}));
        }

        push(@result, "&BEGIN_SCREEN\n");
        foreach $line (@SCREEN) {
            push(@result, "$line\n");
        }
        push(@result, " &END_SCREEN\n");
        push(@result, " &END_TEXT_FILE\n\n");
        undef(@SCREEN);
    }

    $ADD_SW    = 0;
    $CONT_TEXT = '';
}

#
# Format_Line: This will ensure the line is 83 characters long no matter what and
#              will wrap the lines if it is more than 83 chracters long.
#              Used for the MIMS Online Help generation
#
sub Format_Line {
    local( $line, *result) = @_;
    local( $idx, $text);

    $line =~ s/\t/    /g;       # Convert all tabs to 4 spaces
    $line =~ s/ +$//;           # Strip trailing spaces

  LINE: { 
      last LINE unless ( length($line) > 75 || $ADD_SW > 0 ); # 

      # If there is leftover text from previous line
      if ( $ADD_SW ) {
          $ADD_SW = 0;          # Initialise ADD_SW
          # If line is empty or full of spaces, print previous line 
          if ( $line =~ /^ *$/ ) {
              $CONT_TEXT = " $CONT_TEXT" if ( $CONT_TEXT !~ /^ / ) ; # Add leading space if line does not have one
              push(@result, "$CONT_TEXT\n");
              $CONT_TEXT = '';  # Del CONT_TEXT as it has been added to line
              last LINE;
          } 
          else {                # Else add the previous line to the current line
              $CONT_TEXT =~ s/^ +//;
              $CONT_TEXT =~ s/ +$//;

              if ( $line =~ /^ +/ && $SPLIT_SW ) {
                  $line = "${&}${CONT_TEXT}${'}";
                  $SPLIT_SW = 0;
              }
              elsif ( $CONT_TEXT =~ /^\w+/ ) {
                  $line = "${CONT_TEXT} $line";
              }
              else {
                  $line = "${CONT_TEXT}${line}";
              }

          }
      }                         # End ADD_SW

      $CONT_TEXT = '';  # Del CONT_TEXT as it has been added to line      

      # IF line ended in a split word ie thorough-
      if ( $line =~ /\w+\-$/ ) {
          $line = $`;
          ($text = $&) =~ s/\-$//;
          $ADD_SW++;
          $SPLIT_SW++;
      }
      else {
          $SPLIT_SW = 0;
      }

      
      @characters = split(//,$line);
      $idx        = $#characters;
      for (local($i)=($#characters); $i > 0 ; $i-- ) {
          if ( $characters[$i] =~ /\W/ && $i < 75 ) {
              $idx = $i;  
              last;
          }
      }
      for ( local($i)=++$idx; $i <= $#characters; $i++) {
          $CONT_TEXT = "${CONT_TEXT}${characters[$i]}";
      }
      $CONT_TEXT = "${CONT_TEXT}${text}" if ( $text ne '' );

      $#characters = --$idx if ( $idx != $#characters );
      $line        = '';        # Reset line to nothing
      foreach $char (@characters) { $line = "$line$char"};
      $ADD_SW++;      
  }

    $line = " $line" if ( $line !~ /^ / ) ; # Add leading space if line does not have one
    return("$line");
}

# package return value
1;
sdf-2.001/perllib/sdf/macros.pl010064400042570001753000002035410672217057200161610ustar00iancmtr00000400000236# $Id$
$VERSION{''.__FILE__} = '$Revision$';
#
# >>Title::     SDF Macros Library
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 24-Oct-98 ianc    added jump macro, variables parameter for classes
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# This library provides the built-in macros (implemented in [[Perl]]) for
# [[SDF]] files.
#
# >>Description::
# For default values within argument tables:
#
# * the empty string means there is no default
# * the symbol _NULL_ means the default is the empty string.
#
# >>Limitations::
#
# >>Implementation::
# The block macros (i.e. block/endblock, macro/endmacro) work as follows:
#
# ^ the starting macro sets the following global variables:
#   - {{$sdf_block_start}} to the current line number
#   - {{$sdf_block_type}} to {{block}} or {{macro}}
#   - {{@sdf_block_text}} to empty
#   - {{%sdf_block_args}} to the arguments
# + the main parser then builds {{@sdf_block_text}} by searching
#   until it finds the end of the structure (i.e. the end-style macro
#   at the same nesting level)
# + the ending macro then:
#   - clears {{$sdf_block_type}}
#   - processes {{@sdf_block_text}} using {{%sdf_block_args}}
#
# This strategy minimises the work these macros have to do.
#
# The conditional text macros (i.e. if, elsif, etc.) work by changing
# the following global stacks:
#
# * {{@sdf_if_start}} - the starting line number (needed for errors)
# * {{@sdf_if_now}} - is the current text section to be included?
# * {{@sdf_if_yet}} - has a section been included yet?
# * {{@sdf_if_else}} - has the else directive been found yet?
#


# Switch to the user package
package SDF_USER;

##### Constants #####

@_CLASS_PARAMS = (
    'Name       Type        Rule',
    'data       boolean',
    'cited      boolean',
    'root       string',
    'columns    string',
    'style      string',
    'compact    boolean',
    'wide       boolean',
    'headings   boolean',
    'where      string',
    'sort       string',
    'select     string',
    'delete     string',
    'colaligns  string',
    'colvaligns string',
    'wrap       integer',
    'variables  boolean',
);

##### Variables #####

# Loaded modules
%_loaded = ();

# User variables, macros, export lookup table
%var = ();
%macro = ();
%export = ();

# Header/footer parts
%page_hf = ();

# Class definitions
%_class = ();

# Object properties
%obj_name = ();
%obj_long = ();

# Stack of file-related information
@_file_info = ();

# Subsection prefixes
%subsection_prefix = ();

# Event data - paragraphs
@evcode_paragraph = ();
@evmask_paragraph = ();
@evid_paragraph = ();

# Event data - phrases
@evcode_phrase = ();
@evmask_phrase = ();
@evid_phrase = ();

# Event data - variables
@evcode_variable = ();
@evmask_variable = ();
@evid_variable = ();

# Event data - macros
@evcode_macro = ();
@evmask_macro = ();
@evid_macro = ();

# Event data - filters
@evcode_filter = ();
@evmask_filter = ();
@evid_filter = ();

# Event data - tables
@evcode_table = ();
@evmask_table = ();
@evid_table = ();

# Lookup table of readonly & restricted variable families
%restricted = ();
%readonly = ();

##### Initialisation #####

#
# >>Description::
# {{Y:InitMacros}} initialises the global variables in this module.
#
sub InitMacros {
#   local() = @_;
#   local();
    local($name);

    %_loaded = ();
    %var = ();
    %macro = ();
    %export = ();
    %page_hf = ();
    %_class = ();
    %obj_name = ();
    %obj_long = ();
    @_file_info = ();
    %subsection_prefix = ();

    @evcode_paragraph = ();
    @evmask_paragraph = ();
    @evid_paragraph = ();
    @evcode_phrase = ();
    @evmask_phrase = ();
    @evid_phrase = ();
    @evcode_variable = ();
    @evmask_variable = ();
    @evid_variable = ();
    @evcode_macro = ();
    @evmask_macro = ();
    @evid_macro = ();
    @evcode_filter = ();
    @evmask_filter = ();
    @evid_filter = ();
    @evcode_table = ();
    @evmask_table = ();
    @evid_table = ();

    %readonly = ();
    %restricted = ();
    for $name (keys %'sdf_target) {
        $name =~ tr/a-z/A-Z/;
        $restricted{$name} = 1;
    }
}

##### Support Routines #####

#
# >>_Description::
# {{Y:_PageHF}} builds headers or footers.
# {{type}} is 'HEADER' or 'FOOTER'.
# If {{overwrite}} is true, the existing header/footer macros are cleared.
# Otherwise the existing macros are edited.
# {{pages}} is a comma separated list of page names (i.e. First,Right,Left).
# {{component}} is the manual component, if any.
# {{%parts}} is the assocative array of parts within the macro.
sub _PageHF {
    local($type, $overwrite, $component, *pages, *parts) = @_;
    local(@result);
    local($page, $comp_page);
    local($mac_name, $mac_value, %mac_parts);
    local($line, $first, $last);
    local($posn, @posns);
    local($sep, $part, $varname);

    # Build the pages
    for $page (@pages) {
        $comp_page = $component ne '' ? "\U${component}_$page" : "\U$page";
        $mac_name = "PAGE_${comp_page}_$type";

        # Get and save the parts within this macro
        if ($overwrite) {
            %mac_parts = %parts;
        }
        else {
            %mac_parts = &'SdfAttrSplit($page_hf{$comp_page});
            @mac_parts{keys %parts} = values %parts;
        }
        $page_hf{$comp_page} = &'SdfAttrJoin(*mac_parts);

        # Get the part ordering information
        $first = 1;
        $last  = $var{'OPT_HEADINGS'};
        if ($type eq 'HEADER') {
            $last = 2 if $last > 2;
        }
        elsif ($last > 3) {
            $first--;
            $last--;
        }
        @posns = "\U$page" eq 'LEFT' ?
                 ('outer', 'center', 'inner') :
                 ('inner', 'center', 'outer');

        # Build the macro value
        $mac_value = $last >= 3 ? "${type}[size='7pt']" : "$type:";
        $sep = '';
        for $line ($first .. $last) {
            for $posn (@posns) {
                $part = $posn . $line;
                $varname = $mac_name . "_\U$part";
                $var{$varname} = $mac_parts{$part};
                $var{$varname} = '' unless defined $var{$varname};
                $mac_value .= $sep . '[[' . $varname . ']]';
                $sep = '[[tab]]';
            }
            $sep = '[[nl]]';
        }
 
        # Add this macro to the result
#print STDERR "$mac_name macro is:\n$mac_value\n";
        push(@result, "!macro $mac_name", $mac_value, "!endmacro");
    }

    # Return result
    return @result;
}

#
# >>_Description::
# {{Y:_EventFind}} finds a name in a list of event names.
# The index of the event is returned, or -1 if the event is
# not found.
#
sub _EventFind {
    local(*stack, $name) = @_;
    local($index);

    # Search through the stack of names
    for ($index = $#stack; $index >= 0; $index--) {
        return $index if $stack[$index] eq $name;
    }

    # If we reach here, no luck
    return -1;
}

#
# >>_Description::
# {{Y:_ClassHandler}} is the implementation for class filters.
#
sub _ClassHandler {
    local($class, *rules, *text, %param) = @_;
    local(@tbl, @flds, $rec, %values);
    local($name_style, $name_fld, $long_fld);
    local($process);
    local(@out_fields, @out_styles, $out_values);
    local($field, $style, $value);
    local($root);
    local($name, $long, $jump);
    local($params);
    local($tbl_style);
    local($view);
    local($make_vars, $var_name);

    @tbl = &'TableParse(@text);
    @text = ();
    &'TableValidate(*tbl, *rules);

    # Get the class details
    $name_style = $_class{$class,'name_style'};
    $name_fld   = $_class{$class,'name_fld'};
    $long_fld   = $_class{$class,'long_fld'};

    # Get the processing action
    if ($param{'data'}) {
        $process = 'data';
    }
    elsif ($param{'cited'}) {
        $process = 'cited';
    }
    else {
        $process = 'display';
    }

    # Get the 'make variables' flag
    $make_vars = $param{'variables'};
    $var_name = '';

    # For display tables, get the fields to be output
    @out_fields = ();
    @out_styles = ();
    if ($process eq 'display') {
        if ($param{'columns'}) {
            for $field (split(/,/, $param{'columns'})) {
                if ($field =~ /^(\w+):(.+)$/) {
                    push(@out_fields, $2);
                    push(@out_styles, $1);
                }
                else {
                    push(@out_fields, $field);
                    push(@out_styles, '');
                }
            }
        }
        else {
            @out_fields = ($name_fld, $long_fld);
            @out_styles = ($name_style, '');
        }
    }

    # Process the data
    (@flds) = &'TableFields(shift @tbl);
    $root = $param{'root'};
    for $rec (@tbl) {
        if ($rec =~ /^!/) {
            push(@text, $rec);
            next;
        }
        %values = &'TableRecSplit(*flds, $rec);

        # Get the fields of interest
        $name = $values{$name_fld};
        $long = $values{$long_fld};
        $long = $obj_name{$class,$name,$long_fld} if $long eq '';
        $jump = $values{'Jump'};
        $jump = $root . $jump if $jump ne '';
        $jump = $obj_name{$class,$name,'Jump'} if $jump eq '';

        # Convert the name to a legal variable name, if necessary
        if ($make_vars) {
            $var_name = $name;
            $var_name =~ s/\W/_/g;
        }

        # Store the data - we call an internal macro to do this (rather
        # than doing it directly) as this approach ensures that macros
        # embedded in the original data table (e.g. !if) have the
        # expected effect.
        $values{'Jump'} = $jump;
        push(@text, "!_store_ " . join("\000", $class, $process ne 'data',
            $name_fld, $name, $long_fld, $long, %values));
        push(@text, "!define $var_name '{{$name_style:$name}}'") if $var_name ne '';

        # For display tables, build the output
        if ($process eq 'display') {
            if ($long_fld && $long eq '' && $jump eq '') {
                &'AppMsg("warning", "unknown object '$name' in class '$class'");
            }
            @out_values = ();
            for ($i = 0; $i <= $#out_fields; $i++) {
                $field = $out_fields[$i];
                $style = $out_styles[$i];

                # Get the view, if any.
                if ($field =~ /^(\w+)\&/) {
                    $field = $1;
                    $view = $';
                }
                else {
                    $view = '';
                }
        
                # Note: The logic below was originally put there for
                # speed reasons, I think? However, the introduction of
                # views means that Value should now always be called.
                # However, doing that breaks some tests at the moment?

                # Get the value
                if ($field eq $name_fld) {
                    $value = $name;
                }
                elsif ($field eq $long_fld) {
                    $value = $long;
                }
                elsif (defined($values{$field})) {
                    $value = $values{$field};
                }
                else {
                    my $ok_class = $class; $ok_class =~ s/['\\]/\\$&/g;
                    my $ok_name  = $name;  $ok_name  =~ s/['\\]/\\$&/g;
                    my $ok_field = $field; $ok_field =~ s/['\\]/\\$&/g;
                    my $ok_view  = $view;  $ok_view  =~ s/['\\]/\\$&/g;
                    $value = "[[&Value('$ok_class', '$ok_name', '$ok_field', '$ok_view')]]";
                }

                # Apply the format or style
                if ($style ne '') {
                    if (defined($var{"FORMAT_$style"})) {
                        if (substr($value, 0, 2) eq '[[') {
                            $value = "[[$style:" . substr($value, 2);
                        }
                        else {
                            $value = "[[$style:$value]]";
                        }
                    }
                    else {
                        $params = $view ? "[view='$view']" : ":";
                        $value = "{{$style$params$value}}";
                    }
                }

                push(@out_values, $value);
            }
            push(@text, join("~", @out_values));
        }
    }

    # Build the field parsing line.
    # We replace the & with a _ within the field name so that
    # column name parsing doesn't screw up if views are specified.
    my $fields_heading = join("~", @out_fields);
    $fields_heading =~ tr/&/_/;

    # For display tables, finish generating the table
    if ($process eq 'display') {
        $tbl_style = $param{'style'} ? $param{'style'} : 'plain';
        $params = "style='$tbl_style'";
        $params .= "; cellpadding=0; cellspacing=0" if $param{'compact'};
        $params .= "; wide" if $param{'wide'};
        $params .= "; noheadings" unless $param{'headings'};
        $params .= "; where='$param{'where'}'" if $param{'where'} ne '';
        $params .= "; sort='$param{'sort'}'" if $param{'sort'} ne '';
        $params .= "; select='$param{'select'}'" if $param{'select'} ne '';
        $params .= "; delete='$param{'delete'}'" if $param{'delete'} ne '';
        $params .= "; colaligns='$param{'colaligns'}'" if $param{'colaligns'} ne '';
        $params .= "; colvaligns='$param{'colvaligns'}'" if $param{'colvaligns'} ne '';
        $params .= "; wrap='$param{'wrap'}'" if $param{'wrap'} ne '';
        unshift(@text,
          "!block table; $params",
          $fields_heading);
        push(@text, "!endblock");
    }
#printf STDERR "%s<\n", join("<\n", @text);
}

#
# >>_Description::
# {{Y:_ObjectNameEP}} is the event processing for objects in a class.
#
sub _ObjectNameEP {
    local($class, $long_style, $long_fld) = @_;

    # Validate the object
    if (! $obj_name{$class,$text}) {
        &'AppMsg("warning", "unknown object '$text' in class '$class' (name EP)");
    }

    # Generate the hypertext, if any
    if ($attr{'jump'} eq '' && defined $obj_name{$class,$text,'Jump'}) {
        $attr{'jump'} = $obj_name{$class,$text,'Jump'};
    }

    # Expand the object name, if requested
    if ($attr{'expand'}) {
        delete $attr{'expand'};
        if ($long_fld && $obj_name{$class,$text,$long_fld} ne '') {
            $style = $long_style if $long_style ne '';
            $text = $obj_name{$class,$text,$long_fld};
        }
        else {
            &'AppMsg("warning", "unable to expand object '$text' in class '$class'");
        }
    }

    # Cite the object number, if requested
    elsif ($attr{'cite'}) {
        delete $attr{'cite'};
        $style = 'N';
        $text = &Value($class, $text, 'Cite', $attr{'view'});
    }
}

#
# >>_Description::
# {{Y:_ObjectLongEP}} is the event processing for object long names in a class.
#
sub _ObjectLongEP {
    local($class, $name_style, $name_fld) = @_;

    # Validate the object
    if (! $obj_long{$class,$text}) {
        &'AppMsg("warning", "unknown object '$text' in class '$class' (long EP)");
    }

    # Generate the hypertext, if any
    if ($attr{'jump'} eq '' && defined $obj_long{$class,$text,'Jump'}) {
        $attr{'jump'} = $obj_long{$class,$text,'Jump'};
    }

    # Shrink the object name, if requested
    if ($attr{'shrink'}) {
        delete $attr{'shrink'};
        if ($obj_long{$class,$text,$name_fld} ne '') {
            $style = $name_style;
            $text = $obj_long{$class,$text,$name_fld};
        }
        else {
            &'AppMsg("warning", "unable to shrink object '$text' in class '$class'");
        }
    }

    # Cite the object number, if requested
    elsif ($attr{'cite'}) {
        delete $attr{'cite'};
        $style = 'N';
        $text = &Value($class, $text, 'Cite', $attr{'view'});
    }
}

##### General Macros #####

# block - begin a block of text
@_block_MacroArgs = (
    'Name       Type        Default     Rule',
    'filter     filter',
    'params     rest        _NULL_',
);
sub block_Macro {
    local(%arg) = @_;
    local(@text);
#print STDERR "sb1 file: $'ARGV, lineno: $'app_lineno<\n";

    # Update the parser state
    $'sdf_block_start = $'app_lineno;
    $'sdf_block_type = 'block';
    @'sdf_block_text = ();
    %'sdf_block_arg = %arg;

    # Return result
    return ();
}

# endblock - end a block of text
@_endblock_MacroArgs = ();
sub endblock_Macro {
    local(%arg) = @_;
    local(@text);

    # Check the state
    if ($'sdf_block_type ne 'block') {
        &'AppMsg("error", "endblock macro not expected");
        return ();
    }

    # Update the parser state
    $'sdf_block_type = '';

    # Filter the text
    &ExecFilter($'sdf_block_arg{'filter'}, *'sdf_block_text,
      $'sdf_block_arg{'params'}, $'sdf_block_start, $'ARGV, 'filter on ');

    # Mark the text as a section, if necessary
    if (@'sdf_block_text) {
        unshift(@'sdf_block_text,
          "!_bos_ $'sdf_block_start;block on ");
        push(@'sdf_block_text, "!_eos_ $'app_lineno;$'app_context");
    }

    # Return result
    return @'sdf_block_text;
}

# include - include another file
@_include_MacroArgs = (
    'Name       Type        Default     Rule',
    'filename   string',
    'filter     filter      _NULL_',
    'params     rest        _NULL_',
);
sub include_Macro {
    local(%arg) = @_;
    local(@text);
    local($filename, $fullname);
    local($outfile);

    # Get the file location
    $filename = $arg{'filename'};
    $fullname = &FindFile($filename);
    if ($fullname eq '') {
        &'AppMsg("warning", "unable to find '$filename'");
        return ();
    }

    # Get the text
    unless (&FileFetch(*text, $fullname)) {
        &'AppMsg("warning", "unable to read '$fullname'");
        return ();
    }

    # Filter the text
    &ExecFilter($arg{'filter'}, *text, $arg{'params'});

    # Return result
    return ("!_bof_ '$fullname'", @text, "!_eof_");
}

# use - load a library module
@_use_MacroArgs = (
    'Name       Type        Default     Rule',
    'filename   string',
    'filter     filter      sdf',
    'params     rest        _NULL_',
);
sub use_Macro {
    local(%arg) = @_;
    local(@text);
    local($filename, $fullname);

    # Add the sdm extension, if there is none
    $filename = $arg{'filename'};
    $filename .= ".sdm" unless $filename =~ /\.\w+$/;

    # Get the file location
    $fullname = &FindModule($filename);
    if ($fullname eq '') {
        &'AppMsg("warning", "unable to find '$filename'");
        return ();
    }

    # If already loaded, do nothing
    return () if $_loaded{$fullname};

    # Get the text
    unless (&FileFetch(*text, $fullname)) {
        &'AppMsg("warning", "unable to read '$fullname'");
        return ();
    }

    # Mark the library as loaded
    $_loaded{$fullname} = 1;

    # Filter the text
    &ExecFilter($arg{'filter'}, *text, $arg{'params'});

    # Return result
    return ("!_bof_ '$fullname'", @text, "!_eof_");
}

# inherit - load a library
@_inherit_MacroArgs = (
    'Name       Type        Default     Rule',
    'library    string',
);
sub inherit_Macro {
    local(%arg) = @_;
    local(@text);
    local($library, $dos_library);
    local($module);

    # Add the library to the include and module paths
    $library = $arg{'library'};
    $dos_library = $library;
    $dos_library =~ s#/#\\#g;
    $module = (&'NameSplit($library))[1];
    if (-f "$module.sdm") {
        # Module is in the current directory
        $library = '.';
    }
    elsif (&'NameIsAbsolute($library)) {
        push(@include_path, $library);
        push(@module_path, $library);
        $var{'HLP_OPTIONS_ROOT'} .= ", $dos_library";
    }
    else {
        my $lib_dir = &FindLibrary($library);
        if ($lib_dir ne '') {
            push(@include_path, $lib_dir);
            push(@module_path, $lib_dir);
            $var{'HLP_OPTIONS_ROOT'} .= ", $var{'SDF_DOSHOME'}\\$dos_library";
        }
        else {
            &'AppMsg("warning", "unable to find library '$library'");
            return ();
        }
    }

    # Load the matching module
    @text = ("!use '$library/$module'");

    # Return result
    return @text;
}

# execute - include output from a command
@_execute_MacroArgs = (
    'Name       Type        Default     Rule',
    'cmd        string',
    'filter     filter      sdf',
    'params     rest        _NULL_',
);
sub execute_Macro {
    local(%arg) = @_;
    local(@text);
    local($cmd);

    # Get the text
    $cmd = $arg{'cmd'};
    unless (&FileFetch(*text, "$cmd|")) {
        &'AppMsg("error", "failed to execute '$cmd'");
        return ();
    }

    # Filter the text
    #&ExecFilter($arg{'filter'}, *text, $arg{'params'}, 0, "'$cmd'", 'line ');
    &ExecFilter($arg{'filter'}, *text, $arg{'params'});

    # Return result
    return ("!_bof_ '$cmd'", @text, "!_eof_");
}

# import - import an object (e.g. figure) from another package
@_import_MacroArgs = (
    'Name       Type        Default     Rule',
    'filename   string',
    'params     rest        _NULL_',
);
sub import_Macro {
    local(%arg) = @_;
#   local(@text);
    local($filename);
    local(%params);

    # Process the filename and attributes
    $filename = $arg{'filename'};
    %params = &'SdfAttrSplit($arg{'params'});
    &ProcessImageAttrs(*filename, *params);

    # Return result
    return (&'SdfJoin('__import', $filename, %params));
}

# jumps - create jump lines
@_jumps_MacroArgs = (
    'Name       Type        Default     Rule',
    'labels     string',
    'layout     string      Center      ',
);
sub jumps_Macro {
    local(%arg) = @_;
    local(@text);
    local(@subs, $sub, $jump);
    local($sep);
    local($layout);

    # Build the jumps
    @subs = split(/,/, $arg{'labels'});
    $sep = '';
    for $sub (@subs) {
        if ($sub eq '') {
            $sub = "{{CHAR:nl}}";
            $sep = '';
        }
        else {
            $jump = &TextToId($sub);
            $sub = $sep . "{{[jump='#$jump']$sub}}";
            $sep = ' | ';
        }
    }

    # Build the output
    @text = ();
    $layout = $arg{'layout'};
    substr($layout, 0, 1) =~ tr/a-z/A-Z/;
    @text = ("[align='$layout']" . join("", @subs));

    # Return result
    return @text;
}

# subsections - list topic subsections (and create a jump line for HTML)
@_subsections_MacroArgs = (
    'Name       Type        Default     Rule',
    'labels     string',
    'prefix     string      Topic       ',
    'layout     string      Left        ',
);
sub subsections_Macro {
    local(%arg) = @_;
    local(@text);
    local(@subs, $sub, $jump);
    local($prefix);
    local($sep);
    local($layout);

    # Get the list of subsections
    @subs = split(/,/, $arg{'labels'});

    # Get the prefix, if any
    $prefix = '';
    if ($arg{'prefix'} eq 'Topic') {
        $prefix = $topic ne '' ? "$topic - " : '';
    }

    # Save the sub-section data and build the jumps
    $sep = '';
    for $sub (@subs) {
        if ($sub eq '') {
            $sub = "{{CHAR:nl}}";
            $sep = '';
        }
        else {
            $subsection_prefix{$sub} = $prefix;
            $jump = &TextToId($prefix . $sub);
            $sub = $sep . "{{[jump='#$jump']$sub}}";
            $sep = ' | ';
        }
    }

    # Build the output (HTML only for now)
    @text = ();
    if ($var{'OPT_TARGET'} eq 'html') {
        $layout = $arg{'layout'};
        substr($layout, 0, 1) =~ tr/a-z/A-Z/;
        if ($layout ne 'None') {
            @text = ("[align='$layout']" . join("", @subs));
        }
    }

    # Return result
    return @text;
}

# continued - continue a heading onto another page
@_continued_MacroArgs = (
    'Name       Type        Default             Rule',
    'style      string',
    'suffix     string      , {{N:Continued}}',
);
sub continued_Macro {
    local(%arg) = @_;
    local(@text);
    local($target);
    local($style, $suffix);

    # Build result
    $target = $var{'OPT_TARGET'};
    if ($target eq 'html' || $target eq 'hlp') {
        @text = ();
    }
    else {
        $style = $arg{'style'};
        $suffix = $arg{'suffix'};
        @text = $style . "[notoc;noid;continued][[&Previous($style)]]$suffix";
    }

    # Return result
    return @text;
}

# clear - insert a BR CLEAR for HTML
@_clear_MacroArgs = (
    'Name       Type        Default     Rule',
    'type       string      All         ',
);
sub clear_Macro {
    local(%arg) = @_;
    local(@text);

    # Build the result
    if ($var{'OPT_TARGET'} eq 'html') {
        @text = (
            "!block inline",
            "
      ',
            "!endblock");
    }
    else {
        @text = ();
    }

    # Return result
    return @text;
}

# catalog - build a catalog of the objects already loaded for a class
@_catalog_MacroArgs = (
    'Name       Type        Default     Rule',
    'class      symbol',
    'mask       string',
    'params     rest        _NULL_',
);
sub catalog_Macro {
    local(%arg) = @_;
    local(@text);
    local($class, $name_fld);
    local($object, $mask);

    # Get the class and its name field
    $class    = $arg{'class'};
    $name_fld = $_class{$class,'name_fld'};

    # Build the output header
    @text = ("!block $class; $arg{'params'}", $name_fld);

    # Build the result
    $mask = $arg{'mask'};
    if ($mask eq 'cited') {
        for $object (split("\n", $_class{$class,'cited'})) {
            push(@text, $object);
        }
    }
    elsif ($mask =~ /^(\w+):/) {
        my $attr = $1;
        $mask = $';
        my $value;
        for $object (split("\n", $_class{$class,'catalog'})) {
            $value = &Value($class, $object, $attr);
            next if $mask ne '' && $value !~ /^$mask$/;
            push(@text, $object);
        }
    }
    else {
        for $object (split("\n", $_class{$class,'catalog'})) {
            next if $mask ne '' && $object !~ /^$mask$/;
            push(@text, $object);
        }
    }
    push(@text, "!endblock");

    # Return result
    return @text;
}

# namevalues - insert a set of object attributes using a namevalues filter
@_namevalues_MacroArgs = (
    'Name       Type        Default     Rule',
    'class      string',
    'object     string',
    'attributes string',
    'params     rest        _NULL_',
);
sub namevalues_Macro {
    local(%arg) = @_;
    local(@text);
    local($class, $object, @attrs, $attr);

    # Get the details
    $class = $arg{'class'};
    $object = $arg{'object'};
    @attrs = sort split(/,/, $arg{'attributes'});

    # Build result
    @text = ("!block namevalues; $arg{'params'}", "Name|Value");
    for $attr (@attrs) {
        push(@text, "$attr:|" . &Value($class, $object, $attr));
    }
    push(@text, "!endblock");

    # Return result
    return @text;
}

##### Variables Macros #####

# define - define a variable
@_define_MacroArgs = (
    'Name       Type        Default     Rule',
    'name       symbol',
    'value      string      1',
);
sub define_Macro {
    local(%arg) = @_;
    local(@text);
    local($name, $value);
    local($type, $rule);

    # Get the name and value
    $name = $arg{'name'};
    $value = $arg{'value'};

    ## If the variable looks like an enum, output an error
    #if ($name =~ /^[A-Z][a-z]+$/) {
    #    &'AppMsg("error", "'variable '$name' looks like an enumerated value");
    #    return ();
    #}

    # If the variable is in a family, check it has been declared
    if ($name =~ /^([A-Z]+)_/ && $restricted{$1} &&
      !$variables_name{$name}) {
        $status = (defined($var{$name}) || $readonly{$1}) ? 'read-only' : 'unknown';
        &'AppMsg("warning", "'$1' variable '$name' is $status - ignoring definition");
        return ();
    }

    # If the variable has been declared, validate it
    if ($variables_name{$name}) {
        $type = $variables_type{$name};
        $rule = $variables_rule{$name};
        unless (&'MiscCheckRule($value, $rule, $type)) {
            &'AppMsg("warning", "bad value '$value' for variable '$name'");
        }
    }

    # Save the definition
    $var{$name} = $value;

    # Export the variable, if necessary
    if ($export{$name}) {
        @text = (&'SdfJoin('__object', 'Variable',
                'Name',  $name,
                'value', $value));
    }

    # Return result
    return (@text);
}

# default - define a variable (if not already set)
@_default_MacroArgs = (
    'Name       Type        Default     Rule',
    'name       symbol',
    'value      string      1',
);
sub default_Macro {
    local(%arg) = @_;
    local(@text);
    local($name);

    $name = $arg{'name'};

    # Save the definition, if necessary
    &define_Macro(%arg) unless defined($var{$name});

    # Return result
    return ();
}

# undef - undefine a variable
@_undef_MacroArgs = (
    'Name       Type        Default     Rule',
    'name       symbol',
);
sub undef_Macro {
    local(%arg) = @_;
    local(@text);

    # Clear the definition
    delete $var{$arg{'name'}};

    # Return result
    return ();
}

# init - initialise a set of variables
@_init_MacroArgs = (
    'Name       Type        Default     Rule',
    'vars       rest        _NULL_',
);
sub init_Macro {
    local(%arg) = @_;
    local(@text);
    local(%vars, $name, $value);

    # Convert the name-value pairs to define macros
    %vars = &'SdfAttrSplit($arg{'vars'});
    for $name (sort keys %vars) {
        $value = $vars{$name};
        $value =~ s/'/\\'/g;
        push(@text, "!default $name '$value'");
    }

    # Return result
    return @text;
}

# export - mark a variable for export
@_export_MacroArgs = (
    'Name       Type        Default     Rule',
    'name       symbol',
);
sub export_Macro {
    local(%arg) = @_;
    local(@text);
    local($name);

    # Mark for export
    $name = $arg{'name'};
    $export{$name} = 1;

    # If already defined, export it immediately
    if (defined $var{$name}) {
        @text = (&'SdfJoin('__object', 'Variable',
                'Name',  $name,
                'value', $var{$name}));
    }

    # Return result
    return @text;
}

##### Configuration Macros #####

# macro - begin a macro definition
@_macro_MacroArgs = (
    'Name       Type        Default     Rule',
    'name       symbol',
);
sub macro_Macro {
    local(%arg) = @_;
    local(@text);

    # Update the parser state
    $'sdf_block_start = $'app_lineno;
    $'sdf_block_type = 'macro';
    @'sdf_block_text = ();
    %'sdf_block_arg = %arg;

    # Return result
    return ();
}

# endmacro - end a macro definition
@_endmacro_MacroArgs = ();
sub endmacro_Macro {
    local(%arg) = @_;
    local(@text);

    # Check the state
    if ($'sdf_block_type ne 'macro') {
        &'AppMsg("error", "endmacro macro not expected");
        return ();
    }

    # Update the parser state
    $'sdf_block_type = '';

    # Save the definition
    $macro{$'sdf_block_arg{'name'}} = join("\n", @'sdf_block_text);

    # Return result
    return ();
}

# class - declare a class of objects
@_class_MacroArgs = (
    'Name       Type        Default         Rule',
    'name       symbol',
    'styles     string',
    'ids        string      Name,Long',
    'properties string      Jump',
);
sub class_Macro {
    local(%arg) = @_;
    local(@text);
    local($name);
    local($name_style, $long_style);
    local($name_fld, $long_fld);
    local($fld, @rest, @rules);
    local($code);

    # Store the class details
    $name = $arg{'name'};
    ($name_style, $long_style) = split(/,/, $arg{'styles'});
    ($name_fld,   $long_fld)   = split(/,/, $arg{'ids'});
    $_class{$name} = 1;
    $_class{$name,'name_style'} = $name_style;
    $_class{$name,'long_style'} = $long_style;
    $_class{$name,'name_fld'} = $name_fld;
    $_class{$name,'long_fld'} = $long_fld;
    $_class{$name,'properties'}  = $arg{'properties'};

    # Build the rules table
    ($fld, @rest) = split(/,/, $arg{'ids'});
    push(@rest, split(/,/, $arg{'properties'}));
    @rules = ('Field:Category:Rule', "$fld:mandatory");
    push(@rules, "$fld:optional") while ($fld = shift(@rest));

    # Build the filter
    $code = <= 0; $col--) {
        if ($format[$col] eq '') {
            $format[$col] = $unspecified;
            $unspecified = '0%-100%';
        }
    }
    $param{'format'} = join(",", @format);
    delete $param{'narrow'};

    # Build the result
    @text = (&'SdfJoin("__table", $arg{'columns'}, %param));

    # Return result
    return @text;
}

# row - begin a table row
@_row_MacroArgs = (
    'Name       Type        Default     Rule',
    'type       string      Body        ',
    'params     rest        _NULL_',
);
sub row_Macro {
    local(%arg) = @_;
    local(@text);
    local(%param);

    # Check the state
    unless (@'sdf_tbl_state) {
        &'AppMsg("error", "!row not expected");
        return ();
    }

    # For performance, handle the empty parameters case first
    return ('__row[]Body') unless $arg{'type'}.$arg{'params'};

    # Validate and clean the parameters
    %param = &SdfTableParams('row', $arg{'params'}, *rowparams_name,
      *rowparams_type, *rowparams_rule);

    # Build the result
    @text = (&'SdfJoin("__row", $arg{'type'}, %param));

    # Return result
    return @text;
}

# cell - begin a table cell
@_cell_MacroArgs = (
    'Name       Type        Default     Rule',
    'params     rest        _NULL_',
);
sub cell_Macro {
    local(%arg) = @_;
    local(@text);
    local(%param);

    # Check the state
    unless (@'sdf_tbl_state) {
        &'AppMsg("error", "!cell not expected");
        return ();
    }

    # For performance, handle the empty parameters case first
    return ('__cell[]') if $arg{'params'} eq '';

    # Validate and clean the parameters
    %param = &SdfTableParams('cell', $arg{'params'}, *cellparams_name,
      *cellparams_type, *cellparams_rule);

    # Build the result
    @text = (&'SdfJoin("__cell", '', %param));

    # Return result
    return @text;
}

# endtable - end a table
@_endtable_MacroArgs = ();
sub endtable_Macro {
    local(%arg) = @_;
    local(@text);

    # Check the state
    unless (@'sdf_tbl_state) {
        &'AppMsg("error", "!endtable not expected");
        return ();
    }

    # Update the state
    pop(@'sdf_tbl_state);
    pop(@'sdf_tbl_start);

    # Build the result
    @text = (&'SdfJoin("__endtable", ''));

    # Return result
    return @text;
}

##### Header/footer Macros #####

# build_header - build a header macro
@_build_header_MacroArgs = (
    'Name       Type        Default     Rule',
    'pages      string',
    'component  string      _NULL_',
    'parts      rest        _NULL_',
);
sub build_header_Macro {
    local(%arg) = @_;
#   local(@text);
    local(@pages, %parts);

    # Get the arguments
    @pages = split(/,/, $arg{'pages'});
    %parts = &'SdfAttrSplit($arg{'parts'});

    # Return result
    return &_PageHF('HEADER', 1, $arg{'component'}, *pages, *parts);
}

# build_footer - build a footer macro
@_build_footer_MacroArgs = (
    'Name       Type        Default     Rule',
    'pages      string',
    'component  string      _NULL_',
    'parts      rest        _NULL_',
);
sub build_footer_Macro {
    local(%arg) = @_;
#   local(@text);
    local(@pages, %parts);

    # Get the arguments
    @pages = split(/,/, $arg{'pages'});
    %parts = &'SdfAttrSplit($arg{'parts'});

    # Return result
    return &_PageHF('FOOTER', 1, $arg{'component'}, *pages, *parts);
}

# edit_header - edit a header macro
@_edit_header_MacroArgs = (
    'Name       Type        Default     Rule',
    'pages      string',
    'component  string      _NULL_',
    'parts      rest        _NULL_',
);
sub edit_header_Macro {
    local(%arg) = @_;
#   local(@text);
    local(@pages, %parts);

    # Get the arguments
    @pages = split(/,/, $arg{'pages'});
    %parts = &'SdfAttrSplit($arg{'parts'});

    # Return result
    return &_PageHF('HEADER', 0, $arg{'component'}, *pages, *parts);
}

# edit_footer - edit a footer macro
@_edit_footer_MacroArgs = (
    'Name       Type        Default     Rule',
    'pages      string',
    'component  string      _NULL_',
    'parts      rest        _NULL_',
);
sub edit_footer_Macro {
    local(%arg) = @_;
#   local(@text);
    local(@pages, %parts);

    # Get the arguments
    @pages = split(/,/, $arg{'pages'});
    %parts = &'SdfAttrSplit($arg{'parts'});

    # Return result
    return &_PageHF('FOOTER', 0, $arg{'component'}, *pages, *parts);
}


##### Extraction Macros #####

# getdoc - get (SDF) documentation from a file
@_getdoc_MacroArgs = @_include_MacroArgs;
sub getdoc_Macro {
    local(%arg) = @_;
    local(@text);

    # Return result
    return &CommandMacro("sdfget -r -g", %arg);
}

# getcode - get source code (i.e. non-documentation) from a file
@_getcode_MacroArgs = @_include_MacroArgs;
sub getcode_Macro {
    local(%arg) = @_;
    local(@text);

    # Return result
    return &CommandMacro("sdfget -i -g", %arg);
}

# getusage - get the Command Line Interface for a script
@_getusage_MacroArgs = (
    'Name       Type        Default     Rule',
    'command    string',
    'filter     filter      _NULL_',
    'params     rest        _NULL_',
);
sub getusage_Macro {
    local(%arg) = @_;
    local(@text);

    # Execute the command
    my $command = $arg{'command'};
    unless (&FileFetch(*text, "sdfcli $command|")) {
        &'AppMsg("warning", "unable to execute sdfcli on '$command'");
        return ();
    }

    # Filter the text
    &ExecFilter($arg{'filter'}, *text, $arg{'params'});

    # Return result
    return ("!_bof_ 'sdfcli $command'", @text, "!_eof_");
}

# perlapi - get the Application Programming Interface for a Perl library
@_perlapi_MacroArgs = @_include_MacroArgs;
sub perlapi_Macro {
    local(%arg) = @_;
    local(@text);

    # Return result
    return &CommandMacro('sdfapi -j', %arg);
}

##### Event Processing Macros #####

# on - specify processing for an event
@_on_MacroArgs = (
    'Name       Type        Default     Rule',
    'type       symbol                  ',
    'mask       string',
    'id         eventid     _NULL_      <\w+>',
    'code       rest',
);
sub on_Macro {
    local(%arg) = @_;
    local(@text);
    local($type);

    # Store the event
    $type = $arg{'type'};
    if ($type eq 'paragraph') {
        push(@evcode_paragraph, $arg{'code'});
        push(@evmask_paragraph, $arg{'mask'});
        push(@evid_paragraph, $arg{'id'});
    }
    elsif ($type eq 'phrase') {
        push(@evcode_phrase, $arg{'code'});
        push(@evmask_phrase, $arg{'mask'});
        push(@evid_phrase, $arg{'id'});
    }
    elsif ($type eq 'macro') {
        push(@evcode_macro, $arg{'code'});
        push(@evmask_macro, $arg{'mask'});
        push(@evid_macro, $arg{'id'});
    }
    elsif ($type eq 'filter') {
        push(@evcode_filter, $arg{'code'});
        push(@evmask_filter, $arg{'mask'});
        push(@evid_filter, $arg{'id'});
    }
    elsif ($type eq 'table') {
        push(@evcode_table, $arg{'code'});
        push(@evmask_table, $arg{'mask'});
        push(@evid_table, $arg{'id'});
    }

    # Return result
    return ();
}

# off - begin conditional text
@_off_MacroArgs = (
    'Name       Type        Default     Rule',
    'type       symbol                  ',
    'id         eventid                 <\w+>',
);
sub off_Macro {
    local(%arg) = @_;
    local(@text);
    local($type, $id, $num);

    # Find & delete the event, if any
    $type = $arg{'type'};
    $id = $arg{'id'};
    if ($type eq 'paragraph') {
        $num = &_EventFind(*evid_paragraph, $id);
        if ($num != -1) {
            $evcode_paragraph[$num] = '';
            $evid_paragraph[$num] = '';
        }
    }
    elsif ($type eq 'phrase') {
        $num = &_EventFind(*evid_phrase, $id);
        if ($num != -1) {
            $evcode_phrase[$num] = '';
            $evid_phrase[$num] = '';
        }
    }
    elsif ($type eq 'macro') {
        $num = &_EventFind(*evid_macro, $id);
        if ($num != -1) {
            $evcode_macro[$num] = '';
            $evid_macro[$num] = '';
        }
    }
    elsif ($type eq 'filter') {
        $num = &_EventFind(*evid_filter, $id);
        if ($num != -1) {
            $evcode_filter[$num] = '';
            $evid_filter[$num] = '';
        }
    }
    elsif ($type eq 'table') {
        $num = &_EventFind(*evid_table, $id);
        if ($num != -1) {
            $evcode_table[$num] = '';
            $evid_table[$num] = '';
        }
    }

    # Check the event exists
    if ($num == -1) {
        &'AppMsg("warning", "unknown event '$id'");
    }

    # Return result
    return ();
}

##### Miscellaneous Macros #####

# insert - insert the output from a macro
@_insert_MacroArgs = (
    'Name       Type        Default     Rule',
    'macro      string',
    'missing    string      ok          ',
);
sub insert_Macro {
    local(%arg) = @_;
    local(@text);
    local($name, $args);

    # Return result
    ($name, $args) = split(/\s+/, $arg{'macro'}, 2);
    return &ExecMacro($name, $args, $arg{'missing'});
}

# output - change the output file
@_output_MacroArgs = (
    'Name       Type        Default     Rule',
    'outfile    string',
);
sub output_Macro {
    local(%arg) = @_;
    local(@text);

    # Return result
    return ("__output[]" . $arg{'outfile'});
}

# message - output a message during execution
@_message_MacroArgs = (
    'Name       Type        Default     Rule',
    'text       string',
    'type       string      Object      ',
);
sub message_Macro {
    local(%arg) = @_;
    local(@text);
    local($type);

    # Output the message
    $type = "\L$arg{'type'}";
    &'AppMsg($type, $arg{'text'});

    # Return result
    return ();
}

# line - change message parameters
@_line_MacroArgs = (
    'Name       Type        Default     Rule',
    'lineno     integer',
    'filename   string      _NULL_',
    'context    string      line',
);
sub line_Macro {
    local(%arg) = @_;
    local(@text);

    # Update the message variables
    $'app_lineno = $arg{'lineno'};
    $'app_context = $arg{'context'};
    $'app_context .= " " unless $'app_context =~ / $/;
    if ($arg{'filename'} ne '') {
        $'ARGV = $arg{'filename'};
        $var{'FILE_PATH'} = &'NameAbsolute($'ARGV);
        @var{'FILE_DIR', 'FILE_BASE', 'FILE_EXT', 'FILE_SHORT'} =
          &'NameSplit($var{'FILE_PATH'});

        # Update the file and document modified times. Note that
        # we use a constant (1e9 = 09-Sep-2001) during regression
        # testing to minimise file differences.
        $var{'FILE_MODIFIED'} = $var{'SDF_TEST'} ? 1e9 : (stat($'ARGV))[9];
        $var{'DOC_MODIFIED'} = $var{'FILE_MODIFIED'} if
          $var{'DOC_MODIFIED'} < $var{'FILE_MODIFIED'};

        # For the first file, set the document wide values
        if (!defined $var{'DOC_BASE'}) {
            $var{'DOC_PATH'}  = $var{'FILE_PATH'};
            $var{'DOC_DIR'}   = $var{'FILE_DIR'};
            $var{'DOC_BASE'}  = $var{'FILE_BASE'};
            $var{'DOC_EXT'}   = $var{'FILE_EXT'};
            $var{'DOC_SHORT'} = $var{'FILE_SHORT'};
        }
    }

    # Return result
    return ();
}

# macro_interface - build the interface section for an SDF macro
@_macro_interface_MacroArgs = (
    'Name       Type        Default     Rule',
    'name       string',
    'sep_reqd   string      _NULL_',
);
sub macro_interface_Macro {
    local(%arg) = @_;
    local(@text);
    local($name, @arg_list);
    local($format, @rules);
    local(@flds, $rec, %values);
    local($sep_reqd, $sep, $arg, $type);

    # Build usage
    $name = $arg{'name'};
    @text = ("The general syntax is:",
             "E:  !{{2:$name}}");

    # Add the arguments, if any
    @arg_list = eval "\@_${name}_MacroArgs";
    if (@arg_list) {
        push(@text,
             "",
             "The arguments are:",
             "",
             "!block table; format='16,16,20,48'",
             @arg_list,
             "!endblock"
        );

        # Update the usage
        ($format, @rules) = &'TableParse(@arg_list);
        @flds = &'TableFields($format);
        $sep = '';
        $sep_reqd = $arg{'sep_reqd'};
        for $rec (@rules) {
            %values = &'TableRecSplit(*flds, $rec);
            $arg = $values{'Name'};
            if ($sep_reqd eq $arg) {
                $arg = "$sep [$arg]";
            }
            else {
                $arg = "$sep $arg" if $sep;
                $arg = "[$arg]" if $values{'Default'} ne '';
            }
            $text[1] .= " $arg";

            # Get the separator for the NEXT argument
            $type = $values{'Type'};
            $sep = ($type =~ /^symbol$|^rest$/) ? '' : ';';
        }
    }

    # Add the help text, if any
    unshift(@text, "!insert 'MACRO_INTERFACE_BEGIN'");
    push(@text,    "!insert 'MACRO_INTERFACE_END'");

    # Return result
    return @text;
}

# filter_interface - build the interface section for an SDF filter
@_filter_interface_MacroArgs = (
    'Name       Type        Default     Rule',
    'name       string',
);
sub filter_interface_Macro {
    local(%arg) = @_;
    local(@text);
    local($name, @params, @fields);

    # Build usage
    $name = $arg{'name'};
    @text = (
            "The general syntax is:",
            "E:  !block {{2:$name}}",
            "E:  ...",
            "E:  !endblock");

    # Add the parameters, if any
    @params = eval "\@_${name}_FilterParams";
    if (@params) {
        $text[1] .= "[; parameters]";
        if ($params[0] ne 'ANY') {
            push(@text,
                "",
                "The parameters are:",
                "",
                "!block table",
                @params,
                "!endblock"
            );
        }
    }

    # Add the fields, if any
    @fields = eval "\@_${name}_FilterModel";
    if (@fields) {
        $text[2] =~ s/\.\.\./{{table}}/;
        push(@text,
             "",
             "The table fields are:",
             "",
             "!block table",
             @fields,
             "!endblock"
        );
    }

    # Add the help text, if any
    unshift(@text, "!insert 'FILTER_INTERFACE_BEGIN'");
    push(@text,    "!insert 'FILTER_INTERFACE_END'");

    # Return result
    return @text;
}

# class - build the interface section for an SDF class
@_class_interface_MacroArgs = (
    'Name       Type        Default     Rule',
    'name       string',
);
sub class_interface_Macro {
    local(%arg) = @_;
    local(@text);
    local($name, @fields);

    # Build usage
    $name = $arg{'name'};
    @text = (
            "The general syntax is:",
            "E:  !block {{2:$name}}[; parameters]",
            "E:  table of objects",
            "E:  !endblock");

    # Add the fields, if any
    @fields = eval "\@_${name}_FilterModel";
    if (@fields) {
        push(@text,
             "",
             "The object attributes are:",
             "",
             "!block table",
             &'TableFormat(*fields),
             "!endblock"
        );
    }

    # Add the help text, if any
    unshift(@text, "!insert 'CLASS_INTERFACE_BEGIN'");
    push(@text,    "!insert 'CLASS_INTERFACE_END'");

    # Return result
    return @text;
}

##### Internal Macros #####

# _bof_ - beginning of file processing
@__bof__MacroArgs = (
    'Name       Type        Default     Rule',
    'filename   string      _NULL_',
);
sub _bof__Macro {
    local(%arg) = @_;
    local(@text);
    local($new_file);

    # Push the state stack
    push(@_file_info, join("\000", $'ARGV, $'app_lineno, $'app_context,
      scalar(@'sdf_if_now), scalar(@'sdf_tbl_state)));

    # Update the message state
    $new_file = $arg{'filename'};
    if ($new_file ne '') {
        @text = ("!line 0; '$new_file'");
    }
    
    # Return result
    return (@text);
}

# _eof_ - end of file processing
@__eof__MacroArgs = ();
sub _eof__Macro {
    local(%arg) = @_;
    local(@text);
    local($old_file, $old_line, $if_level, $tbl_level);
    local($start);
    local($missing, $last_index);

    # Pop the state stack
    ($old_file, $old_line, $old_context, $if_level, $tbl_level) =
      split(/\000/, pop(@_file_info));

    # Adjust the line number & set the context for messages
    $'app_lineno--;
    $'app_context = "EOF at ";

    # Check not in a block or macro
    if ($'sdf_block_type ne '') {
        $start = $'sdf_block_start;
        &'AppMsg("error", "!end$'sdf_block_type missing for !$'sdf_block_type on line $start");

        # restore the state to something safe
        $'sdf_block_type = '';
    }

    # Check if nesting level is ok
    $missing = scalar(@'sdf_if_now) - $if_level;
    if ($missing != 0) {
        $start = $'sdf_if_start[$#main'sdf_if_start];
        &'AppMsg("error", "!endif missing for !if on line $start");

        # pop unexpected ones so that things resync
        $last_index = $if_level - 1;
        $#main'sdf_if_start = $last_index;
        $#main'sdf_if_now = $last_index;
        $#main'sdf_if_yet = $last_index;
        $#main'sdf_if_else = $last_index;
    }

    # Check table nesting level is ok
    $missing = scalar(@'sdf_tbl_state) - $tbl_level;
    if ($missing != 0) {
        $start = $'sdf_tbl_start[$#main'sdf_tbl_start];
        &'AppMsg("error", "!endtable missing for !table on line $start");

        # pop unexpected ones so that things resync
        $last_index = $tbl_level - 1;
        $#main'sdf_tbl_start = $last_index;
        $#main'sdf_tbl_state = $last_index;
    }

    # Restore the message state
    @text = ("!line $old_line; '$old_file'; '$old_context'");
    
    # Return result
    return (@text);
}

# _bos_ - begin a section
# The performance of this routine is critical so it handles its own arguments
sub _bos__Macro {
    local($args) = @_;

    # Update the line number and context
    ($'app_lineno, $'app_context) = split(/\;/, $args, 2);

    # Update the section counter
    $'sdf_sections++;
}

# _eos_ - end of section
# The performance of this routine is critical so it handles its own arguments
sub _eos__Macro {
    local($args) = @_;

    # Update the line number and context
    ($'app_lineno, $'app_context) = split(/\;/, $args, 2);

    # Update the section counter
    $'sdf_sections--;
}

# _bor_ - beginning of report processing
@__bor__MacroArgs = (
    'Name       Type        Default     Rule',
    'name       symbol',
    'params     rest        _NULL_',
);
sub _bor__Macro {
    local(%arg) = @_;
#   local();
    local($name);
    local($rpt_file);
    local($begin_fn);

    # Update the state
    $name = $arg{'name'};
    push(@'sdf_report_names, $name);

    # Load the report
    $rpt_file = &FindModule(&'NameJoin('', $name, 'sdr'));
    if ($rpt_file) {
        unless (require $rpt_file) {
            &'AppMsg("error", "unable to load report '$rpt_file'");
            return ();
        }
    }
    else {
        &'AppMsg("error", "unable to find report '$name'");
        return ();
    }

    # Begin the report
    $begin_fn = $name . "_ReportBegin";
    if (defined &$begin_fn) {
        &$begin_fn(&SdfFilterParams($name, $params));
    }

    # Return result
    return ();
}

# _eor_ - end of report processing
@__eor__MacroArgs = ();
sub _eor__Macro {
    local(%arg) = @_;
    local(@text);
    local($name);
    local($end_fn);

    # Update the state
    $name = pop(@'sdf_report_names);

    # End the report
    $end_fn = $name . "_ReportEnd";
    if (defined &$end_fn) {
        @text = &$end_fn();
    }
    else {
        &'AppMsg("warning", "unable to find report end routine '$end_fn'");
    }

    # Return result
    return @text;
}

# _store_ - store an object
@__store__MacroArgs = (
    'Name       Type        Default     Rule',
    'object     rest',
);
sub _store__Macro {
    local(%arg) = @_;
#   local();
    local($args);
    local($class, $cited, $name_fld, $name, $long_fld, $long, %values);
    local($cite);
    local($prop, @properties);

    # Get the arguments. Note that Perl 5.004 explicitly warns about
    # an odd number of elements in a hash list, so we need to explicitly
    # check for this and work around it. :-(
    $args = $arg{'object'};
    ($class, $cited, $name_fld, $name, $long_fld, $long, %values) =
      $args =~ /\000$/ ?
      (split(/\000/, $args), '') :
      split(/\000/, $args);

    # Add the name to the catalog for the class, if not already done
    $_class{$class,'catalog'} .= "$name\n" unless $obj_name{$class,$name};

    # Mark the object as cited, if requested
    if ($cited && ! $obj_name{$class, $name, 'Cite'}) {
        $_class{$class,'cited'} .= "$name\n";
        $cite = ++$_class{$class,'cite_count'};
        $values{'Cite'} = "[$cite]";
    }
    
    # Store the name(s)
    $obj_name{$class,$name}           = 1;
    $obj_name{$class,$name,$long_fld} = $long;
    $obj_long{$class,$long}           = 1;
    $obj_long{$class,$long,$name_fld} = $name;

    # Store the properties, if any
    @properties = split(/,/, $_class{$class,'properties'});
    push(@properties, 'Cite') if $cited;
    for $prop (@properties) {
        if ($values{$prop} ne '') {
            $obj_name{$class,$name,$prop} = $values{$prop};
#printf STDERR "%s=%s<\n", "$class.$name.$prop", $values{$prop};
            $obj_long{$class,$long,$prop} = $values{$prop};
        }
    }
}

# _load_look_ - load the look library
@__load_look__MacroArgs = ();
sub _load_look__Macro {
    local(%arg) = @_;
    local(@text);
    local($look);
    local($style);

    # Get the look and style
    $look = $var{'OPT_LOOK'};
    $style = $var{'OPT_STYLE'};

    # Support old style names to improve backwards compatibility
    if ($look eq 'plain') {
        $look = 'simple';
        $var{'OPT_LOOK'} = $look;
    }
    if ($style eq 'newsletter') {
        $style = 'newslttr';
        $var{'OPT_STYLE'} = $style;
    }

    # If paged output is being generated:
    # * Init the page size,
    # * load the look library,
    # * load the style module, and
    # * calculate the layout variables.
    @text = ();
    if ($var{'DOC_PAGED'}) {
        push(@text,
            "!_init_page_size_",
            "!inherit 'look/$look'",
            "!use '$style.sds'",
            "!_calc_layout_vars_");
    }

    # Return result
    return @text;
}

# _init_page_size - initialise the page width and height
@_init_page_size__MacroArgs = ();
sub _init_page_size__Macro {
#   local(%arg) = @_;
#   local(@text);
    local($page_size, $page_width, $page_height);

    $page_size = $'sdf_pagesize{$var{'OPT_PAGE_SIZE'}};
    if ($page_size ne '') {
        ($page_width, $page_height) = split(/\000/, $page_size, 2);
    }
    else {
        # Custom size
        ($page_width, $page_height) = split(/x/, $var{'OPT_PAGE_SIZE'}, 2);
    }
    $page_width = &'SdfPoints($page_width);
    $page_height = &'SdfPoints($page_height);
    $var{'DOC_PAGE_WIDTH'} = $page_width;
    $var{'DOC_PAGE_HEIGHT'} = $page_height;

    # Return result
    return ();
}

# _calc_layout_vars_ - calculate the layout information variables
@__calc_layout_vars__MacroArgs = ();
sub _calc_layout_vars__Macro {
#   local(%arg) = @_;
#   local(@text);
    local($h_top, $h_height, $f_height, $f_top, $m_top, $m_height);
    local($full_width, $text_width, $columns, $col_width);

    # Calculate the height information
    $h_top    = &'SdfVarPoints("OPT_MARGIN_TOP");
    $h_height = &'SdfPageInfo("RIGHT", "HEADER_HEIGHT", "pt");
    $f_height = &'SdfPageInfo("RIGHT", "FOOTER_HEIGHT", "pt");
    $f_top    = $var{'DOC_PAGE_HEIGHT'} - $f_height -
                &'SdfVarPoints("OPT_MARGIN_BOTTOM");
    $m_top    = $h_top + $h_height +
                &'SdfPageInfo("RIGHT", "HEADER_GAP", "pt");
    $m_height = $f_top - $m_top -
                &'SdfPageInfo("RIGHT", "FOOTER_GAP", "pt");

    # Initialise the number of columns
    $var{'OPT_COLUMNS'} = 1 if $var{'OPT_COLUMNS'} < 1;
    $columns = $var{'OPT_COLUMNS'};

    # Calculate the width information
    $full_width = $var{'DOC_PAGE_WIDTH'} - &'SdfVarPoints("OPT_MARGIN_OUTER") -
                  &'SdfVarPoints("OPT_MARGIN_INNER");
    $text_width = $full_width - &'SdfVarPoints("OPT_SIDEHEAD_WIDTH") -
                  &'SdfVarPoints("OPT_SIDEHEAD_GAP");
    $col_width  = ($text_width - ($columns - 1) * $var{"OPT_COLUMN_GAP"}) /
                  $columns;

    # Set the variables
    $var{'DOC_TEXT_HEIGHT'} = $m_height;
    $var{'DOC_FULL_WIDTH'} = $full_width;
    $var{'DOC_TEXT_WIDTH'} = $text_width;
    $var{'DOC_COLUMN_WIDTH'} = $col_width;

    # Return result
    return ();
}

# _load_tuning - load the tuning for a document
@_load_tuning__MacroArgs = ();
sub _load_tuning__Macro {
    local(%arg) = @_;
    local(@text);
    local($name);
    local($target_module);

    # Tell the output driver when we start
    $name = $var{'OPT_TUNING'};
    @text = (&'SdfJoin("__tuning", $name));

    # Add the driver-specific stuff, if any
    $target_module = &FindModule(&'NameJoin('', $var{'OPT_DRIVER'}, 'sdn'));
    if ($target_module) {
        push(@text, "!include '$target_module'");
    }

    # Tell the output driver when we reach the end
    push(@text, "__endtuning[]");

    # Return the result
    return @text;
}

# _load_config_ - load the configuration library
@_load_config__MacroArgs = ();
sub _load_config__Macro {
#   local(%arg) = @_;
#   local(@text);
    local($config);

    $config = $var{'OPT_CONFIG'};
    return ($config ne '') ? ("!inherit '$config'") : ();
}

# package return value
1;
beginning of file processing
@__bof__MacroArgs = (
    'Name       Type        Default     Rule',
    'filename   string      _NULL_',
);
sub _bof__Macro {
   sdf-2.001/perllib/sdf/table.pl010064400042570001753000000737350671107345300157740ustar00iancmtr00000400000236# $Id$
$VERSION{''.__FILE__} = '$Revision$';
#
# >>Title::     Table Processing Library
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# This library provides routines for reading, processing and
# writing {{FMT:TBL}} files.
#
# >>Description::
# Tables are stored in arrays.
# The first element in the array is the {{input format specification}}.
# Remaining elements are data, one record per element.
#
# The routines are often used together as follows:
#
# !block verbatim
#      # Read in the table (using the default format)
#      ($ok, @table) = &TableFetch($table_name);
# 
#      # Process the data records
#      $format = shift @table;
#      @flds = &TableFields($format);
#      for $rec (@table) {
#              %value = &TableRecSplit(*flds, $rec);
#              $value{'Age'}++;        # say ...
#              $rec = &TableRecJoin(*flds, %value);
#      }
#      unshift(@table, $format);
# 
#      # Ouptut the new table (using the default flags)
#      &TablePrint(STDOUT, *table);
# !endblock
#
# Note: Multi-line fields are stored with a newline as the first character
# so be sure to allow for this when processing them.
#
# >>Limitations::
# When validating field-names, the line number and context should be
# set to something meaningful. To achieve this, the line number of
# the format string in the file (if it's in the file, that is!) needs
# to be saved as part of the table.
#
# >>Resources::
#
# >>Implementation::
#

require "sdf/misc.pl";

######### Constants #########

# Tab size used in expanding fixed-width TBL data
$_TABLE_TAB_SIZE = 8;

#
# >>Description::
# {{Y:TABLE_MODEL_MODEL}} is the model for model files.
#
@TABLE_MODEL_MODEL = &TableParse (
    'Field,Category,Rule,AuxRule',
    'Field,key,<\w+>',
    'Category,mandatory,',
    'Rule,optional',
    'AuxRule,optional',
    '_ENTRY_,routine,-,&_TableValRules("ENTRY")',
    '_RECORD_,routine,-,&_TableValRules("RECORD")',
    '_EXIT_,routine ,-,&_TableValRules("EXIT")',
);

# These are the tables of custom read/write routines indexed on type
%_TABLE_CUSTOM_READ = (
);
%_TABLE_CUSTOM_WRITE = (
);

######### Variables #########

# Counter used to ensure {{Y:TableFetch}} is re-entrant
$_table_cnt = 0;

# Counters used by TableValRules()
$_table_keys = 0;
$_table_partkeys = 0;

######### Routines #########

#
# >>Description::
# {{Y:TableFetch}} reads {{file}} as a table defined in {{TBL}} format.
# If the first data line of the file is not an input format specification,
# it can be specified using {{format}}.
# {{success}} is 1 if the file is opened successfully.
# {{records}} is an array of records,
# the first of which is the format specification.
#
sub TableFetch {
    local($file, $format) = @_;
    local($success, @records);
    local($strm);

    # Open the file (ensuring stream_id is unique)
    $strm = sprintf("tbl_s%d", $_table_cnt++);
    open($strm, $file) || return (0);

    # Input the records
    @records = &TableParse($format, <$strm>);

    # close the output
    close($strm);

    # return results
    return (1, @records);
}

#
# >>Description::
# {{Y:TableParse}} converts a list of strings into a table.
#
sub TableParse {
    local(@strings) = @_;
    local(@records);

    # Read in the data
    &_TableReadText(*strings, *records);

    # Return result
    return @records;
}

#
# >>Description::
# {{Y:TableParseUsingParams}} converts a list of strings into a table
# using the nominated parameters. No parameters are supported yet.
#
sub TableParseUsingParams {
    local($ref_to_strings, %params) = @_;
    local(@records);
    local(@strings);

    # Read in the data
    @strings = @$ref_to_strings;
    &_TableReadText(*strings, *records, %params);
#printf STDERR "records are:\n%s<\n", join("<\n", @records);

    # Return result
    return @records;
}

#
# >>Description::
# {{Y:TableValidate}} validates {{@table}} against {{@rules}}.
#
sub TableValidate {
    local(*table, *rules) = @_;
#   local();
    local($i);
    local(@partkeys, $rulesep, @ruleflds, %rule);
    local($fld, %fldcat, %fldrule, %fldauxrule);
    local(@flds, %keylist);

    # Build the validation lookup tables
    @partkeys = ();
    @ruleflds = &TableFields($rules[0]);
    for ($i = 1; $i <= $#rules; $i++) {
        %rule = &TableRecSplit(*ruleflds, $rules[$i]);
        $fld = $rule{"Field"};
        $fldcat{$fld} = $rule{"Category"};
        push(@partkeys, $fld) if $fldcat{$fld} eq 'partkey';
        $fldrule{$fld} = $rule{"Rule"};
        $fldrule{$fld} =~ s#^\<(.*)\>$#/^($1)\$/#;
        $fldauxrule{$fld} = $rule{"AuxRule"};
        $fldauxrule{$fld} =~ s#^\<(.*)\>$#/^($1)\$/#;
    }

    # Check the data
    @flds = &TableFieldsCheck($table[0], "error", %fldcat);
    &MiscDoAction($fldauxrule{"_ENTRY_"}, "_ENTRY_ routine");
    %keylist = ();
    for ($i = 1; $i <= $#table; $i++) {
        next if $table[$i] =~ /^!/;
        &_TableRecordCheck($table[$i], *flds,
          *fldcat, *fldrule, *fldauxrule, *keylist, @partkeys);
    }
    &MiscDoAction($fldauxrule{"_EXIT_"}, "_EXIT_ routine");
}

#
# >>Description::
# {{Y:TablePrint}} outputs {{@table}} to {{strm}}.
# The {{flags}} supported are outlined below.
#
# !block table
# Flag        Description
# TBL format:
# behead      column headings are not included at the top of the output
# delimited   use delimited format - delimiter is the argument (default is tab)
# !endblock
#
sub TablePrint {
    local($strm, *table, %flags) = @_;
#   local();
    local($format, $i);

    # Get the format and output it, unless explicitly asked not to
    $format = $table[0];
    if ($format eq '' || $format =~ /^\w/) {
        &_TableWriteText(*table, $strm, '', %flags);
    }
    else {
        &_TableWriteCustom(*table, $strm, '', %flags);
    }
}

#
# >>Description::
# {{Y:TableFormat}} formats {{@table}} using {{flags}} and
# returns a set of strings. See {{Y:TablePrint}} for a list
# of the flags supported.
#
sub TableFormat {
    local(*table, %flags) = @_;
    local(@strings);

    &_TableWriteText(*table, '', *strings, %flags);

    # Return results
    return @strings;
}

#
# >>Description::
# {{Y:TableFields}} returns the list of fields in {{format}}.
# Behaviour for custom formats is currently undefined.
#
sub TableFields {
    local($format) = @_;
    local(@fields);
    local($sep);

    ($sep, @fields) = &_TableFormatSplit($format);
    return @fields;
}

#
# >>_Description::
# {{Y:_TableFormatSplit}} converts a format string into a separator
# and a list of fields.
#
sub _TableFormatSplit {
    local($format) = @_;
    local($sep, @fields);
    local($sep_regexp);

    # Trim leading whitespace
    $format =~ s/^\s+//;

    # find the field separator
    ($sep) = $format =~ /(\W)/;

    # for custom formats, handling is currently undecided
    if ($format !~ /^\w/) {
        &AppMsg("failure", "TableFields() does not support custom formats yet");
    }

    # for single column tables, the field is the format
    elsif ($sep eq '') {
        @fields = ($format);
    }

    # for fixed-width fields, split on whitespace
    elsif ($sep =~ /\s/) {
        @fields = split(/\s+/, $format);
    }

    # for delimited fields, split on the delimiter
    else {
        # escape any regular expression characters
        $sep_regexp = $sep;
        $sep_regexp =~ s/(\W)/\\$1/g;
        @fields = split(/$sep_regexp/, $format);
    }

    # return results
    return ($sep, @fields);
}

#
# >>_Description::
# {{Y:_TableFormatJoin}} converts a separator and a list of fields
# into a format string.
#
sub _TableFormatJoin {
    local($sep, @fields) = @_;
    local($format);

    # return results
    return join($sep, @fields);
}

#
# >>Description::
# {{Y:TableRecSplit}} converts a record into a set of name-value pairs
# using a set of fields (typically returned from {{Y:TableFields}}).
#
sub TableRecSplit {
    local(*fields, $record) = @_;
    local(%values);

    # store the field values into an associative array, after
    # splitting the record into an (ordinary) array of field values,
    # remembering that the .line pseudo-field always exists
    @values{".line", @fields} = split(/\000/, $record, scalar(@fields) + 1);

    # return results
    %values;
}

#
# >>Description::
# {{Y:TableRecJoin}} converts a set of name-value pairs into a record
# using a set of fields (typically returned from {{Y:TableFields}}).
#
sub TableRecJoin {
    local(*fields, %values) = @_;
    local($record);

    # return results
    return join("\000", @values{".line", @fields});
}

#
# >>Description::
# {{Y:TableRecFormat}} formats a set of name-value pairs into a string
# using a format string.
# Behaviour for custom formats is currently undefined.
#
sub TableRecFormat {
    local($format, %values) = @_;
    local($string);
    local(@values, @fields, $sep, $packfmt);

    # Get the format-related stuff
    @fields = &TableFields($format);
    ($sep) = $format =~ /(\W)/;
    if ($sep =~ /^\s/) {
        $packfmt = &_TablePackStr($format);
    }

    # Get the list of values
    @values = @values{@fields};

    # return results
    return &_TableFmtText(*values, *fields, $sep, $packfmt);
}

#
# >>Description::
# {{Y:TableFilter}} filters a table using an expression.
#
sub TableFilter {
    local(*table, $where, *var) = @_;
    local(@result);
    local($format, @data);
    local(@fields);
    local($_, %o);

    # Split the table into its components
    ($format, @data) = @table;
    @fields = &TableFields($format);

    # Filter the data
    @result = ($format);
    for $_ (@data) {
        next if /^\!/;
        %o = &TableRecSplit(*fields, $_);
        push(@result, $_) if eval $where;
        if ($@) {
            &AppMsg("warning", "table filter '$where' failed: $@");
        }
    }

    # Return result
    return @result;
}

#
# >>Description::
# {{Y:TableDeleteFields}} deletes a list of fields from a table.
#
sub TableDeleteFields {
    local(*table, @junk) = @_;
    local(@result);
    local($format, @data);
    local(%junk);
    local($sep, @fields, @new_fields);
    local($_, %o);

    # Split the table into its components
    ($format, @data) = @table;
    ($sep, @fields) = &_TableFormatSplit($format);

    # Build the new format
    grep($junk{$_}++, @junk);
    @new_fields = ();
    for $_ (@fields) {
        push(@new_fields, $_) unless $junk{$_};
    }
    $format = &_TableFormatJoin($sep, @new_fields);

    # Build the new data records
    @result = ($format);
    for $_ (@data) {
        next if /^\!/;
        %o = &TableRecSplit(*fields, $_);
        push(@result, &TableRecJoin(*new_fields, %o));
    }

    # Return result
    return @result;
}

#
# >>Description::
# {{Y:TableSelectFields}} selects a list of fields from a table.
#
sub TableSelectFields {
    local(*table, @new_fields) = @_;
    local(@result);
    local($format, @data);
    local($sep, @fields);
    local($_, %o);

    # Split the table into its components
    ($format, @data) = @table;
    ($sep, @fields) = &_TableFormatSplit($format);

    # Build the new format
    $format = &_TableFormatJoin($sep, @new_fields);

    # Build the new data records
    @result = ($format);
    for $_ (@data) {
        next if /^\!/;
        %o = &TableRecSplit(*fields, $_);
        push(@result, &TableRecJoin(*new_fields, %o));
    }

    # Return result
    return @result;
}

#
# >>Description::
# {{Y:TableSort}} sorts a table by one of more fields.
# The fields to use are passed in {{by}}.
# If no fields are specified, all fields are used in the order
# they appear in the table.
#
sub TableSort {
    local(*table, @by) = @_;
    local(@result);
    local($format, @data);
    local(@fields);

    # Split the table into its components
    ($format, @data) = @table;
    @fields = &TableFields($format);

    # Sort the data
    if (@by && $by[0] ne '-') {
        @data = sort _TableSortFn @data;

    }
    else {
        @data = sort @data;
    }

    # Return result
    return ($format, @data);
}

#
# >>_Description::
# {{Y:_TableSortFn}} is used by {{Y:TableSort}} as the sorting function.
# This routine compares two records ($a and $b) and return -1, 0 or 1
# depending on whether the first record is greater than, equal to or
# less than the second record respectively.
# {{@by}}, {{$sep}} and {{@fields}} are dynamically scoped within
# {{Y:TableSort}} and are used by this routine.
#
sub _TableSortFn {
    local(%data1, %data2);
    %data1 = &TableRecSplit(*fields, $a);
    %data2 = &TableRecSplit(*fields, $b);
    return join("\000", @data1{@by}) cmp join("\000", @data2{@by});
}

#
# >>Description::
# {{Y:TableIndex}} indexes a table by one of more fields.
# The fields to use are passed in {{by}}.
# If no fields are specified, all fields are used in the order
# they appear in the table. {{index}} is an associative array where:
#
# * the key is the value of the {{by}} fields
# * the data is the index in {{table}} of the matching record
#
# For multiple-field keys, values are separated by a null character (\000).
# The index of the first data record is 1 (the field specification
# record has an index of 0).
# {{@duplicates}} is the list of indices which do not appear in {{%index}}.
# If duplicate keys are found, the highest index is stored in {{%index}}
# for each key.
#
sub TableIndex {
    local(*table, *duplicates, @by) = @_;
    local(%index);
    local(@fields, %values);
    local($index);

    # Get the fields
    @fields = &TableFields($table[0]);

    # Use all fields if none specified
    @by = @fields unless @by;

    # Build the index
    @duplicates = ();
    for ($index = 1; $index <= $#table; $index++) {
        %values = &TableRecSplit(*fields, $table[$index]);
        $key = join("\000", @values{@by});
        if ($index{$key}) {
            push(@duplicates, $index{$key});
        }
        $index{$key} = $index;
    }

    # Return result
    return %index;
}

#
# >>Description::
# {{Y:TableLookup}} returns the name-value pairs for a given key.
# {{@table}} is the data table. {{%index}} is an index created
# using {{Y:TableIndex}}. An empty associative array is returned
# if no matching record is found.
#
sub TableLookup {
    local(*table, *index, @key_values) = @_;
    local(%values);
    local(@fields);
    local($idx);

    $idx = $index{join("\000", @key_values)};
    if ($idx) {
        @fields = &TableFields($table[0]);
        %values = &TableRecSplit(*fields, $table[$idx]);
    }

    # Return result
    return %values;
}

#
# >>Description::
# {{Y:TableFieldsCheck}} is a wrapper around {{Y:TableFields}}
# which checks that the fields contains no duplicates. If {{known}} is
# defined, its keys are used to find unknown fields, if any.
# Any errors encountered are output as such using {{Y:AppMsg}}.
# {{msg_type}} can be used to control the message type - {{error}}
# is the default.
#
sub TableFieldsCheck {
    local($format, $msg_type, %known) = @_;
    local(@flds);
    local(%fldcnt, $fld);
    local(@unknown);

    # The default message type is error
    $msg_type = "error" unless $msg_type;

    # Check that each field only exists once
    %fldcnt = ();
    @flds = &TableFields($format);
    for $fld (@flds) {
        if ($fldcnt{$fld}++) {
            &AppMsg($msg_type, "field '$fld' is duplicated");
        }
    }

    # Check for unknown fields
    if (%known) {
        @unknown = grep(!$known{$_}, @flds);
        if (@unknown) {
            &AppMsg($msg_type, sprintf("unknown field(s): %s",
              join(", ", @unknown)));
        }
    }

    # Return result
    return @flds;
}

#
# >>_Description::
# {{Y:_TableValRules}} is used by {{Y:TABLE_MODEL_MODEL}} to check
# table-wide semantics for validation files. The rules are:
#
# * a key of some form is expected
# * a single partkey is an error
#
# Note that this logic is not directly embedded within
# {{Y:TABLE_MODEL_MODEL}} as doing so greatly reduces readability.
#
sub _TableValRules {
    local($state) = @_;
#       local();

    if ($state eq 'ENTRY') {
        $_table_keys = 0;
        $_table_partkeys = 0;
    }
    elsif ($state eq 'RECORD') {
        $_table_keys++     if $o{"Category"} eq "key";
        $_table_partkeys++ if $o{"Category"} eq "partkey";
    }
    elsif ($state eq 'EXIT') {
        if ($_table_partkeys == 0) {
            &AppMsg("warning", "no keys defined") unless $_table_keys;
        }
        elsif ($_table_partkeys == 1) {
            &AppMsg("error", "bad key definition - only 1 'partkey' field");
        }
    }
    else {
        &AppExit("failure", "unknown state '$state' in _TableValRules()");
    }
}

#
# >>_Description::
# {{Y:_TableRecordCheck}} validates a table record ({{record}})
# against the validation rules defined by {{%fldcat}}, {{%fldrule}}
# and {{%fldauxrule}}. These lookup tables are indexed on field name.
# {{@flds}} is the list of fields in the table.
# {{%keylist}} is an associative array which this routine
# needs for key checking. i.e. checking keys in this record are unique
# and storing the key values from this record for checking by subsequent
# calls. Before this routine is called for the first
# record in a table, it should be cleared by the caller. {{@partkeys}}
# is the list of fields in the key.
#
sub _TableRecordCheck {
    local($record, *flds, *fldcat, *fldrule, *fldauxrule, *keylist, @partkeys) = @_;
#   local();
    local(%o, $fld, $fld_cat, $key_value);
    local($orig_lineno, $orig_context);

    # Setup message parameters
    %o = &TableRecSplit(*flds, $record);
    $orig_lineno = $app_lineno;
    $orig_context = $app_context;
    $app_lineno = $o{'.line'};
    $app_context = 'line ';

    # Check the fields
    for $fld (@flds) {

        # Get the field value
        $_ = $o{$fld};

        # Check the category - for performance, we only check the first letter
        $fld_cat = $fldcat{$fld};
        if ($fld_cat =~ /^k/) {     # key
            $key_value = "$fld:$_";
            &AppMsg("error", "duplicate key on field '$fld', value '$_'") if
              $keylist{$key_value}++;
        }
        elsif ($fld_cat =~ /^m/) {  # mandatory
            &AppMsg("error", "field '$fld' is missing") if $_ eq '';
        }
        elsif ($fld_cat =~ /^e/) {  # expected
            &AppMsg("warning", "field '$fld' is missing") if $_ eq '';
        }
                
        # If there is a value, check the rules, if any.
        if ($_ ne '') {

            # "Rule" validation
            unless (&MiscDoAction($fldrule{$fld}, "rule")) {
                &AppMsg("error", "bad value '$_' for field '$fld'");
            }
            else {
                # "AuxRule" validation
                unless (&MiscDoAction($fldauxrule{$fld}, "rule")) {
                    &AppMsg("warning", "unexpected value '$_' for field '$fld'");
                }
            }
        }
    }

    # Check uniqueness of multi-part keys
    if (@partkeys) {
        $key_value = join("\000", ":", @o{@partkeys});
        &AppMsg("error", sprintf("duplicate key on fields (%s)",
          join(", ", @partkeys))) if $keylist{$key_value}++;
    }

    # If a 'record' rule routine is defined, do it.
    &MiscDoAction($fldauxrule{"_RECORD_"}, "_RECORD_ routine");

    # Restore the original message parameters
    $app_lineno = $orig_lineno;
    $app_context = $orig_context;
}

#
# >>_Description::
# {{Y:_TableReadText}} parses {{@strings}} as {{TBL}} format data using
# the nominated parameters.
# The table is returned in {{@table}}.
# See TableParseUsingParams() for details on the supported parameters.
#
sub _TableReadText {
    local(*strings, *table, %params) = @_;
#   local();
    local($i, $linenum, $_);
    local($format);
    local($sep);
    local($unpackfmt);
    local(@fields, $field_count, $sep_re);
    local($record, $field);
    local($leading_indent_size);

    # Preprocess text:
    # * expand tabs
    # * remove comments and blank lines
    # * convert multi-line records into a single record
    # * record line numbers (needed for meaningful validation messages)
    @table = ();
    for ($i = 0; $i <= $#strings; $i++) {
        $_ = $strings[$i];

        # Trim control-Ms (in case this file came from DOS), the newline
        # and trailing whitespace & expand tabs
        s/\r$//;
        s/\s+$//;
        1 while s/\t+/' ' x (length($&) * $_TABLE_TAB_SIZE - length($`) % $_TABLE_TAB_SIZE)/e;

        unless ($field) {

            # Skip comments and blank lines
            next if /^\s*#/ || /^$/;

            # Get the line number
            $linenum = $i + 1;

            # Lines ending in \ are continued onto the next line,
            # unless there are exactly 2 backslashes at the end of the line
            if (/[^\\]\\\\$/) {
                s/\\$//;
            }
            elsif (s/\\$//) {
                $line = $_;
                for ($i++; $i <= $#strings; $i++) {
                    $_ = $strings[$i];

                    # Trim trailing whitespace, expand tabs & trim leading
                    # whitespace
                    s/\r$//;
                    s/\s+$//;
                    1 while s/\t+/' ' x (length($&) * $_TABLE_TAB_SIZE - length($`) % $_TABLE_TAB_SIZE)/e;
                    s/^\s+//;

                    # Build the logical line
                    $last = ($_ !~ /\\$/ || /[^\\]\\\\$/);
                    s/\\$//;
                    $line .= $_;
                    last if $last;
                }
                $_ = $line;
            }

            # Copy macros into the output
            if (/^\s*\!/) {
                push(@table, $_);
                next;
            }
        }

        # get the format specification, if we haven't already
        if ($format eq '') {
            $_ =~ s/^(\s*)//;
            $leading_indent_size = length($1);
            $format = $_;
            push(@table, $format);
            ($sep) = $format =~ /(\W)/;
            if ($sep =~ /\s/) {
                $unpackfmt = &_TablePackStr($format);
            }
            elsif ($sep ne '') {
                $sep_re = $sep;
                $sep_re =~ s/(\W)/\\$1/g;
                @fields = &TableFields($format);
                $field_count = scalar(@fields);
            }
            next;
        }

        # get records, including those with multi-line cells
        if ($field) {
            if (s/^\>\>//) {

                # Finalise this field
                chop($field);
                $field =~ s/$sep_re/\000/g if $sep_re;
                $record .= $field;

                if (/\<\<$/) {
                    $record .= $`;
                    $field = "\n";
                    next;
                }
                else {
                    $record .= $_;
                    $field = '';
                }
            }
            else {
                $field .= "$_\n";
                next;
            }
        }
        elsif (/\<\<$/) {
            $record = $`;
            $field = "\n";
            next;
        }
        else {
            $record = $_;
        }

        # If we reach here, the record can be saved
        $record = substr($record, $leading_indent_size) if $leading_indent_size;
        push(@table, &_TableBuildRec($record, $sep, $linenum, $unpackfmt,
          $sep_re, $field_count));
    }

    # If a multi-line field was not explicitly terminated,
    # the EOF terminates it
    if ($field) {
        chop($field);
        $field =~ s/$sep_re/\000/g if $sep_re;
        $record .= $field;
        push(@table, &_TableBuildRec($record, $sep, $linenum, $unpackfmt,
          $sep_re, $field_count));
    }
}

sub _TableBuildRec {
    local($rec, $sep, $linenum, $unpackfmt, $sep_re, $field_count) = @_;
    local($result);
    local(@values);
    local($str);
    local($val);

    # Handle single field tables
    if ($sep eq '') {
        @values = ($rec);
    }

    # For fixed-width fields, trim whitespace at the end of each field
    elsif ($sep =~ /\s/) {
        @values = unpack($unpackfmt, $rec);
    }

    # For delimited fields:
    # * split on the delimiter (unless its inside double-quotes), and
    # * process double-quotes, if any
    else {
        $rec =~ s/("[^"]*")/do{$a=$1; $a=~s"$sep_re"\000"g; $a}/eg;
        @values = split(/$sep_re/, $rec, $field_count);
        for $val (@values) {
            $val =~ s/\000/$sep/g;
            if ($val =~ /^"(.*)"$/) {
                $val = $1;
                $val =~ s/""/"/g;
            }
        }
    }

    # Return result
    return join("\000", $linenum, @values);
}

#
# >>_Description::
# {{Y:_TablePackStr}} builds a Perl pack/unpack string for
# a fixed-width format specification.
#
sub _TablePackStr {
    local($format) = @_;
    local($packfmt);

    $packfmt = '';
    while ($format =~ s/\w+\s+//e) {
        $packfmt .= 'A' . length($&);
    }
    $packfmt .= 'A*';
    return $packfmt;
}

#
# >>_Description::
# {{Y:_TableReadCustom}} parses {{@strings}} as custom format data.
# {{format}} is the format specification.
# The list of data records is returned in {{@data}}.
#
sub _TableReadCustom {
    local($format, *strings, *table) = @_;
#   local();
    local($type, $spec, $fn);

    # Get the format type and specification
    @table = ();
    if ($format =~ /^\!(\w+):?/) {
        $type = $1;
        $spec = $';
        $fn = $_TABLE_CUSTOM_READ{$type};
        if ($fn) {
            eval {&$fn(*strings, *table, $type, $spec)};
            &AppExit('failed', $@) if $@;
        }
        else {
            &AppMsg("error", "unsupported custom table type '$type'");
        }
    }
    else {
        &AppMsg("error", "bad table format '$format'");
    }
}

#
# >>_Description::
# {{Y:_TableWriteText}} outputs a table into {{TBL}} format.
# If {{strm}} is true, the table is output to that stream.
# Otherwise, the strings are appended to {{@strings}}.
#
sub _TableWriteText {
    local(*table, $strm, *strings, %flags) = @_;
#       local();
    local($format);
    local(@values, @fields, $sep, $packfmt);
    local($fmtsep, $fmtsep_re);
    local($i);
    local($string);

    # Get the formatting parameters
    $format = $table[0];
    @fields = &TableFields($format);
    ($sep) = $format =~ /(\W)/;
    if ($sep eq '') {
        # do nothing
    }
    elsif ($flags{'delimited'}) {
        $fmtsep = $sep;
        $fmtsep_re = $fmtsep;
        $fmtsep_re =~ s/(\W)/\\$1/g;
        $sep = $flags{'delimited'};
        if ($sep == 1) {
            $sep = "\t";
            if ($fmtsep =~ /\s/) {
                $format =~ s/\s+/\t/g;
            }
            else {
                $format =~ s/$fmtsep_re/\t/g;
            }
        }
        else {
            $format =~ s/$fmtsep_re/$sep/g;
        }
    }
    elsif ($sep =~ /^\s/) {
        $sep = ' ';
        $packfmt = &_TablePackStr($format);
    }

    # Output the header, unless asked not to
    unless ($flags{'behead'}) {
        if ($strm) {
            print $strm $format, "\n";
        }
        else {
            push(@strings, $format);
        }
    }

    # Output the data
    for ($i = 1; $i <= $#table; $i++) {
        @values = split(/\000/, $table[$i]);
        shift(@values);         # skip the .line field
        $string = &_TableFmtText(*values, *fields, $sep, $packfmt);
        if ($strm) {
            print $strm $string, "\n";
        }
        else {
            push(@strings, $string);
        }
    }
}

#
# >>_Description::
# {{Y:_TableFmtText}} formats a text record.
# {{sep}} should be one of the following:
#
# * a space - format is fixed width columns using {{packfmt}}
# * a tab - format is tab-delimited output
# * another character - format is delimited by that character
# 
sub _TableFmtText {
    local(*values, *fields, $sep, $packfmt) = @_;
    local($string);
    local($multiline);
    local($sep_re);
    local($i);

if ($tjhdebug) {
print STDERR "1-------------------------------------------------\n";
for $igc (@values) {
print STDERR "value: $igc<\n";
}
for $igc (@fields) {
print STDERR "field: $igc<\n";
}
print STDERR "2-------------------------------------------------\n";
}

    # Get the list of values, reformatting the last if its multi-line
#       if (substr($values[$#fields], 0, 1) eq "\n") {
#               $values[$#fields] = "<<" . $values[$#fields] . "\n>>";
#               $multiline = $values[$#fields];
#       }
#       else {
#               $multiline = '';
#       }

    # handle single column tables
    if ($sep eq '') {
        $string = $values[0];
    }

    # handle fixed width format
    elsif ($sep eq ' ') {
        $string = pack($packfmt, @values);
    }

    # handle tab-delimited format (skip double quote handling)
    elsif ($sep eq "\t") {
        # remove trailing empty elements
        while (@values && $values[$#values] eq '') {
            pop(@values);
        }
        # TJH 
        for $val (@values) {
            if (substr($val,0,1) eq "\n") {
                print STDERR "\nHACK $val\n" if ($tjhdebug);
                $val = "<<" . $val . ">>";
            }
        }
        $string = join($sep, @values);
    }

    # handle delimited format
    else {
        # remove trailing empty elements
        while (@values && $values[$#values] eq '') {
            pop(@values);
        }

        # Double quote handling - enclose in double quotes if
        # the value contains double quotes or the separator
        $sep_re = $sep;
        $sep_re =~ s/(\W)/\\$1/g;
#               pop(@values) if $multiline;
        for $val (@values) {
            if (substr($val,0,1) eq "\n") {
                print STDERR "\nHACK $val\n" if ($tjhdebug);
                $val = "<<" . $val . ">>";
            } else {
                if ($val =~ s/"/""/g || $val =~ /$sep_re/) {
                    $val = '"' . $val . '"';
                }
            }
            $i++;
        }
#               push(@values, $multiline) if $multiline;
        $string = join($sep, @values);
    }

    # Return result
    return $string;
}

#
# >>_Description::
# {{Y:_TableWriteCustom}} formats a table into a custom format.
#
sub _TableWriteCustom {
    local(*table, $strm, *strings, %flags) = @_;
#       local();

    &AppMsg("failure", "TableWriteCustom() not implemented yet");
}

# package return value
1;
 = ();
    for ($i = 0; $i <= $#strsdf-2.001/perllib/sdf/tomif.pl010075500042570001753000004265250672217057600160330ustar00iancmtr00000400000236# $Id$
$VERSION{''.__FILE__} = '$Revision$';
#
# >>Title::     MIF Format Driver
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 01-Mar-98 ianc    Inner and Outer alignment of tables now supported
#                   David Schooley's patch to MifPathName also applied.
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# This library provides an [[SDF_DRIVER]] which generates
# [[FrameMaker]]'s [[MIF]] (Maker Interchange Format) files.
#
# >>Description::
# Variables supported include:
# 
# * {{MIF_EXT}} - the extension to use for Frame files in jumps
# * {{MIF_BOOK_MODE}} - build a book, rather than a normal document
# * {{MIF_ALL_STYLES}} - output all paragraph styles, rather than
#   just the used ones.
#
# >>Limitations::
# Changing a font family or style does not update the FPostScriptName
# attribute. In practice, this may not be a problem as it may be
# fixed by [[FrameMaker]] during the loading of a [[MIF]] file.
#
# Is _MifProcessControls() the best way to handle document control settings?
# (There may be problems with only processing DOC_* variables at the end.)
#
# We do not support a Running header/footer type of {{paratag}} as
# inserting the name of a Frame paragraph tag would probably be
# meaningless.
#
# Only the predefined colours are currently supported. Ultimately,
# the RGB value of an arbitary color could be converted to CMYK and
# added to the color catalog.
#
# >>Resources::
#
# >>Implementation::
#

##### Constants #####

# FrameMaker 5.0 adds blank pages for tables with titles, so
# this configuration flag controls whether
# we produce real or simple/simulated table titles.
# Unless a book is being generated, generating a list of tables
# only works when table titles are separate paragraphs.
$_MIF_SIMPLE_TBL_TITLES = 1;

# Define the set of paragraph attributes.
@MIF_PARA_ATTRS = (
    'AcrobatLevel',
    'Alignment',
    'AutoNum',
    'BlockSize',
    'BotSepAtIndent',
    'BotSepOffset',
    'BotSeparator',
    'CellAlignment',
    'CellBMarginFixed',
    'CellLMarginFixed',
    'CellMargins',
    'CellRMarginFixed',
    'CellTMarginFixed',
    'FIndent',
    'FIndentOffset',
    'FIndentRelative',
    'FontAngle',
    'FontCase',
    'FontChangeBar',
    'FontColor',
    'FontDW',
    'FontDX',
    'FontDY',
    'FontFamily',
    'FontLocked',
    'FontOutline',
    'FontOverline',
    'FontPairKern',
    'FontPosition',
    'FontSeparation',
    'FontShadow',
    'FontSize',
    'FontStrike',
    'FontUnderlining',
    'FontVar',
    'FontWeight',
    'HyphenMaxLines',
    'HyphenMinPrefix',
    'HyphenMinSuffix',
    'HyphenMinWord',
    'Hyphenate',
    'LIndent',
    'Language',
    'Leading',
    'LetterSpace',
    'LineSpacing',
    'Locked',
    'MaxWordSpace',
    'MinWordSpace',
    'NextTag',
    'NumFormat',
    'NumberFont',
    'NumAtEnd',
    'OptWordSpace',
    'Placement',
    'PlacementStyle',
    'RIndent',
    'RunInDefaultPunct',
    'SpAfter',
    'SpBefore',
    'TabStop',
    'TopSepAtIndent',
    'TopSepOffset',
    'TopSeparator',
    'UseNextTag',
    'WithNext',
    'WithPrev',
);

# Define the set of font attributes.
@MIF_FONT_ATTRS = (
    'Family',
    'Var',
    'Weight',
    'Angle',
    'PostScriptName',
    'Size',
    'Underlining',
    'Overline',
    'Strike',
    'ChangeBar',
    'Outline',
    'Shadow',
    'PairKern',
    'Case',
    'Position',
    'DX',
    'DY',
    'DW',
    'Locked',
    'Separation',
    'Color');

# This is the gap in points between the actual border and the
# decoration for an area on a master page
$_MIF_BORDER_GAP = 6;

# This is the text flow id of the main text
$_MIF_TEXTFLOW_MAIN = 9999;

# This is where we start numbering our text flows from to ensure there
# are no conflicts with those already in templates
$_MIF_TEXTFLOW_START = 10000;

# This is where we start numbering our objects from to ensure there
# are no conflicts with those already in templates
$_MIF_OBJ_REF_START = 11000;

# This is where we start numbering TOC cross-references
$_MIF_TOC_XREF_START = 2000;

# The character mapping table (SDF -> MIF)
%_MIF_CHAR = (
    'bullet',       'Bullet',
    'c',            '\xa9 ',
    'cent',         'Cent',
    'dagger',       'Dagger',
    'doubledagger', 'DoubleDagger',
    'emdash',       'EmDash',
    'endash',       'EnDash',
    'emspace',      'EmSpace',
    'enspace',      'EnSpace',
    'lbrace',       '{',
    'lbracket',     '[',
    'nbdash',       'HardHyphen',
    'nbspace',      'HardSpace',
    'nl',           'HardReturn',
    'pound',        'Pound',
    'r',            '\xa8 ',
    'rbrace',       '}',
    'rbracket',     ']',
    'tab',          'Tab',
    'tm',           '\xaa ',
    'yen',          'Yen',

    # From pod2fm ...

    'amp'       =>      '&',    #   ampersand
    'lt'        =>      '<',    #   left chevron, less-than
    'gt'        =>      '\\>',    #   right chevron, greater-than
    'quot'      =>      '"',    #   double quote

    "Aacute"    =>      "\\xe7 ",    #   capital A, acute accent
    "aacute"    =>      "\\x87 ",    #   small a, acute accent
    "Acirc"     =>      "\\xe5 ",    #   capital A, circumflex accent
    "acirc"     =>      "\\x89 ",    #   small a, circumflex accent
    "AElig"     =>      '\\xae ',    #   capital AE diphthong (ligature)
    "aelig"     =>      '\\xbe ',    #   small ae diphthong (ligature)
    "Agrave"    =>      "\\xcb ",    #   capital A, grave accent
    "agrave"    =>      "\\x88 ",    #   small a, grave accent
    "Aring"     =>      '\\x81 ',    #   capital A, ring
    "aring"     =>      '\\x8c ',    #   small a, ring
    "Atilde"    =>      '\\xcc ',    #   capital A, tilde
    "atilde"    =>      '\\x8b ',    #   small a, tilde
    "Auml"      =>      '\\x80 ',    #   capital A, dieresis or umlaut mark
    "auml"      =>      '\\x8a ',    #   small a, dieresis or umlaut mark
    "Ccedil"    =>      '\\x82 ',    #   capital C, cedilla
    "ccedil"    =>      '\\x8d ',    #   small c, cedilla
    "Eacute"    =>      "\\x83 ",    #   capital E, acute accent
    "eacute"    =>      "\\x8e ",    #   small e, acute accent
    "Ecirc"     =>      "\\xe6 ",    #   capital E, circumflex accent
    "ecirc"     =>      "\\x90 ",    #   small e, circumflex accent
    "Egrave"    =>      "\\xe9 ",    #   capital E, grave accent
    "egrave"    =>      "\\x8f ",    #   small e, grave accent
    "Euml"      =>      "\\xe8 ",    #   capital E, dieresis or umlaut mark
    "euml"      =>      "\\x91 ",    #   small e, dieresis or umlaut mark
    "Iacute"    =>      "\\xea ",    #   capital I, acute accent
    "iacute"    =>      "\\x92 ",    #   small i, acute accent
    "Icirc"     =>      "\\xeb ",    #   capital I, circumflex accent
    "icirc"     =>      "\\x90 ",    #   small i, circumflex accent
    "Igrave"    =>      "\\xe9 ",    #   capital I, grave accent
    "igrave"    =>      "\\x93 ",    #   small i, grave accent
    "Iuml"      =>      "\\xec ",    #   capital I, dieresis or umlaut mark
    "iuml"      =>      "\\x95 ",    #   small i, dieresis or umlaut mark
    "Ntilde"    =>      '\\x84 ',    #   capital N, tilde
    "ntilde"    =>      '\\x96 ',    #   small n, tilde
    "Oacute"    =>      "\\xee ",    #   capital O, acute accent
    "oacute"    =>      "\\x97 ",    #   small o, acute accent
    "Ocirc"     =>      "\\xef ",    #   capital O, circumflex accent
    "ocirc"     =>      "\\x99 ",    #   small o, circumflex accent
    "Ograve"    =>      "\\xf1 ",    #   capital O, grave accent
    "ograve"    =>      "\\x98 ",    #   small o, grave accent
    "Oslash"    =>      "\\xaf ",    #   capital O, slash
    "oslash"    =>      "\\xbf ",    #   small o, slash
    "Otilde"    =>      "\\xcd ",    #   capital O, tilde
    "otilde"    =>      "\\x9b ",    #   small o, tilde
    "Ouml"      =>      "\\x85 ",    #   capital O, dieresis or umlaut mark
    "ouml"      =>      "\\x9a ",    #   small o, dieresis or umlaut mark
    "Uacute"    =>      "\\xf2 ",    #   capital U, acute accent
    "uacute"    =>      "\\x9c ",    #   small u, acute accent
    "Ucirc"     =>      "\\xf3 ",    #   capital U, circumflex accent
    "ucirc"     =>      "\\x9e ",    #   small u, circumflex accent
    "Ugrave"    =>      "\\xf4 ",    #   capital U, grave accent
    "ugrave"    =>      "\\x9d ",    #   small u, grave accent
    "Uuml"      =>      "\\x86 ",    #   capital U, dieresis or umlaut mark
    "uuml"      =>      "\\x9f ",    #   small u, dieresis or umlaut mark
    "yuml"      =>      "\\xd8 ",    #   small y, dieresis or umlaut mark
);

# Lookup table of colour values used by _MifMapColor()
%_MIF_COLOR = (
    'black',    'Black',
    '000000',   'Black',
    'white',    'White',
    'ffffff',   'White',
    'red',      'Red',
    'ff0000',   'Red',
    'green',    'Green',
    '008000',   'Green',
    'blue',     'Blue',
    '0000ff',   'Blue',
    'yellow',   'Yellow',
    'ffff00',   'Yellow',
    'magenta',  'Magenta',
    'ff00ff',   'Magenta',
    'cyan',     'Cyan',
    '00ffff',   'Cyan',
);

# Lookup table of fill values
%_MIF_FILL_CODE = (
    100,    0,
    90,     1,
    70,     2,
    50,     3,
    30,     4,
    10,     5,
    3,      6,
    0,      15,
);

# Lookup table of known index types
%_MIF_INDEX_CODE = (
    "standard",     2,
    "comment",      3,
    "subject",      4,
    "author",       5,
);

# This is the numeric code matching the HardReturn character
$_MIF_HARDRETURN_CODE = 10;

#
# >>_Description::
# {{Y:%_MIF_REF}} maps logical names to MIF reference names.
#
%_MIF_REF = (
    'table',        'ATbl',
    'figure',       'AFrame',
);

# Lookup table of title tags for objects
%_MIF_TITLE_TAG = (
    'table',        'TT',
    'figure',       'FT',
);

# Lookup table of no-title tags for objects
%_MIF_NOTITLE_TAG = (
    'table',        'TA',
    'figure',       'FA',
);

# The text at the end of each paragraph and its length
$_MIF_PARA_END = " >\n> # end of Para";
$_MIF_PARA_END_LEN = length($_MIF_PARA_END);

#
# >>_Description::
# {{Y:%_MIF_DFLT_BOOK_ATTRS}} contains the default set of
# book attributes.
#
%_MIF_DFLT_BOOK_ATTRS = (
    "StartPageSide", "ReadFromFile",
    "PageNumbering", "Continue",
    "PgfNumbering", "Continue",
    "PageNumPrefix", "",
    "PageNumSuffix", "",
    "DefaultPrint", "Yes",
    "DefaultApply", "Yes",
);

# Mapping table for logical variable names to Frame equivalents
%_MIF_VAR_MAP = (
    'Running_H_F_1',    'Running H/F 1',
    'Running_H_F_2',    'Running H/F 2',
    'Running_H_F_3',    'Running H/F 3',
    'Running_H_F_4',    'Running H/F 4',
);

# Set of legal tab types
%_MIF_TAB_TYPE = (
    'Left',         1,
    'Center',       1,
    'Right',        1,
    'Decimal',      1,
);

# Directive mapping table
%_MIF_HANDLER = (
    'tuning',         '_MifHandlerTuning',
    'endtuning',      '_MifHandlerEndTuning',
    'table',            '_MifHandlerTable',
    'row',              '_MifHandlerRow',
    'cell',             '_MifHandlerCell',
    'endtable',         '_MifHandlerEndTable',
    'import',           '_MifHandlerImport',
    'inline',           '_MifHandlerInline',
    'output',           '_MifHandlerOutput',
    'object',           '_MifHandlerObject',
);

# Phrase directive mapping table
%_MIF_PHRASE_HANDLER = (
    'char',             '_MifPhraseHandlerChar',
    'import',           '_MifPhraseHandlerImport',
    'inline',           '_MifPhraseHandlerInline',
    'variable',         '_MifPhraseHandlerVariable',
    'xref',             '_MifPhraseHandlerXRef',
    'pagenum',          '_MifPhraseHandlerPageNum',
    'pagecount',        '_MifPhraseHandlerPageCount',
    'paratext',         '_MifPhraseHandlerParaText',
    'paranum',          '_MifPhraseHandlerParaNum',
    'paranumonly',      '_MifPhraseHandlerParaNumOnly',
    'parashort',        '_MifPhraseHandlerParaShort',
    'paralast',         '_MifPhraseHandlerParaLast',
);

# Table states
$_MIF_INTABLE = 1;
$_MIF_INROW   = 2;
$_MIF_INCELL  = 3;

# Table row suffixes
%_MIF_ROW_SUFFIX = (
    'Heading',  'H',
    'Body',     'Body',
    'Group',    'Body',
    'Footing',  'F',
);

# Parts in a book before numbering starts resetting
%_MIF_FRONT_PART = (
    'front',        1,
    'pretoc',       1,
    'toc',          1,
    'lof',          1,
    'lot',          1,
    'prechapter',   1,
);

##### Variables #####

# Counter to ensure stream processing functions are re-entrant
$_mif_cnt = 0;

# The current template stuff
@_mif_template = ();
%_mif_tpl_vars = ();
%_mif_tpl_xrefs = ();
%_mif_tpl_paras = ();
%_mif_tpl_fonts = ();
%_mif_tpl_tbls = ();
%_mif_tpl_ctrls = ();

# The current variables, cross-references, paragraph/font/table catalogs,
# control settings, reference frames and generated lists
%_mif_vars = ();
%_mif_xrefs = ();
%_mif_paras = ();
%_mif_fonts = ();
%_mif_tbls = ();
%_mif_ctrls = ();
%_mif_frames = ();
%_mif_lists = ();
%_mif_indexes = ();

# Counter of Running H/F variables used
$_mif_runninghf_cnt = 0;

# Style usage counters. We don't bother keeping usage counts for
# font styles because they are small to build and are referenced
# in lots of places (e.g. autonumber fonts).
%_mif_parastyle_used = ();
%_mif_tblstyle_used = ();

# The cover page name and rectangles
$_mif_cover = '';
%_mif_cover_rect = ();

# Buffers for collection of special objects
@_mif_toc_list = ();
@_mif_lof_list = ();
@_mif_lof_list = ();
@_mif_figure = ();
@_mif_table = ();
@_mif_textflows = ();
@_mif_pages = ();
$_mif_bodypage = '';

# Stacks for tables
@_mif_tbl_start = ();
@_mif_tbl_state = ();
@_mif_tbl_wide = ();
@_mif_tbl_id = ();
@_mif_tbl_title = ();
@_mif_tbl_style = ();
@_mif_tbl_landscape = ();

# Type of current row
@_mif_row_type = ();

# Alignment of current table cell
$_mif_cell_align = '';
$_mif_cell_valign = '';

# Margin around current cell (and defaults for current table)
$_mif_cell_lmargin = 0;
$_mif_cell_tmargin = 0;
$_mif_cell_rmargin = 0;
$_mif_cell_bmargin = 0;
$_mif_tbl_lmargin = 0;
$_mif_tbl_tmargin = 0;
$_mif_tbl_rmargin = 0;
$_mif_tbl_bmargin = 0;

#
# >>_Description::
# {{Y:_mif_buffered_fname}} and {{Y:_mif_buffered_file}} contain the
# filename and contents of the last album file fetched.
#
$_mif_buffered_fname = '';
@_mif_buffered_file = ();

# Used to ensure text flows are unique
$_mif_textflow_cnt = $_MIF_TEXTFLOW_START;

# Used to ensure cross-reference targets are unique
$_mif_xref_cnt = $_MIF_TOC_XREF_START;

# Arrays of paragraph attribute information
@_mif_paraattr_name = ();
@_mif_paraattr_full = ();
@_mif_paraattr_type = ();

# Root objects for faster catalog building
$_mif_pararoot_name = '';
%_mif_pararoot_attr = ();
$_mif_fontroot_name = '';
%_mif_fontroot_attr = ();
$_mif_tblroot_name = '';
%_mif_tblroot_attr = ();
$_mif_frameroot_name = '';
%_mif_frameroot_attr = ();
$_mif_listroot_name = '';
%_mif_listroot_attr = ();
$_mif_indexroot_name = '';
%_mif_indexroot_attr = ();

# Stacks of component file offsets and filenames
@_mif_component_offset = ();
@_mif_component_file = ();
@_mif_component_type = ();

# Table of component names and types
@_mif_component_tbl = ();

# Counter for building derived component names
$_mif_component_cntr = 0;

# Cursor in component type array
$_mif_component_cursor= 0;

##### Routines #####

#
# >>Description::
# {{Y:MifFormat}} is an SDF driver which outputs MIF.
#
sub MifFormat {
    local(*data) = @_;
    local(@result);
    local($msg_cursor, %msg_counts);

    # Init global variables/buffers
    $_mif_textflow_cnt = $_MIF_TEXTFLOW_START;
    $_mif_xref_cnt = $_MIF_TOC_XREF_START;
    %_mif_vars = ();
    %_mif_xrefs = ();
    %_mif_paras = ();
    %_mif_fonts = ();
    %_mif_tbls = ();
    %_mif_ctrls = ();
    %_mif_frames = ();
    %_mif_lists = ();
    %_mif_indexes = ();
    $_mif_runninghf_cnt = 0;
    %_mif_parastyle_used = ();
    %_mif_tblstyle_used = ();
    $_mif_cover = '';
    %_mif_cover_rect = ();
    @_mif_toc_list = ();
    @_mif_lof_list = ();
    @_mif_lot_list = ();
    @_mif_figure = ();
    @_mif_table = ();
    @_mif_textflows = ();
    @_mif_pages = ();
    $_mif_bodypage = '';
    @_mif_tbl_start = ();
    @_mif_tbl_wide = ();
    @_mif_tbl_state = ();
    @_mif_tbl_id = ();
    @_mif_tbl_title = ();
    @_mif_tbl_style = ();
    @_mif_tbl_landscape = ();
    @_mif_row_type = ();
    @_mif_component_offset = ();
    @_mif_component_file = ();
    @_mif_component_type = ();
    @_mif_component_tbl = ();
    $_mif_component_cntr = 0;
    $_mif_component_cursor = 0;

    # Initialise things for building a book, if necessary
    if ($SDF_USER'var{'MIF_BOOK_MODE'}) {
        @_mif_component_tbl = ('Part|Type');
    }

    # Get the current message cursor - we skip the finalisation stuff
    # if errors are found
    $msg_cursor = &AppMsgNextIndex();

    # Process the paragraphs
    @result = ();
    &_MifAddSection(*result, *data);

    # Save away any unclosed components
    while (@_mif_component_file) {
        &_MifHandlerOutput(*result, '-');
    }

    # Finalise the output, provided that no errors/aborts/fatals were found
    %msg_counts = &AppMsgCounts($msg_cursor);
    if ($msg_counts{'error'} || $msg_counts{'abort'} || $msg_counts{'fatal'} ) {
        # do nothing
    }
    elsif ($SDF_USER'var{'MIF_BOOK_MODE'}) {
        @_mif_component_tbl = &TableParse(@_mif_component_tbl);
        @result = &_MifBookBuild(*_mif_component_tbl, $SDF_USER'var{'DOC_BASE'});
    }
    else {
        @result = &_MifFinalise(*result);
    }

    # Return result
    return @result;
}

#
# >>_Description::
# {{Y:_MifAddSection}} formats a block of SDF (@data) into MIF and
# adds it to a buffer (@outbuf).
#
sub _MifAddSection {
    local(*outbuf, *data) = @_;
#   local();
    local($prev_tag, %prev_attrs);
    local($para_tag, $para_text, %para_attrs);
    local($directive);

    # Process the paragraphs
    $prev_tag = '';
    %prev_attrs = ();
#print "data: ", join("<\n", @data), "<\n" if $mif_debug;
    while (($para_text, $para_tag, %para_attrs) = &SdfNextPara(*data)) {

        # handle directives
        if ($para_tag =~ /^__(\w+)$/) {
            $directive = $_MIF_HANDLER{$1};
            if (defined &$directive) {
                &$directive(*outbuf, $para_text, %para_attrs);
            }
            else {
                &AppTrace("mif", 5, "ignoring internal directive '$1'");
            }
            next;
        }

        # Add the paragraph
        &_MifParaAdd(*outbuf, $para_tag, $para_text, *para_attrs, $prev_tag,
          *prev_attrs);
    }

    # Do this stuff before starting next loop iteration
    continue {
        $prev_tag = $para_tag;
        %prev_attrs = %para_attrs;
    }
}
       
#
# >>_Description::
# {{Y:_MifEscape}} escapes special characters in a MIF string.
# If {{escape_space}} is true, space characters are also escaped.
#
sub _MifEscape {
    local(*text, $escape_space) = @_;
#   local();
    local($orig_linematch_flag);

    $orig_linematch_flag = $*;
    $* = 1;
    $text =~ s/([\\>])/\\$1/g;
    $text =~ s/\t/\\t/g;
    $text =~ s/'/\\q/g;
    $text =~ s/`/\\Q/g;
    $text =~ s/ /\\ /g if $escape_space;
    $* = $orig_linematch_flag;
}

#
# >>_Description::
# {{Y:_MifFmtMarker}} formats a mif marker.
#
sub _MifFmtMarker {
    local($prefix, $code, $text) = @_;
    local($marker);
    local($rest);

    # For long markers, make each entry a marker until the rest
    # is short enough to fit into one marker
    $marker = '';
    while (length($text) > 255) {
        if ($text =~ /[^\\];/) {
            $rest = $`;
            $text = $';
            &_MifEscape(*rest);
            $marker .=  "$prefix\n" .
                        "$prefix \n" .
                        "$prefix> # end of Marker\n";
        }
        else {
            # If we reach here, we are unable to split the marker text.
            # Therefore, the best we can do is take the first 255 chars
            # and let the user know. :-(
            $rest = substr($text, 255);
            $text = substr($text, 0, 255);
            &AppMsg("warning", "ignoring marker text - '$rest'");
        }
    }

    # Handle the simple case
    &_MifEscape(*text);
    $marker .=  "$prefix\n" .
                "$prefix \n" .
                "$prefix> # end of Marker\n";
    return $marker;
}
       
#
# >>_Description::
# {{Y:_MifParaAdd}} adds a paragraph.
#
sub _MifParaAdd {
    local(*result, $para_tag, $para_text, *para_attrs, $prev_tag, *prev_attrs) = @_;
#   local();
    local($is_example, $para_fmt);
    local($para_override);
    local($para);
    local($hdg_level);
    local($id, $hlpinfo);
    local($index, $index_code);

    # Get the example flag
    $is_example = $SDF_USER'parastyles_category{$para_tag} eq 'example';

    # After headings, use a FIRST tag instead of a normal tag
    if ($prev_tag =~ /^[HAP]\d$/ && $para_tag eq 'N' &&
      $SDF_USER'parastyles_to{'FIRST'} ne '') {
        $para_tag = 'FIRST';
    }

    # Get the Frame format name
    $para_fmt = $SDF_USER'parastyles_to{$para_tag};
    $para_fmt = $para_tag if $para_fmt eq '';
    $para_fmt .= 'NoTOC' if $para_attrs{'notoc'};
    $_mif_parastyle_used{$para_fmt}++;

    # Inherit the alignment and margins from the table cell, if applicable
    if (@_mif_tbl_state) {
        if ($_mif_cell_align ne $para_attrs{'align'}) {
            $para_attrs{'align'} = $_mif_cell_align;
        }
        if ($_mif_cell_valign ne '') {
            $para_attrs{'mif.CellAlignment'} = $_mif_cell_valign;
        }
        # Get the cell margins, if necessary
        if ($_mif_cell_lmargin  ne '' || $_mif_cell_tmargin ne '' ||
            $_mif_cell_rmargin  ne '' || $_mif_cell_bmargin ne '') {
            $_mif_cell_lmargin = $_mif_tbl_lmargin if $_mif_cell_lmargin eq '';
            $_mif_cell_tmargin = $_mif_tbl_tmargin if $_mif_cell_tmargin eq '';
            $_mif_cell_rmargin = $_mif_tbl_rmargin if $_mif_cell_rmargin eq '';
            $_mif_cell_bmargin = $_mif_tbl_bmargin if $_mif_cell_bmargin eq '';
            $para_attrs{'mif.CellMargins'} =
              "${_mif_cell_lmargin}pt ${_mif_cell_tmargin}pt " .
              "${_mif_cell_rmargin}pt ${_mif_cell_bmargin}pt";
            $para_attrs{'mif.CellLMarginFixed'} = 1;
            $para_attrs{'mif.CellTMarginFixed'} = 1;
            $para_attrs{'mif.CellRMarginFixed'} = 1;
            $para_attrs{'mif.CellBMarginFixed'} = 1;
        }
    }

    # Get the format overrides
    &SdfAttrMap(*para_attrs, 'mif', *SDF_USER'paraattrs_to,
      *SDF_USER'paraattrs_map, *SDF_USER'paraattrs_attrs,
      $SDF_USER'parastyles_attrs{$para_tag});
    $para_override = &_MifParaSdfAttr(*para_attrs, "  ");

    # Build the paragraph header
    $para  = "\n";
    if ($para_override ne '') {
        $para .= " \n";
    }
    $para .= " \n" .
             "   \n" .
             "  > # end of Marker\n";
        # And we need this one for cross-references
        $para .= "  \n" .
             "   \n" .
             "  > # end of Marker\n";
        # And this one is for short text within a header/footer
        if ($para_attrs{"short"}) {
            $id = &_MifEscapeNewlink($para_attrs{"short"});
            $para .= "  \n" .
                 "   \n" .
                 "  > # end of Marker\n";
        }
        $id = '';
    }
    for $hlpinfo ('context', 'header', 'topic', 'window', 'endwindow') {
        $id = $para_attrs{"hlp.$hlpinfo"};
        $id = &_MifEscapeNewlink($id);
        if ($id ne '') {
            $para .= "  \n" .
                 "   \n" .
                 "  > # end of Marker\n";
        }
    }

    # If this paragraph is in a generated list, add a cross reference,
    # unless we're in book mode
    unless ($SDF_USER'var{'MIF_BOOK_MODE'}) {
        if ($para_tag =~ /^[HAP](\d)$/) {
            $hdg_level = $1;
            if ($hdg_level <= $SDF_USER'var{'DOC_TOC'} &&
              !$para_attrs{'notoc'}) {
                &_MifAddListXref(*para, $para_fmt, *_mif_toc_list, 'TOC');
            }
        }
        elsif ($para_tag eq 'FT') {
            &_MifAddListXref(*para, $para_fmt, *_mif_lof_list, 'LOF');
        }
        elsif ($para_tag eq 'TT') {
            &_MifAddListXref(*para, $para_fmt, *_mif_lot_list, 'LOT');
        }
    }

    # Process index-related attributes
    $index = $para_attrs{"index"};
    if ($index) {
        $index_code = $para_attrs{"index_type"};
        if ($index_code eq '') {
            $index_code = 2;
        }
        elsif ($_MIF_INDEX_CODE{$index_code}) {
            $index_code = $_MIF_INDEX_CODE{$index_code};
        }
        elsif ($index_code !~ /^\d+/) {
            &AppMsg("warning", "unknown index type '$index_code' - assuming standard");
            $index_code = 2;
        }
        $para .= &_MifFmtMarker("  ", $index_code, $index);
    }

    # Indent examples, if necessary
    if ($is_example && $para_attrs{'in'}) {
        $para_text = " " x ($para_attrs{'in'} * 4) . $para_text;
        delete $para_attrs{'in'};
    }

    # Add the paragraph body
    if ($para_attrs{'verbatim'}) {
        delete $para_attrs{'verbatim'};
        &_MifEscape(*para_text, $is_example);
        $para .= "  \n";
    }
    else {
        $para .= &_MifParaText($para_text, $is_example);
    }

    # Build result
    if ($is_example && $para_tag eq $prev_tag &&
      join('', %para_attrs) eq join('', %prev_attrs)) {
        &_MifParaAppend(*result, $para);
    }
    else {
        push(@result, $para . $_MIF_PARA_END);
    }
}

#
# >>_Description::
# {{Y:_MifAddListXref}} adds a paragraph to a generated list.
#
sub _MifAddListXref {
    local(*para, $para_fmt, *list, $list_type) = @_;
#   local();

    # Add the xref destination marker
    $para .=
         "  \n" .
         "   \n" .
         "  > # end of Marker\n";

    # And a special marker for HLP format
    $para .= "  \n" .
         "   \n" .
         "  > # end of Marker\n";

    # Add the xref to the global list
    $_mif_parastyle_used{"$para_fmt$list_type"}++;
    push(@list,
        "\n" .
        " \n" .
        "   \n" .
        "  > # end of XRef\n" .
        " >\n" .
        "> # end of Para");

    # Update the global xref counter (which makes xref unique)
    $_mif_xref_cnt++;
}
       
#
# >>_Description::
# {{Y:_MifInitTemplate}} initialises the global template variables.
#
sub _MifInitTemplate {
#   local() = @_;
#   local();

    @_mif_template = ();
    %_mif_tpl_paras = ();
    %_mif_tpl_fonts = ();
    %_mif_tpl_vars = ();
    %_mif_tpl_xrefs = ();
    %_mif_tpl_tbls = ();
    %_mif_tpl_ctrls = ();
}
       
#
# >>_Description::
# {{Y:_MifFetchTemplate}} loads a MIF template.
# The following global variables are updated:
#
# * @_mif_template - each element contains one and only one main MIF object
# * %_mif_tpl_vars - the set of variables
# * %_mif_tpl_xrefs - the set of cross references
# * %_mif_tpl_paras - the paragraph catalog
# * %_mif_tpl_fonts - the font catalog
# * %_mif_tpl_tbls - the table catalog (soon)
# * %_mif_tpl_ctrls - the document control settings
#
sub _MifFetchTemplate {
    local($template_file) = @_;
    local($ok);
    local($strm, @rec);

    # Open the input stream
    $strm = sprintf("mif_s%d", $_mif_cnt++);
    open($strm, $template_file) || return 0;

    # Read the data. Objects taking a whole line get a record to
    # themselves. A slight variation of this is needed to cover the
    #  opening  line as it often has a trailing comment.
    #. Otherwise, we use a > at the start of a line to detect
    # the end of objects.
    line:
    while (<$strm>) {
        next line if /^#/;
        chop;
        if (/^\<.*\>$/ || /^\<.*\>\s*\#/) {
            push(@_mif_template, $_);
        }
        else {
            push(@rec, $_); 
            if (/^\>/) {
                $text = join("\n", @rec);
                push(@_mif_template, $text);
                if ($rec[0] =~ /^\text: %d seconds\n", time - $igc_start;
                }
                elsif ($rec[0] =~ /^\>_Description::
# {{Y:_MifFetchAlbum}} handles fetching of album files.
#
sub _MifFetchAlbum {
    local($fname) = @_;
    local($ok, @file);
    local($strm);

    # Check if the file is buffered
    if ($fname eq $_mif_buffered_fname) {
        return (1, @_mif_buffered_file);
    }

    # Fetch the file
    $strm = sprintf("mif_s%d", $_mif_cnt++);
    $ok = open($strm, $fname);
    if ($ok) {
        @file = <$strm>;
        chop(@file);
        close($strm);
    }

    # Buffer the file
    $_mif_buffered_fname = $fname;
    @_mif_buffered_file = @file;

    # Return result
    return ($ok, @file);
}

#
# >>_Description::
# {{Y:_MifVarsFromText}} converts text records (@recs)
# that represent variable declarations in a MIF file to
# a set of name value pairs.
#
sub _MifVarsFromText {
    local(*recs) = @_;
    local(%vars);
    local($line);
    local($name, $value);

    for $line (@recs) {
        if ($line =~ /VariableName\s+`(.+)'\>/) {
            $name = $1;
        }
        elsif ($line =~ /VariableDef\s+`(.+)'\>/) {
            $value = $1;
            $value =~ s/\\q/'/g;
            $value =~ s/\\Q/`/g;
            $value =~ s/\\t/\t/g;
            $value =~ s/\\([\\\>])/$1/g;
            $vars{$name} = $value;
        }
    }

    # Return result
    return %vars;
}

#
# >>_Description::
# {{Y:_MifVarsToText}} converts {{%vars}} to the text string
# that represents those declarations in a MIF file.
#
sub _MifVarsToText {
    local(*vars) = @_;
    local($text);
    local($var, $value);

    # Build the result
    $text = "\n" .
             "  \n" .
             " > # end of VariableFormat\n";
    }
    $text .= "> # end of VariableFormats";

    # Return result
    return $text;
}

#
# >>_Description::
# {{Y:_MifXRefsFromText}} converts text records (@recs)
# that represent cross-reference declarations in a MIF file to
# a set of name value pairs.
#
sub _MifXRefsFromText {
    local(*recs) = @_;
    local(%xrefs);
    local($line);
    local($name, $value);

    for $line (@recs) {
        if ($line =~ /XRefName\s+`(.+)'\>/) {
            $name = $1;
        }
        elsif ($line =~ /XRefDef\s+`(.+)'\>/) {
            $value = $1;
            $xrefs{$name} = $value;
        }
    }

    # Return result
    return %xrefs;
}

#
# >>_Description::
# {{Y:_MifXRefsToText}} converts {{%xrefs}} to the text string
# that represents those declarations in a MIF file.
#
sub _MifXRefsToText {
    local(*xrefs) = @_;
    local($text);
    local($xref, $value);

    # Build the result
    $text = "\n" .
             "  \n" .
             " > # end of XRefFormat\n";
    }
    $text .= "> # end of XRefFormats";

    # Return result
    return $text;
}

#
# >>_Description::
# {{Y:_MifParasFromText}} converts text records (@recs) that represent
# paragraph definitions in a MIF file to a set of name value pairs.
# Use {{Y:_MifAttrSplit}} and {{Y:_MifAttrSplit}} to convert
# the value to and from an associative array.
#
sub _MifParasFromText {
    local(*recs) = @_;
    local(%result);
    local($line);
    local($name, %values);
    local($in_font, $in_tabstop, %tab, $tab);
    local($atname, $atvalue);

    $in_font = 0;
    $in_tabstop = 0;
    for $line (@recs) {
        $line =~ s/^\s+//;
        $line =~ s/\s+$//;
        if ($line =~ /^\$/) {
            $name = $1;
            %values = ();
        }
        elsif ($line =~ /^\<(\w+)\s+(.+)\>$/) {
            $atname = $1;
            $atvalue = &_MifAttrToText($2);
            if ($in_tabstop) {
                $tab{$atname} = $atvalue;
            }
            elsif($in_font) {
                $values{'Font' . substr($atname, 1)} = $atvalue;
            }
            else {
                $atname =~ s/^Pgf//;
                $values{$atname} = $atvalue;
            }
        }
        elsif ($line =~ /^\> # end of Pgf$/) {
            # Finalise the set of attributes
            delete $values{'FontTag'};
            delete $values{'FontPostScriptName'};
            delete $values{'NumTabs'};
            $values{'TabStop'} = '' unless defined($values{'TabStop'});

            # Store the attributes for this paragraph format
            $result{$name} = &_MifAttrJoin(*values);
        }
        elsif ($line =~ /^ # end of PgfFont$/) {
            $in_font = 0;
        }
        elsif ($line =~ /^ # end of TabStop$/) {
            $in_tabstop = 0;
            $tab{'TSType'}      = '' if $tab{'TSType'} eq 'Left';
            $tab{'TSLeaderStr'} = '' if $tab{'TSLeaderStr'} eq ' ';
            $tab = join('/', @tab{'TSX', 'TSType', 'TSLeaderStr'});
            $tab =~ s/\/+$//;
            if (defined($values{'TabStop'})) {
                $values{'TabStop'} .= "," . $tab;
                next;
            }
            $values{'TabStop'} = $tab;
        }
    }

    # Return result
    return %result;
}

#
# >>_Description::
# {{Y:_MifParasToText}} converts {{%paras}} to the text string
# that represents those declarations in a MIF file.
#
sub _MifParasToText {
    local(*paras) = @_;
    local($text);
    local(@styles);
    local($name, %attr);

    # Build the attribute information arrays
    &_MifBuildAttrInfo();

    # Decide on the styles to output
    @styles = $SDF_USER'var{'MIF_ALL_STYLES'} ? sort keys %paras :
                sort keys %_mif_parastyle_used;

    # Build the result
    $text = "\n",
             &_MifParaMifAttr(*attr, '  '),
             " > # end of Pgf\n");
    }
    $text .= "> # end of PgfCatalog";

    # Return result
    return $text;
}

#
# >>_Description::
# {{Y:_MifFontsFromText}} converts text records (@recs) that represent
# font definitions in a MIF file to a set of name value pairs.
# Use {{Y:_MifAttrJoin}} and {{Y:_MifAttrSplit}} to convert
# the value to and from an associative array.
#
sub _MifFontsFromText {
    local(*recs) = @_;
    local(%result);
    local($line);
    local($name, %values);

    for $line (@recs) {
        $line =~ s/^\s+//;
        $line =~ s/\s+$//;
        if ($line =~ /^$/) {
            $name = $1;
            %values = ();
        }
        elsif ($line =~ /^$/) {
            $values{$1} = &_MifAttrToText($2);
        }
        elsif ($line =~ /^\> # end of Font$/) {
            delete $values{'PostScriptName'};
            $result{$name} = &_MifAttrJoin(*values);
        }
    }

    # Return result
    return %result;
}

#
# >>_Description::
# {{Y:_MifFontsToText}} converts {{%fonts}} to the text string
# that represents those declarations in a MIF file.
#
sub _MifFontsToText {
    local(*fonts) = @_;
    local($text);
    local($name, %attr);

    # Build the result
    $text = ">_Description::
# {{Y:_MifTblsFromText}} converts text records (@recs) that represent
# table format definitions in a MIF file to a set of name value pairs.
# Use {{Y:_MifAttrJoin}} and {{Y:_MifAttrSplit}} to convert
# the value to and from an associative array.
#
sub _MifTblsFromText {
    local(*recs) = @_;
    local(%result);
    local($line);
    local($name, %values);

    for $line (@recs) {
        $line =~ s/^\s+//;
        $line =~ s/\s+$//;
        if ($line =~ /^$/) {
            $name = $1;
            %values = ();
            $nested = 0;
        }
        elsif ($line =~ /^$/) {
            $values{$1} = &_MifAttrToText($2) unless $nested;
        }
        elsif ($line =~ /^ # end of Tbl(Column|TitlePgf1)$/) {
            $nested = 0;
        }
        elsif ($line =~ /^\> # end of TblFormat$/) {
            $result{$name} = &_MifAttrJoin(*values);
        }
    }

    # Return result
    return %result;
}

#
# >>_Description::
# {{Y:_MifTblsToText}} converts {{%tbls}} to the text string
# that represents those declarations in a MIF file.
#
sub _MifTblsToText {
    local(*tbls) = @_;
    local($text);
    local(@styles);
    local($name, %attr);

    # Decide on the styles to output
    @styles = $SDF_USER'var{'MIF_ALL_STYLES'} ? sort keys %tbls :
                sort keys %_mif_tblstyle_used;

    # Build the result
    $text = ">_Description::
# {{Y:_MifTblFormat}} formats a table format name and
# set of attributes (%attr) into MIF.
# {{prefix}} is a string of spaces to put at the front of each line.
#
sub _MifTblFormat {
    local($name, $prefix, *attr) = @_;
#   local($result);
    local(@text);
    local($id, $type, $value);

    # Build the header
    @text = ("$prefix");

    # Add the attributes
    for $id (sort keys %attr) {
        $type = $SDF_USER'tableparams_type{"mif.$id"};
        $value = &_MifAttrFromText($attr{$id}, $type);
        push(@text, " ");
    }

    # Add a dummy table column
    push(@text,
        " ",
        "  ",
        "  ",
        "  > # end of TblColumnH",
        "  ",
        "  > # end of TblColumnBody",
        "  ",
        "  > # end of TblColumnF",
        " > # end of TblColumn");

    # Add the footer
    push(@text, "> # end of TblFormat\n");

    # Return result
    return join("\n$prefix", @text);
}

#
# >>_Description::
# {{Y:_MifCtrlsFromText}} converts text records (@recs) that represent
# document contorl settings in a MIF file to a set of name value pairs.
#
sub _MifCtrlsFromText {
    local(*recs) = @_;
    local(%result);
    local($line);

    for $line (@recs) {
        $line =~ s/^\s+//;
        $line =~ s/\s+$//;
        if ($line =~ /^<(\w+)\s+(.+)\>$/) {
            $result{$1} = &_MifAttrToText($2);
        }
    }

    # Return result
    return %result;
}

#
# >>_Description::
# {{Y:_MifCtrlsToText}} converts {{%ctrls}} to the text string
# that represents those settings in a MIF file.
#
sub _MifCtrlsToText {
    local(*ctrls) = @_;
    local($text);
    local($name, $var_name, $type, $value);

    # Build the result
    $text = ">_Description::
# {{Y:_MifAttrSplit}} split a string of attributes into an associative array.
# The string format is a null-separated list of "name=value" strings.
#
sub _MifAttrSplit {
    local($str) = @_;
    local(%attr);
    local($nv);

    for $nv (split(/\000/, $str)) {
        $nv =~ /\=/;
        $attr{$`} = $';
    }

    # Return result
    %attr;
}

#
# >>_Description::
# {{Y:_MifAttrJoin}} joins an associative array into a string of attributes.
# (A "reference" to the array is passed for performance.)
# The string format is a null-separated list of "name=value" strings.
#
sub _MifAttrJoin {
    local(*attr) = @_;
    local($str);
    local($name, $value);

    # Build the string
    $str .= "$name=$value\000" while ($name, $value) = each %attr;

    # Return result
    $str;
}

#
# >>_Description::
# {{Y:_MifAttrToText}} formats a MIF attribute into text.
# As this routine can have a major impact on performance,
# the implementation favors performance over readability.
#
sub _MifAttrToText {
    local($mif) = @_;
#   local($text);

    # Trim leading/trailing whitespace
    $mif =~ s/^\s+//;
    $mif =~ s/\s+$//;

    # Convert boolean values to numeric
    $mif = 0 if $mif eq 'No';

    # Trim surrounding quotes, if any
    $mif =~ s/^\`(.*)\'$/$1/;

    # Return result
    $mif;
}

#
# >>_Description::
# {{Y:_MifAttrFromText}} formats an attribute into MIF.
# {{type}} can be one of the following:
#
# * {{boolean}} - output is Yes or No
# * {{string}} - output is `data'
# * {{tabstop}} - output is a tabstop record
# * {{keyword}} - output has a trailing space (matches MIF conventions)
#
# Other types return the value as it is. If the type is unknown:
#
# * 0 is converted to No
# * other values are returned as is.
#
# This algorithm minimises the problems associated with unknown attributes.
#
# As this routine can have a major impact on performance,
# the implementation favors performance over readability.
#
sub _MifAttrFromText {
    local($value, $type) = @_;
#   local($text);

    # Handle special cases
    return $value ? 'Yes ' : 'No '  if $type =~ /^b/;   # boolean
    return "`$value'"               if $type =~ /^s/;   # string
    return "$value "                if $type =~ /^k/;   # keyword
    return &_MifTabFromText($value) if $type =~ /^t/;   # tabstop
    return $value                   if $type =~ /^\w/;  # other

    # Otherwise, return the value as is, or No
    return $value eq '0' ? 'No ' : $value;
}

#
# >>_Description::
# {{Y:_MifTabFromText}} formats a tabstop attribute into MIF.
#
sub _MifTabFromText {
    local($value) = @_;
    local($text);
    local(@tabs, $tab, $tsx, $tstype, $tsleader);

    @tabs = split(/\s*,\s*/, $value);
    $text = '';
    for $tab (@tabs) {
        $text .= ">\n  >_Description::
# {{Y:_MifParaSdfAttr}} formats a set of SDF paragraph attributes into MIF.
# {{prefix}} is a string of spaces to put at the front of each line.
#
sub _MifParaSdfAttr {
    local(*attrs, $prefix) = @_;
    local($mif);
    local($attr, $value, $type, $fm_prefix, $font);

    for $attr (sort keys %attrs) {

        # get the attribute value & type
        $value = $attrs{$attr};
        $type = $SDF_USER'paraattrs_type{$attr};

        # Get the Frame prefix
        $fm_prefix = $SDF_USER'phraseattrs_name{$attr} ? 'F' : 'Pgf';

        # Check it's a Frame attribute 
        next unless $attr =~ s/^mif\.//;

        # Map to the MIF name
        $attr = "$fm_prefix$attr" unless
          ($attr =~ /^HyphenM/ || $attr eq 'TabStop');

        # format the value
        $value = &_MifAttrFromText($value, $type);

        # build the result, separating the font attributes for now
        if ($fm_prefix eq 'F') {
             $font .= "$prefix <$attr $value>\n";
        }
        else {
            $mif .= "$prefix<$attr $value>\n";
        }
    }

    # Combine normal and font attributes
    $mif .= "$prefix\n$font$prefix>\n" if $font;

    # Return result
    $mif;
}

#
# >>_Description::
# {{Y:_MifBuildAttrInfo}} builds the table of paragraph attribute
# information. Each record contains the the attribute name & type,
# separated by a NULL character.
#
sub _MifBuildAttrInfo {
#   local() = @_;
#   local();
    local($name, $short_name, $new_name);

    # If the work has already been done, don't bother doing it again
    return if @_mif_paraattr_name;

    # Add the attribute information
    for $name (sort keys %SDF_USER'paraattrs_type) {
        next unless $name =~ /^mif\./;

        # Skip attributes we don't weant to output
        next if $name eq 'mif.NumTabs';
        next if $name eq 'mif.component';

        # Convert the name
        $short_name = $name;
        $short_name =~ s/^mif\.//;
        if ($short_name =~ /^Font/) {
            $new_name = "F" . $';
        }
        elsif ($short_name =~ /^HyphenM|^TabS/) {
            $new_name = $short_name;
        }
        else {
            $new_name = "Pgf" . $short_name;
        }

        # Store the information
        push(@_mif_paraattr_name, $short_name);
        push(@_mif_paraattr_full, $new_name);
        push(@_mif_paraattr_type, $SDF_USER'paraattrs_type{$name});
    }
}

#
# >>_Description::
# {{Y:_MifParaMifAttr}} formats a set of MIF paragraph attributes into MIF.
# {{prefix}} is a string of spaces to put at the front of each line.
#
sub _MifParaMifAttr {
    local(*attrs, $prefix) = @_;
    local($mif);
    local($i, $attr, $value, $fullname, $type, $font);

    # This routine has a big impact on performance, so we
    # get the list of names from a prebuilt array, rather than by
    # sorting the keys of %attrs. Likewise, the fullname and type
    # come from prebuilt arrays, rather than from assocative arrays
    # indexed on attribute name, to improve performance.
    for ($i = 0; $i <= $#_mif_paraattr_name; $i++) {

        # get the attribute information
        $attr     = $_mif_paraattr_name[$i];
        $fullname = $_mif_paraattr_full[$i];
        $type     = $_mif_paraattr_type[$i];

        # format the value
        $value = &_MifAttrFromText($attrs{$attr}, $type);

        # build the result, separating the font attributes for now
        # and ignoring empty tab stops
        ## Note that we explicitly test for the most common case first
        ## in order to improve performance.
        #if ($fullname =~ /^P/) {
        #    $mif .= "$prefix<$fullname $value>\n";
        #}
        #elsif ($fullname =~ /^F/) {
        if ($fullname =~ /^F/) {
             $font .= "$prefix <$fullname $value>\n";
        }
        elsif ($fullname =~ /^T/ && $value eq '') {
            next;
        }
        else {
            $mif .= "$prefix<$fullname $value>\n";
        }
    }

    # Combine normal and font attributes
    $mif .= "$prefix\n$font$prefix>\n" if $font;

    # Return result
    $mif;
}

#
# >>_Description::
# {{Y:_MifFontFormat}} formats a MIF font specification from a
# tag and set of MIF attributes.
#
sub _MifFontFormat {
    local($tag, $prefix, %attr) = @_;
    local($mif);
    local($attr);
    local($short_name);
    local($type, $value);

    # Init things
    $mif = "$prefix\n";

    # Process the attributes
    for $attr (sort keys %attr) {

        # Get the short name
        $short_name = $attr;
        $short_name =~ s/^mif\.//;

        # get the attribute type and value
        $type = $SDF_USER'phraseattrs_type{"mif.$short_name"};
        $value = $attr{$attr};

        # For MIF font definitions, an empty value implies "as-is"
        # and as-is attributes are not including in the definition
        next if $value eq '';

        # format the value
        $value = &_MifAttrFromText($value, $type);

        # build the result
        $mif .= "$prefix \n";
    }
    $mif .= "$prefix>\n";

    # Return result
    return $mif;
}

#
# >>_Description::
# {{Y:_MifCharFont}} formats a MIF font specification from a
# tag and set of SDF attributes.
#
sub _MifCharFont {
    local($tag, $prefix, %attr) = @_;
    local($mif);
    local($attr);
    local($type, $value);

    # Init things
    $mif = "$prefix\n";

    # Process the attributes
    for $attr (sort keys %attr) {

        # get the attribute type and value
        $type = $SDF_USER'phraseattrs_type{$attr};
        $value = $attr{$attr};

        # Check it's a Frame attribute and map it to a MIF name
        next unless $attr =~ s/^mif\./F/;

        # format the value
        $value = &_MifAttrFromText($value, $type);

        # build the result
        $mif .= "$prefix <$attr $value>\n";
    }
    $mif .= "$prefix>\n";

    # Return result
    return $mif;
}

#
# >>_Description::
# {{Y:_MifParaText}} converts SDF text into MIF "paragraph lines".
# 
sub _MifParaText {
    local($para_text, $is_example) = @_;
    local($para);
    local($state);
    local($sect_type, $char_tag, $text, %sect_attrs);
    local(@char_fonts);
    local($char_font, $id, $index, $index_code);
    local($directive);

    # Handle blank lines
    $para_text = " " if $para_text eq '';

    # Process the text
    $para = '';
    while (($sect_type, $text, $char_tag, %sect_attrs) =
      &SdfNextSection(*para_text, *state)) {

        # Escape any special characters
        if ($sect_type eq 'phrase') {
            ($text) = &SDF_USER'ExpandLink($text) if $char_tag eq 'L';
            &_MifEscape(*text, $is_example);
        }
        elsif ($sect_type eq 'string') {
            &_MifEscape(*text, $is_example);
        }

        # Build the paragraph
        if ($sect_type eq 'string') {
            # Convert hyphens to hard-hyphens, if in a phrase
            $text =~ s/\-/\\x15 /g if @char_fonts;

            $para .= "  \n";
        }

        elsif ($sect_type eq 'phrase') {

            # Map colors to safe values
            if ($sect_attrs{'color'} ne '') {
                my $color = &_MifMapColor($sect_attrs{'color'});
                if ($color ne '') {
                    $sect_attrs{'color'} = $color;
                }
                else {
                    delete $sect_attrs{'color'};
                }
            }

            # Process formatting attributes
            &SdfAttrMap(*sect_attrs, 'mif', *SDF_USER'phraseattrs_to,
              *SDF_USER'phraseattrs_map, *SDF_USER'phraseattrs_attrs,
              $SDF_USER'phrasestyles_attrs{$char_tag});
            $char_font = &_MifCharFont($SDF_USER'phrasestyles_to{$char_tag}, "  ",
              %sect_attrs);
            push(@char_fonts, $char_font);
            $para .= $char_font;

            # Process hypertext-related attributes
            $id = &_MifEscapeNewlink($sect_attrs{"id"});
            if ($id) {
                # We need this one for hypertext
                $para .= "  \n" .
                    "   \n" .
                    "  > # end of Marker\n";
                # And we need this one for cross-references
                $para .= "  \n" .
                    "   \n" .
                    "  > # end of Marker\n";
            }
            &_MifAddLink(*para, $sect_attrs{'jump'});
            $id = &_MifEscapeNewlink($sect_attrs{"hlp.popup"});
            if ($id ne '') {
                $para .= "  \n" .
                     "   \n" .
                     "  > # end of Marker\n";
            }

            # Process index-related attributes
            $index = $sect_attrs{"index"};
            if ($index) {
                $index_code = $sect_attrs{"index_type"};
                if ($index_code eq '') {
                    $index_code = 2;
                }
                elsif ($_MIF_INDEX_CODE{$index_code}) {
                    $index_code = $_MIF_INDEX_CODE{$index_code};
                }
                elsif ($index_code !~ /^\d+/) {
                    &AppMsg("warning", "unknown index type '$index_code' - assuming standard");
                    $index_code = 2;
                }
                $para .= &_MifFmtMarker("  ", $index_code, $index);
            }

            # Convert hyphens to hard-hyphens
            $text =~ s/\-/\\x15 /g;

            # Convert spaces to non-breaking spaces, if necessary
            $text =~ s/ /\\x11 /g if $char_tag eq 'S';

            # Add the text for this phrase
            $para .= "  \n";
        }

        elsif ($sect_type eq 'phrase_end') {
            pop(@char_fonts);
            $char_font = $char_fonts[$#char_fonts];
            $para .= $char_font ne '' ? $char_font :
			  "  \n  > # end of Font\n";
        }

        elsif ($sect_type eq 'special') {
            $directive = $_MIF_PHRASE_HANDLER{$char_tag};
            if (defined &$directive) {
                &$directive(*para, $text, %sect_attrs);
            }
            else {
                &AppMsg("warning", "ignoring special phrase '$1' in MIF driver");
            }
        }
    }

    # Return result
    return $para;
}

#
# >>_Description::
# {{Y:_MifMapColor}} maps Web (CSS) colors to MIF colors.
#
sub _MifMapColor {
    local($color) = @_;
    local($mif_color);

    # Ignore leading # on rrggbb value, if any
    $color =~ s/^#//;

    # For now, if it's not in the lookup table, ignore it
    $mif_color = $_MIF_COLOR{"\L$color"};

    # Return result
    return $mif_color;
}

#
# >>_Description::
# {{Y:_MifAddLink}} adds link information for a paragraph.
#
sub _MifAddLink {
    local(*para, $link) = @_;
#   local();

    if ($link) {
        $link = &_MifLink($link, $SDF_USER'var{'MIF_EXT'});
        $para .= "  \n" .
            "   \n" .
            "  > # end of Marker\n";
    }
}

#
# >>_Description::
# {{Y:_MifFinalise}} generates a MIF file.
# If a template has been loaded, the result is a merge of the buffered
# MIF objects with the current template. Otherwise, the output is the
# buffered MIF objects prepended onto the text records. (In the latter
# case, the generated MIF must be imported into a template to produce
# the final document.) If the output is a component in a book,
# {{component_type}} should be set accordingly (e.g. FRONT, TOC,
# CHAPTER, etc.)
#
sub _MifFinalise {
    local(*text, $component_type) = @_;
    local(@out_result);
    local($pwidth, $pheight);
    local($component_prefix);
    local(%offset, $old_match_rule);
    local(%merged_ctrls, %merged_vars, %merged_xrefs);
    local(%merged_paras, %merged_fonts, %merged_tbls);
    local($mainflow);

    # Process document control settings
    &_MifProcessControls(*SDF_USER'var, $component_type);

    # Get the page width and height
    $pwidth = $SDF_USER'var{'DOC_PAGE_WIDTH'};
    $pheight = $SDF_USER'var{'DOC_PAGE_HEIGHT'};

    # Generate the master pages
    $component_prefix = $component_type eq '' ? '' : $component_type . "_";
    &_MifAddMasterPage('First', $component_prefix . "FIRST", $pwidth, $pheight,
      $_MIF_TEXTFLOW_MAIN);
    &_MifAddMasterPage('Right', $component_prefix . "RIGHT", $pwidth, $pheight);
    if ($SDF_USER'var{'DOC_TWO_SIDES'}) {
        &_MifAddMasterPage('Left', $component_prefix . "LEFT", $pwidth, $pheight);
    }

    # Generate the reference pages
    &_MifAddRefPages($component_type);

    # Add the generated lists (Table of Contents, etc.) unless this is
    # a part of a book
    &_MifAddLists(*text) if $component_type eq '';

    #
    # Build the import table. Note that each record in the
    # import table contains a single MIF main statement.
    # As we go, we also build an offset table which is
    # required by MifMerge so it can merge the import
    # table with the nominated template.
    #       
    @out_result = ("");
    if (%_mif_ctrls) {
        %merged_ctrls = %_mif_tpl_ctrls;
        @merged_ctrls{keys %_mif_ctrls} = values %_mif_ctrls;
        push(@out_result, &_MifCtrlsToText(*merged_ctrls));
        $offset{'Document'} = $#out_result;
    }
    if (%_mif_vars) {
        %merged_vars = %_mif_tpl_vars;
        @merged_vars{keys %_mif_vars} = values %_mif_vars;
        push(@out_result, &_MifVarsToText(*merged_vars));
        $offset{'VariableFormats'} = $#out_result;
    }
    if (%_mif_xrefs) {
        %merged_xrefs = %_mif_tpl_xrefs;
        @merged_xrefs{keys %_mif_xrefs} = values %_mif_xrefs;
        push(@out_result, &_MifXRefsToText(*merged_xrefs));
        $offset{'XRefFormats'} = $#out_result;
    }
    if (%_mif_paras) {
$igc_start = time;
        %merged_paras = %_mif_tpl_paras;
        @merged_paras{keys %_mif_paras} = values %_mif_paras;
        push(@out_result, &_MifParasToText(*merged_paras));
#printf STDERR "text->para: %d seconds\n", time - $igc_start;
        $offset{'PgfCatalog'} = $#out_result;
    }
    if (%_mif_fonts) {
$igc_start = time;
        %merged_fonts = %_mif_tpl_fonts;
        @merged_fonts{keys %_mif_fonts} = values %_mif_fonts;
        push(@out_result, &_MifFontsToText(*merged_fonts));
#printf STDERR "text->font: %d seconds\n", time - $igc_start;
        $offset{'FontCatalog'} = $#out_result;
    }
    if (%_mif_tbls) {
$igc_start = time;
        %merged_tbls = %_mif_tpl_tbls;
        @merged_tbls{keys %_mif_tbls} = values %_mif_tbls;
        push(@out_result, &_MifTblsToText(*merged_tbls));
#printf STDERR "text->tbl: %d seconds\n", time - $igc_start;
        $offset{'TblCatalog'} = $#out_result;
    }
    if (@_mif_figure) {
        push(@out_result, join("\n",
          ' # end of AFrames'
        ));
        $offset{'AFrames'} = $#out_result;
    }
    if (@_mif_table) {
        push(@out_result, join("\n",
          ' # end of Tbls'
        ));
        $offset{'Tbls'} = $#out_result;
    }
    if (@_mif_pages) {
        push(@out_result, join("\n", @_mif_pages, $_mif_bodypage));
        $offset{'Page'} = $#out_result;
    }

    # Build the main text flow:
    # * add the header
    # * patch in the TextRect ID for the main flow
    # * ensure that nested lines are indented
    # * add the footer.
    $mainflow = join("\n",
        "",
        "",
        "",
        "",
        "",
        "",
        " # end of Notes",
        @text);
    $old_match_rule = $*;
    $* = 1;
    $mainflow =~ s/\/;
    $mainflow =~ s/\n/\n /g;
    $mainflow .= "\n> # end of TextFlow";
    $* = $old_match_rule;

    # Add the text flows to the  import table
    push(@out_result, join("\n", @_mif_textflows, $mainflow));
    $offset{'TextFlow'} = $#out_result;

    # If we're building a book, reset the buffers ready for the next part
    if ($component_type ne '') {
        @_mif_figure = ();
        @_mif_table = ();
        @_mif_pages = ();
        @_mif_textflows = ();
    }

    # Merge with the current template, if necessary
    if (scalar(@_mif_template) > 0) {
        @out_result = &_MifMerge(*_mif_template, *out_result, %offset);
    }

    # Return result
    push(@out_result, "# End of MIFFile");
    return @out_result;
}

#
# >>_Description::
# {{Y:_MifProcessControls}} checks the document control variables
# and sets the MIF control settings appropriately.
#
sub _MifProcessControls {
    local(*vars, $component_type) = @_;
#   local();
    local($page_size, $page_width, $page_height);
    local($sdf_tag, $mif_tag, $prefix);

    # Set the page size
    $page_size = $sdf_pagesize{$vars{'OPT_PAGE_SIZE'}};
    if ($page_size ne '') {
        ($page_width, $page_height) = split(/\000/, $page_size, 2);
    }
    else {
        # Custom size
        ($page_width, $page_height) = split(/x/, $vars{'OPT_PAGE_SIZE'}, 2);
    }
    $page_width  .= "pt" if $page_width =~ /^[\d\.]+$/;
    $page_width  .= "pt" if $page_width =~ /^[\d\.]+$/;
    $_mif_ctrls{'DPageSize'} = "$page_width $page_height";

    # Set the number of sides
    $_mif_ctrls{'DTwoSides'} = $vars{'DOC_TWO_SIDES'} || $vars{'MIF_TWO_SIDES'};

    # If numbering per section is enabled, adjust the 'Current Page #'
    # variable definition, if necessary
    if ($vars{'MIF_BOOK_MODE'} && $vars{'OPT_NUMBER_PER_COMPONENT'}) {
        $_mif_ctrls{'DPageNumStyle'} = 'Arabic';
        if ($component_type eq 'CHAPTER') {
            $sdf_tag = $vars{'OPT_COMPONENT_COVER'} ? 'H1NUM' : 'H1';
            $mif_tag = $SDF_USER'parastyles_to{$sdf_tag};
            $prefix = "<\$paranumonly[$mif_tag]>";
        }
        elsif ($component_type eq 'APPENDIX') {
            $sdf_tag = $vars{'OPT_COMPONENT_COVER'} ? 'A1NUM' : 'A1';
            $mif_tag = $SDF_USER'parastyles_to{$sdf_tag};
            $prefix = "<\$paranumonly[$mif_tag]>";
        }
        elsif ($component_type eq 'IX') {
            $prefix = "Index";
        }
        elsif (! $_MIF_FRONT_PART{"\L$component_type"}) {
            $prefix = "\u\L$component_type";
        }
        else {
            # Use roman numerals for page numbers of front matter
            $_mif_ctrls{'DPageNumStyle'} = 'LCRoman';
        }
        if ($prefix) {
            $_mif_vars{'Current Page #'} = "$prefix-<\$curpagenum>";
        }
        else {
            $_mif_vars{'Current Page #'} = "<\$curpagenum>";
        }
    }
}

#
# >>_Description::
# {{Y:_MifAddMasterPage}} adds a master page to the internal buffers.
# {{name}} is either Left, Right or a 'user' name.
# (In the latter case, the MIF type is implicitly 'OtherMasterPage'.)
# {{sdf_type}} is the SDF page type (e.g. FIRST, FRONT_RIGHT).
# {{page_width}} and {{page_height}} are the page width and height
# in points.
# The text flows for the header and footer, if any, are added to
# internal buffers used to generate the final document.
# If you want a matching body page for this master page, then set
# {{bodypage_id}} to the id of the TextRect within that body page.
#
sub _MifAddMasterPage {
    local($name, $sdf_type, $page_width, $page_height, $bodypage_id) = @_;
#   local();
    local(@page);
    local($mif_type);
    local($left, $width);
    local($h_top, $h_height);
    local($m_top, $m_height);
    local($f_top, $f_height);
    local($prefix);
    local($sh_width, $sh_gap);
    local($col_count, $col_gap);
    local(@body);
    local(@text, $id);
    local($background);

    # Build the header
    if ($name eq 'Left' || $name eq 'Right') {
        $mif_type = $name . "MasterPage";
    }
    else {
        $mif_type = "OtherMasterPage";
    }
    @page = (
        "",
        " ",
        " ");

    # Calculate the left & width (used by all rectangles on the page)
    $left   = ($name eq 'Left') ? &SdfVarPoints("OPT_MARGIN_OUTER") :
              &SdfVarPoints("OPT_MARGIN_INNER");
    $width  = $page_width - &SdfVarPoints("OPT_MARGIN_OUTER") -
              &SdfVarPoints("OPT_MARGIN_INNER");

    # Calculate the tops and heights
    $h_top    = &SdfVarPoints("OPT_MARGIN_TOP");
    $h_height = &SdfPageInfo($sdf_type, "HEADER_HEIGHT", "pt");
    $f_height = &SdfPageInfo($sdf_type, "FOOTER_HEIGHT", "pt");
    $f_top    = $page_height - $f_height - &SdfVarPoints("OPT_MARGIN_BOTTOM");
    $m_top    = $h_top + $h_height +
                &SdfPageInfo($sdf_type, "HEADER_GAP", "pt");
    $m_height = $f_top - $m_top -
                &SdfPageInfo($sdf_type, "FOOTER_GAP", "pt");

    # Get the sidehead and column details
    $prefix    = $sdf_type =~ /^IX/ ? 'OPT_IX' : 'OPT';
    $sh_width  = &SdfVarPoints("${prefix}_SIDEHEAD_WIDTH");
    $sh_gap    = &SdfVarPoints("${prefix}_SIDEHEAD_GAP");
    $col_count = $SDF_USER'var{"${prefix}_COLUMNS"};
    $col_gap   = &SdfVarPoints("${prefix}_COLUMN_GAP");

    # Add the main section
    @text = ();
    $id = &_MifAddTextFlow(*text, 'A');
    &_MifAddTextArea(*page, $id, $left, $m_top, $width, $m_height,
      $sh_width, $sh_gap, &SdfPageInfo($sdf_type, "MAIN_BORDER"),
      $col_count, $col_gap);
    if ($bodypage_id ne '') {
        @body = (
            "",
            " ");
        &_MifAddTextArea(*body, $bodypage_id, $left, $m_top, $width, $m_height,
          $sh_width, $sh_gap, '', $col_count, $col_gap);
        push(@body, "> # end of Page");
        $_mif_bodypage = join("\n", @body);
    }

    # Add the header, if any
    if ($h_height) {
        @text = split("\n", &SdfPageInfo($sdf_type, "HEADER", "macro"));
        @text = ('HEADER:') unless @text;
        $id = &_MifAddTextFlow(*text, '');
        &_MifAddTextArea(*page, $id, $left, $h_top, $width, $h_height,
          $sh_width, $sh_gap, &SdfPageInfo($sdf_type, "HEADER_BORDER"));
    }

    # Add the footer, if any
    if ($f_height) {
        @text = split("\n", &SdfPageInfo($sdf_type, "FOOTER", "macro"));
        @text = ('FOOTER:') unless @text;
#$mif_debug = 1;
        $id = &_MifAddTextFlow(*text, '');
$mif_debug = 0;
        &_MifAddTextArea(*page, $id, $left, $f_top, $width, $f_height,
          $sh_width, $sh_gap, &SdfPageInfo($sdf_type, "FOOTER_BORDER"));
    }

    # Add background objects, if any
    $background = &SdfPageInfo($sdf_type, "BACKGROUND");
    if ($background ne '') {
        &_MifAddPageBackground(*page, $background, $background);
    }

    # Add the object footer
    push(@page, "> # end of Page");

    # Add the page to the internal buffers
    push(@_mif_pages, join("\n", @page));
}

#
# >>_Description::
# {{Y:_MifAddTextFlow}} adds a text flow to the internal buffers.
# {{@text}} is the sdf for the text in the text flow,
# unless {{mif}} is true, in which case {{@text}} is assumed to be MIF.
# {{tag}} is the tag of the text flow, if any.
# The {{id}} of the text flow added is returned.
#
sub _MifAddTextFlow {
    local(*text, $tag, $mif) = @_;
    local($id);
    local(@hdr, @flow);
    local($textflow, $old_match_rule);

    # Get the next text flow id
    $id = $_mif_textflow_cnt++;

    # Build the text flow header
    @hdr = ("",
            " ");
    }

    # Convert the SDF to a MIF, if necessary
    if ($mif) {
        @flow = @text;
    }
    else {
        @flow = ();
        &_MifAddSection(*flow, *text);
    }

    # Convert to a text flow
    if (@flow) {
        $textflow = join("\n", @flow);
        $old_match_rule = $*;
        $* = 1;
        $textflow =~ s/\/;
        $textflow =~ s/\n/\n /g;
        $textflow .= "\n> # end of TextFlow";
        $* = $old_match_rule;
    }

    # If nothing was generated, build the text flow with a dummy paragraph
    else {
        $textflow = join("\n",
            " ",
            "  > # end of ParaLine",
            " > # end of Para",
            "> # end of TextFlow");
    }

    # Add the text flow to the internal buffers
    push(@_mif_textflows, join("\n", @hdr, $textflow));

    # Return result
    return $id;
}

#
# >>_Description::
# {{Y:_MifAddTextArea}} adds a text area to a master or reference page.
# {{@page}} is the MIF page data (so far).
# {{id}} is the id of the text flow for this area.
# {{left}}, {{top}}, {{width}} and {{height}} give the
# rectangle's position. {{shwidth}} and {{shgap}} give
# the sidehead width and gap respectively.
# {{border}} is a comma-separated list of
# attributes which collectively describe the border.
# The format of each attribute is name[=value].
# The supported attributes are:
#
# * {{top}} - a line above the area
# * {{bottom}} - a line below the area
# * {{box}} - a box around the area
# * {{radius}} - for a box, the radius of the corner.
#
# For {{top}}, {{bottom}} and {{box}}, the value of the
# attribute is the line width in points.
#
sub _MifAddTextArea {
    local(*page, $id, $left, $top, $width, $height, $shwidth, $shgap, $border, $colcnt, $colgap) = @_;
#   local();
    local(%border, $nv, $name, $value);
    local($left2, $top2, $width2, $height2);
    local($right, $bottom);

    # Convert the border attribute to a set of name-value pairs
    %border = ();
    for $nv (split(/\s*,\s*/, $border)) {
        if ($nv =~ /\=/) {
            $name = $`;
            $value = $';
        }
        else {
            $name = $nv;
            $value = 1;
        }
        $border{$name} = $value;
    }

    # Add the border, if any
    for $name (sort keys %border) {
        $value = $border{$name};
        if ($name eq 'top') {
            # put the line just above the actual border
            $top2 = $top - $_MIF_BORDER_GAP;
            $right = $left + $width;
            push(@page, &_MifLine($left, $top2, $right, $top2,
                " ", 0, $value));
        }
        elsif ($name eq 'bottom') {
            # put the line just below the actual border
            $right = $left + $width;
            $bottom = $top + $height + $_MIF_BORDER_GAP;
            push(@page, &_MifLine($left, $bottom, $right, $bottom,
                " ", 0, $value));
        }
        elsif ($name eq 'box') {
            # put the rectangle just around the actual border
            $left2 = $left - $_MIF_BORDER_GAP;
            $top2 = $top - $_MIF_BORDER_GAP;
            $width2 = $width + $_MIF_BORDER_GAP * 2;
            $height2 = $height + $_MIF_BORDER_GAP * 2;
            push(@page, &_MifRectangle($left2, $top2, $width2, $height2,
                $border{'radius'}, " ", 0, $value));
        }
    }

    # Add the text rectangle. Note that we explicitly do this AFTER
    # the border stuff so that MIF attribute inheritance will work
    # correctly for background objects (if any).
    $colcnt = 1 if $colcnt < 1;
    $colgap = 0 if $colgap eq '';
    push(@page,
        " ",
        "  ",
        "  ",
        "  ",
        "  ",
        "  ",
        "  ",
        "  ",
        "  ",
        " > # end of TextRect");
}

#
# >>_Description::
# {{Y:_MifLine}} creates a MIF line object.
#
sub _MifLine {
    local($x1, $y1, $x2, $y2, $prefix, $pen, $pen_width, $color) = @_;
#   local($result);
    local(@line);

    # Apply defaults
    $pen       = 0          if $pen       eq '';
    $pen_width = 1          if $pen_width eq '';
    $color     = 'Black'    if $color     eq '';

    # Build the header
    @line = ("$prefix",
        " ",
        " ",
        " ",
        " ");

    # Add the points
    push(@line,
        " ",
        " ",
        " ",
        "> # end of PolyLine");

    # Return result
    return join("\n$prefix", @line);
}

#
# >>_Description::
# {{Y:_MifRectangle}} creates a MIF rectangle object.
# {{radius}} is the radius of the corner (0=square corner).
#
sub _MifRectangle {
    local($left, $top, $width, $height, $radius, $prefix, $pen, $pen_width) = @_;
#   local($result);
    local(@rect);

    # Build the header
    @rect = ("$prefix",
        " ");

    # Add the shape
    push(@rect,
        " ",
        " ",
        "> # end of RoundRect");

    # Return result
    return join("\n$prefix", @rect);
}

#
# >>_Description::
# {{Y:_MifAddPageBackground}} adds background objects to a page.
# {{master}} is the name of the master page to get the
# objects from. The master page is assumed to be in a file called
# {{background}}.{{mif}}.
# If {{required}} is true, then a warning is output if the
# master page is not found.
#
sub _MifAddPageBackground {
    local(*page, $background, $master, $required) = @_;
#   local();
    local($bg_ext, $bg_short, $bg_file);
    local($_, $in_object, $in_file);

    # Find the file
    #$bg_ext = 'bg' . substr($sdf_fmext, -1);
    $bg_ext = 'mif';
    $bg_short = &NameJoin('', $background, $bg_ext);
    $bg_file = &SDF_USER'FindFile($bg_short);
    if ($bg_file eq '') {
        &AppMsg("warning", "unable to find background file '$bg_short'");
        return;
    }

    # Open the file
    unless (open(BGFILE, $bg_file)) {
        &AppMsg("warning", "unable to open background file '$bg_file'");
        return;
    }

    # Copy the objects
    $in_object = 0;
    $in_file = 0;
    while () {
        chop;
        if ($in_object) {
            push(@page, $_);
            $in_object = 0 if /^ \>/;
        }
        elsif ($in_file) {
            last if /^\>/;
            next if /\>$/;
            next if /^ \/) {
            $in_file = 1;
        }
    }
    close(BGFILE);

    # Output a warning, if necessary
    if ($required && !$in_file) {
        &AppMsg("warning", "master page '$master' not found in '$bg_file'");
    }
}

#
# >>_Description::
# {{Y:_MifAddRefPages}} adds the reference pages to the internal buffers.
# {{part_type}} is the book part type. If {{part_type}} is a derived
# list (e.g. TOC), the relevant special text flow is added.
#
sub _MifAddRefPages {
    local($part_type) = @_;
#   local();
    local(@page);
    local($name);
    local(%attr);
    local($page_x, $page_y, $width, $height);
    local($objects);
    local($pen, $pen_width);
    local($y, $length);

    # Build the reference page header
    @page = (
        "",
        " ",
        " ");

    # Add the frames
    $page_x = 72;
    $page_y = 72;
    for $name (sort keys %_mif_frames) {
        %attr = &_MifAttrSplit($_mif_frames{$name});
        $width  = $attr{'Width'};
        $width  = $SDF_USER'var{'DOC_FULL_WIDTH'} if $width eq '';
        $height = $attr{'Height'};
        $page_y += $height + 36;

        # Build the object in the frame, if necessary
        if ($attr{'LineLength'}) {
            $pen       = $attr{'Pen'};
            $pen_width = $attr{'PenWidth'};
            $x         = $attr{'LineX'};
            $x         = 0 if $x eq '';
            $y         = $attr{'LineY'};
            $y         = 0 if $y eq '';
            $length    = $attr{'LineLength'};
            $objects   = &_MifLine($x, $y, $length+$x, $y, "  ", $pen,
                         $pen_width, $attr{'Color'});
        }
        else {
            $objects = $attr{'Objects'};
        }

        # Add the frame
        push(@page,
            " ",
            "  ",
            "  ",
            "  ",
            "  ",
            "  ",
            "  ",
            $objects,
            " > # end of Frame");
    }

    # Add the object footer
    push(@page, "> # end of Page");

    # Add the page to the internal buffers
    push(@_mif_pages, join("\n", @page));

    # Add the special text flow, if necessary
    &_MifAddSpecialTextFlow($part_type);
}
sub _MifAddSpecialTextFlow {
    local($name) = @_;
#   local();
    local(%attr, $layout);
    local(@mif_text, $j, $hdgtag, $tag, $tagtype, $tagbase);
    local($id);
    local(@page);
    local($left, $top, $width, $height, $sh_width, $sh_gap);

    # Get the attributes, if any
    if ($_mif_lists{$part_type}) {
        %attr = &_MifAttrSplit($_mif_lists{$name});
    }
    elsif ($_mif_indexes{$part_type}) {
        %attr = &_MifAttrSplit($_mif_indexes{$name});
    }
    else {
        return;
    }

    # Build the MIF for the text flow.
    # Note: Frame core dumps(!!) if a layout includes a paranumonly
    # or paranum when the matching paragraph has no autonumber, so
    # we make sure this cannot happen!!!
    @mif_text = ();
    if ($name eq 'TOC') {
        for ($j = 1; $j <= $SDF_USER'var{'DOC_TOC'}; $j++) {
            for $tagtype ('H', 'A', 'P') {
                $hdgtag = $SDF_USER'parastyles_to{"$tagtype$j"};
                $tag = $hdgtag . $name;
                $_mif_parastyle_used{$tag}++;
                $layout = &_MifFixLayout($attr{'Layout'}, $hdgtag);
                push(@mif_text,
                     "",
                     " ",
                     " >",
                     "> # end of Para");
            }
        }

        # Ensure the index makes it into the contents
        $hdgtag = $SDF_USER'parastyles_to{"IXT"};
        $tag = $hdgtag . $name;
        $_mif_parastyle_used{$tag}++;
        $layout = &_MifFixLayout($attr{'Layout'}, $hdgtag);
        push(@mif_text,
             "",
             " ",
             " >",
             "> # end of Para");
    }
    elsif ($name eq 'LOF') {
        $hdgtag = $SDF_USER'parastyles_to{"FT"};
        $tag = $hdgtag . $name;
        $_mif_parastyle_used{$tag}++;
        $layout = &_MifFixLayout($attr{'Layout'}, $hdgtag);
        push(@mif_text,
             "",
             " ",
             " >",
             "> # end of Para");
    }
    elsif ($name eq 'LOT') {
        $hdgtag = $SDF_USER'parastyles_to{"TT"};
        $tag = $hdgtag . $name;
        $_mif_parastyle_used{$tag}++;
        $layout = &_MifFixLayout($attr{'Layout'}, $hdgtag);
        push(@mif_text,
             "",
             " ",
             " >",
             "> # end of Para");
    }
    elsif ($name eq 'IX') {
        for $tagbase ('GroupTitles', 'Index', 'Level1', 'Level2') {
            $tag = $tagbase . $name;
            $_mif_parastyle_used{$tag}++ if $_mif_paras{$tag};
        }
    }

    # Add the text flow to the internal buffers
    $id = &_MifAddTextFlow(*mif_text, $name, 1);

    # Build the reference page header
    @page = (
        "",
        " ",
        " ");

    # Calculate the page dimensions
    $left     = &SdfVarPoints("OPT_MARGIN_INNER");
    $width    = &SdfVarPoints("DOC_FULL_WIDTH");
    $top      = &SdfVarPoints("OPT_MARGIN_TOP");
    $height   = &SdfVarPoints("DOC_TEXT_HEIGHT");
    $sh_width = &SdfVarPoints("OPT_SIDEHEAD_WIDTH");
    $sh_gap   = &SdfVarPoints("OPT_SIDEHEAD_GAP");

    # Add the text area
    &_MifAddTextArea(*page, $id, $left, $top, $width, $height, $sh_width,
      $sh_gap);

    # Add the object footer
    push(@page, "> # end of Page");

    # Add the page to the internal buffers
    push(@_mif_pages, join("\n", @page));
}

#
# >>_Description::
# {{Y:_MifFixLayout}} removes paranum/paranumonly building blocks
# from a layout for a paragraph which does not have an autonumber.
#
sub _MifFixLayout {
    local($layout, $paratag) = @_;
    local($result);
    local(%attr);

    # Build the result
    $result = $layout;
    %attr = &_MifAttrSplit($_mif_paras{$paratag});
    if ($attr{'NumFormat'} eq '') {
        $result =~ s/\<\$paranumonly\\\>//g;
        $result =~ s/\<\$paranum\\\>//g;
    }
#print STDERR "$paratag:$result.\n";

    # Return result
    return $result;
}

#
# >>_Description::
# {{Y:_MifAddLists}} adds the generated lists (i.e. table of contents, etc.).
#
sub _MifAddLists {
    local(*text) = @_;
#   local();
    local($target, $soft);
    local($name);
    local(%attr);
    local($layout);
    local($i);
    local($old_match_rule, $toc_offset);

    # Set some flags based on the output ultimately generated
    $target = $SDF_USER'var{'OPT_TARGET'};
    $soft = $target eq 'help' || $target eq 'html';

    # Process the list definitions (add xrefs, etc.)
    for $name (sort keys %_mif_lists) {
        %attr = &_MifAttrSplit($_mif_lists{$name});
        $layout = $attr{'Layout'};
        $layout = '<$paratext\>' if $soft;
        $_mif_xrefs{$name} = $layout;
    }

    # Add titles
    if (@_mif_toc_list) {
        unshift(@_mif_toc_list, &_MifListTitle('TOC', 'Table of Contents'));
    }
    if (@_mif_lof_list) {
        unshift(@_mif_lof_list, &_MifListTitle('LOF', 'List of Figures'));
    }
    if (@_mif_lot_list) {
        unshift(@_mif_lot_list, &_MifListTitle('LOT', 'List of Tables'));
    }

    # Insert the generated lists before the first level 1 heading
    push(@_mif_toc_list, @_mif_lof_list, @_mif_lot_list);
    if (@_mif_toc_list) {
        $old_match_rule = $*;
        $* = 1;
        $toc_offset = 0;
        para:
        for ($i = 0; $i <= $#text; $i++) {
            if ($text[$i] =~ /\/) {
                $toc_offset = $i;
                last para;
            }
        }
        $* = $old_match_rule;
        splice(@text, $toc_offset, 0, @_mif_toc_list);
    }
}

#
# >>_Description::
# {{Y:_MifListTitle}} builds a title for a generated list.
# The mif for the title is returned. {{default_title}} is used if
# a title hasn't been specified via the appropriate SDF variable.
#
sub _MifListTitle {
    local($type, $default_title) = @_;
    local($mif);
    local($title, $tag);
    local(@sdf_data, @mif_data);

    # If we're building component covers, make sure that the relevant SDF
    # macro gets called
    $mif = '';
    if ($SDF_USER'var{'OPT_COMPONENT_COVER'} &&
        ($type eq 'TOC' || $type eq 'IX')) {
        @sdf_data = ('!DOC_COMPONENT_COVER_BEGIN');
        &_MifAddSection(*mif_data, *sdf_data);
        $mif = join("\n", @mif_data) . "\n";
    }

    $tag = $SDF_USER'parastyles_to{$type . 'T'};
    $_mif_parastyle_used{$tag}++;
    $title = $SDF_USER'var{"DOC_${type}_TITLE"};
    $title = $default_title if $title eq '';
    &_MifEscape(*title);
    $mif .=
        "\n" .
        " \n" .
        " >\n" .
        "> # end of Para";

    # Return result
    return $mif;
}

#
# >>_Description::
# {{Y:_MifMerge}} merges an import table into a MIF template.
# The import table must be generated so that each
# main MIF object contains one record only. {{offset}} contains
# the indices of each main MIF object which exists in {{@import}}.
# Reference pages and their textflows are retained from {{@template}}.
# The other pages (i.e. the master and body pages) must be supplied
# by {{@import}}.
#
sub _MifMerge {
    local(*template, *import, %offset) = @_;
    local(@new);
    local($record, $obj);
    local($old_match_rule);
    local($merged_pages, $merged_textflows, %ref_textflow);
    local($side_width);
    local($page_type, $page_name, $page_size, $cover_rect);
    
    # To permit multi-line matching, save the old state here and
    # restore it later      
    $old_match_rule = $*;
    $* = 1;

    #
    # Do the merge. We ignore BookComponent objects
    # in @import as this simplifies the code somewhat.
    # As a Tbls section may or may not exist in the template,
    # we ignore existing Tbls and place new tables, if any,
    # immediately after figures (AFrames).
    #
    # We use while/shift, rather than for, to save memory.
    #
    $merged_pages = 0;
    $merged_textflows = 0;
    %ref_textflow = ();
    while($record = shift(@template)) {
    
        # Find the object 'name'
        unless ($record =~ /^\<(\w+)/) {
            &AppExit("fatal", "MIF template error - expecting object");
        }       
        $obj = $1;

        # Patch the comment to claim responsibility
        if ($obj eq 'MIFFile') {
            $record =~ s/\>.*$/>/;
            $record .= " # Generated by $app_product_name $app_product_version";
        }
        
        # Patch in records from import  
        if ($obj eq 'TextFlow') {

            # If this is the first text flow, merge the import text flows
            unless ($merged_textflows) {
                $merged_textflows = 1;
                push(@new, $import[$offset{'TextFlow'}]);
            }

            # If this is a text flow for a reference page, keep it
            if ($record =~ /\/) {
                    $ref_textflow{$1} = 1;
                }
                #else {
                #    &AppMsg("warning", "MIF template error - no TextRect ID for reference page");
                #}
            }
        }
        elsif ($obj eq 'AFrames') {
            if ($offset{$obj}) {
                push(@new, $import[$offset{$obj}]);
            }
            if ($offset{"Tbls"}) {
                push(@new, $import[$offset{"Tbls"}]);
            }
        }
        elsif ($obj ne 'BookComponent' && $obj ne 'Tbls' && $offset{$obj}) {
            push(@new, $import[$offset{$obj}]);
        }
        else {
            push(@new, $record);
        }
    }
    
    # Return result
    $* = $old_match_rule;
    return @new;    
}

#
# >>_Description::
# {{Y:_MifHandlerTuning}} handles the 'tuning' directive.
#
sub _MifHandlerTuning {
    local(*outbuffer, $tuning, %attr) = @_;
#   local();
    local($template_file);

    # Regardless of what happens, make sure we init things
    &_MifInitTemplate();

    # A tuning of '.' means to skip merging (used in testing)
    if ($tuning eq '.') {
        return;
    }

    # Find the template file. A template file is searched for by
    # looking for {{tuning}}.{{fmver}} along the SDF include
    # path, where {{sdfver}} is fm4 or fm5 (typically).
    $template_file = &SDF_USER'FindFile(&NameJoin('', $tuning, $sdf_fmext));
    if ($template_file eq '') {
        #&AppMsg("warning", "unable to find template '$tuning'");
        return;
    }

    # Load the template file
    unless (&_MifFetchTemplate($template_file)) {
        &AppMsg("warning", "unable to load template file '$template_file'");
    }
}

#
# >>_Description::
# {{Y:_MifHandlerEndTuning}} handles the 'endtuning' directive.
#
sub _MifHandlerEndTuning {
    local(*outbuffer, $text, %attr) = @_;
#   local();

    # do nothing
}

#
# >>_Description::
# {{Y:_MifHandlerTable}} handles the 'table' directive.
#
sub _MifHandlerTable {
    local(*outbuffer, $columns, %attr) = @_;
#   local();
    local($tbl_id);
    local($style, $style_tag);
    local($tbl_title);
    local($tbl_width, $unit_width, $width, @widths);
    local($rest);
    local($target);
    local(@equal_cols, $col);
    local($lower, $sep, $upper);
    local($indent);
    local($align, $placement);
    local($margins);

    # Update the state
    push(@_mif_tbl_state, $_MIF_INTABLE);
    push(@_mif_tbl_start, $#outbuffer + 1);
    push(@_mif_tbl_wide, $attr{'wide'});
    push(@_mif_tbl_style, $attr{'style'});
    push(@_mif_tbl_landscape, $attr{'landscape'});
    push(@_mif_row_type, '');

    # Get the table id. Note that we keep a queue of these (rather
    # than a stack) to ensure that nested table are output in the
    # right order.
    $tbl_id = $#_mif_table + scalar(@_mif_tbl_id) + $_MIF_OBJ_REF_START;
    unshift(@_mif_tbl_id, $tbl_id);

    # Get the style
    $style = $attr{'style'};
    $style_tag = $SDF_USER'tablestyles_to{$style};
    if ($style_tag eq '') {
        &AppMsg("warning", "unknown table style '$style'");
        $style_tag = $style;
    }

    # Get the title, if any. FrameMaker 5.0 adds blank pages for
    # tables with titles, so a configuration flag controls whether
    # we produce real or simulated table titles.
    $tbl_title = $attr{'title'};
    push(@_mif_tbl_title, $tbl_title);
    $tbl_title = '' if $_MIF_SIMPLE_TBL_TITLES;

    # Get the indent
    if (!$attr{'wide'} && $attr{'listitem'} ne '') {
        $indent = &SdfVarPoints('OPT_LIST_INDENT') * $attr{'listitem'};
    }
    else {
        $indent = 0;
    }

    # Get the positioning details
    $align = $attr{'align'};
    $align = 'Inside' if $align eq 'Inner';
    $align = 'Outside' if $align eq 'Outer';
    $placement = $attr{'placement'};
    $placement =~ s/top/Top/ if $placement ne '';

    # For landscape tables, the default alignment is centered, i.e.
    # the table is centered BEFORE rotation
    if ($attr{'landscape'} && $align eq '') {
        $align = 'Center';
    }

    # Get the table width and 1% (i.e. unit) width
    if ($attr{'wide'}) {
        $tbl_width = $SDF_USER'var{'DOC_FULL_WIDTH'} - $indent;
    }
    else {
        $tbl_width = $SDF_USER'var{'DOC_TEXT_WIDTH'} - $indent;
    }
    $unit_width = $tbl_width / 100;

    # For margins not supplied, we use some defaults. Ideally,
    # the default values should come from the table format used.
    ($_mif_tbl_lmargin, $_mif_tbl_tmargin, $_mif_tbl_rmargin,
      $_mif_tbl_bmargin) = (6, 4, 6, 2);

    # Get the cell margins, if necessary
    if ($attr{'lmargin'} ne '' || $attr{'tmargin'} ne '' ||
        $attr{'rmargin'} ne '' || $attr{'bmargin'} ne '') {
        $_mif_tbl_lmargin = $attr{'lmargin'} if defined $attr{'lmargin'};
        $_mif_tbl_tmargin = $attr{'tmargin'} if defined $attr{'tmargin'};
        $_mif_tbl_rmargin = $attr{'rmargin'} if defined $attr{'rmargin'};
        $_mif_tbl_bmargin = $attr{'bmargin'} if defined $attr{'bmargin'};
        $margins =
          "${_mif_tbl_lmargin}pt ${_mif_tbl_tmargin}pt " .
          "${_mif_tbl_rmargin}pt ${_mif_tbl_bmargin}pt";
    }

    # Update the output buffer
    $_mif_tblstyle_used{$style_tag}++;
    push(@outbuffer, 
        " ",
        "  ");

    # If we're ultimately going to rtf or hlp, output a simple set of
    # column widths
    $target = $SDF_USER'var{'OPT_TARGET'};
    if ($target eq 'hlp' || $target eq 'rtf') {
        push(@outbuffer, "  ");
        @widths = split(/,/, $attr{'format'});
        $rest = 100;
        for ($col = 0; $col < $columns; $col++) {
            $width = $widths[$col];
            if ($width =~ /([-=])/) {
                # Assume 30% for now :-(
                $width = (30 * $unit_width) . 'pt';
                $rest -= 30;
            }
            elsif ($width =~ /\*$/) {
                # Assume the rest for now. This will work provided
                # that it is last column and that preceding dimensions are 
                # guessed (e.g. -) or percentages. :-(
                $rest = 10 if $rest <= 0;
                $width = ($rest * $unit_width) . 'pt';
                $rest = 0;
            }
            else {
                # Convert the measurement to points if it's a percentage
                if ($width =~ /\%$/) {
                    $rest -= $`;
                    $width = ($` * $unit_width) . 'pt';
                }
            }
            push(@outbuffer, "  ");
        }
    }

    else {
        # Override the table format
        push(@outbuffer, "  ") if $tbl_title;
        push(@outbuffer, "   ") if $indent ne '';
        push(@outbuffer, "   ") if $align;
        push(@outbuffer, "   ") if $placement;
        push(@outbuffer, "   ") if $margins;
        push(@outbuffer, "   ");

        # Output the column widths
        @widths = split(/,/, $attr{'format'});
        @equal_cols = ();
        for ($col = 0; $col < $columns; $col++) {
            $width = $widths[$col];
            push(@outbuffer, "   ");
            if ($width =~ /([-=])/) {
                $lower = $`;
                $sep   = $1;
                $upper = $';
                $lower = ($` * $unit_width) . 'pt' if $lower =~ /\%$/;
                $upper = ($` * $unit_width) . 'pt' if $upper =~ /\%$/;
                push(@outbuffer, "    ");
                push(@equal_cols, $col) if $sep eq '=';
            }
            elsif ($width =~ /\*$/) {
                push(@outbuffer, "    ");
            }
            else {
                $width = ($` * $unit_width) . 'pt' if $width =~ /\%$/;
                push(@outbuffer, "    ");
            }
            push(@outbuffer, "   > # end of TblColumn");
        }
        push(@outbuffer, "  > # end of TblFormat");

        # Output the column details (those not already in the table format)
        push(@outbuffer, "  ");
        if (@equal_cols) {
            push(@outbuffer, "  ");
            }
            push(@outbuffer, "  > # end of EqualizeWidths");
        }
    }

    # Output the table title, if any
    if ($tbl_title) {
        push(@outbuffer, "   # end of TblTitleContent");
    }    
}

#
# >>_Description::
# {{Y:_MifHandlerRow}} handles the 'row' directive.
#
sub _MifHandlerRow {
    local(*outbuffer, $text, %attr) = @_;
#   local();
    local($state);

    # Finalise the old cell/row, if any
    $state = $_mif_tbl_state[$#_mif_tbl_state];
    if ($state eq $_MIF_INCELL) {
        push(@outbuffer,
            "     > # end of CellContent",
            "    > # end of Cell",
            "   > # end of Row",
            "  > # end of TblH/TblBody/TblF");
    }
    elsif ($state eq $_MIF_INROW) {
        push(@outbuffer,
            "   > # end of Row",
            "  > # end of TblH/TblBody/TblF");
    }

    # Update the state
    $_mif_tbl_state[$#_mif_tbl_state] = $_MIF_INROW;
    $_mif_row_type[$#_mif_row_type] = $text;

    # Update the output buffer
    push(@outbuffer,
            "  ") if $text eq 'Group';
}

#
# >>_Description::
# {{Y:_MifHandlerCell}} handles the 'cell' directive.
#
sub _MifHandlerCell {
    local(*outbuffer, $text, %attr) = @_;
#   local();
    local($state);
    local($fill, $color, $cols, $rows, $angle);
    local($lruling, $rruling, $truling, $bruling);

    # Finalise the old cell, if any
    $state = $_mif_tbl_state[$#_mif_tbl_state];
    if ($state eq $_MIF_INCELL) {
        push(@outbuffer,
            "     > # end of CellContent",
            "    > # end of Cell");
    }

    # Update the state
    $_mif_tbl_state[$#_mif_tbl_state] = $_MIF_INCELL;
    $_mif_cell_align = $attr{'align'};
    $_mif_cell_valign = $attr{'valign'};
    if ($_mif_cell_valign eq 'Baseline') {
        $_mif_cell_valign = '';
    }
    $_mif_cell_tmargin = $attr{'tmargin'};
    $_mif_cell_bmargin = $attr{'bmargin'};
    $_mif_cell_lmargin = $attr{'lmargin'};
    $_mif_cell_rmargin = $attr{'rmargin'};

    # Get the attributes
    $color = &_MifMapColor($attr{'bgcolor'});
    $fill = $attr{'fill'} ne '' ? $_MIF_FILL_CODE{$attr{'fill'}} :
            ($color ne '' ? 0 : '');
    $cols = $attr{'cols'};
    $rows = $attr{'rows'};
    $angle = $attr{'angle'};
    $lruling = $attr{'lruling'};
    $lruling = 'Very Thin' if $lruling eq 'Vthin';
    $rruling = $attr{'rruling'};
    $rruling = 'Very Thin' if $rruling eq 'Vthin';
    $truling = $attr{'truling'};
    $truling = 'Very Thin' if $truling eq 'Vthin';
    $bruling = $attr{'bruling'};
    $bruling = 'Very Thin' if $bruling eq 'Vthin';

    # For tables of style "columns", the default top ruling of
    # group rows is 'Thin'
    if ($_mif_row_type[$#_mif_row_type] eq 'Group' && $truling eq '') {
        $truling = 'Thin' if $_mif_tbl_style[$#_mif_tbl_style] eq 'columns';
    }

    # Update the output buffer
    push(@outbuffer, "    ") if $fill ne '';
    push(@outbuffer, "     ") if $color ne '';
    push(@outbuffer, "     ") if $cols > 1;
    push(@outbuffer, "     ") if $rows > 1;
    push(@outbuffer, "     ") if $angle != 0;
    push(@outbuffer, "     ") if $lruling ne '';
    push(@outbuffer, "     ") if $rruling ne '';
    push(@outbuffer, "     ") if $truling ne '';
    push(@outbuffer, "     ") if $bruling ne '';
    push(@outbuffer, "     >_Description::
# {{Y:_MifHandlerEndTable}} handles the 'endtable' directive.
#
sub _MifHandlerEndTable {
    local(*outbuffer, $text, %attr) = @_;
#   local();
    local($state, $start, $tbl_id, $tbl_title, $tbl_wide);
    local($nested, $angle);

    # Finalise the table
    $state = pop(@_mif_tbl_state);
    if ($state eq $_MIF_INCELL) {
        push(@outbuffer,
            "     > # end of CellContent",
            "    > # end of Cell",
            "   > # end of Row",
            "  > # end of TblH/TblBody/TblF");
    }
    elsif ($state eq $_MIF_INROW) {
        push(@outbuffer,
            "   > # end of Row",
            "  > # end of TblH/TblBody/TblF");
    }
    push(@outbuffer,
            " > # end of Tbl");

    # Move the table to the table buffer
    $start = pop(@_mif_tbl_start);
    push(@_mif_table, join("\n", @outbuffer[$start .. $#outbuffer]));
    $#outbuffer = $start - 1;

    # Update the main text flow
    $tbl_id = pop(@_mif_tbl_id);
    $tbl_wide = pop(@_mif_tbl_wide);
    $tbl_title = pop(@_mif_tbl_title);
    $landscape = pop(@_mif_tbl_landscape);
    if (@_mif_tbl_id) {
        &'AppMsg("warning", "ignoring nested MIF table");
    }
    else {
        if ($landscape) {
            $nested = $landscape;
            $angle = 90;
        }
        &_MifUpdateMainFlow(*outbuffer, "table", $tbl_id, $tbl_title, $tbl_wide,
          $nested, $angle);
    }

    # Cleanup the state
    pop(@_mif_tbl_style);
    pop(@_mif_row_type);
}

#
# >>_Description::
# {{Y:_MifHandlerInline}} handles the inline directive.
#
sub _MifHandlerInline {
    local(*outbuffer, $text, %attr) = @_;
#   local();

    # Check we can handle this format
    my $target = $attr{'target'};
    return unless $target eq 'mif' || $target eq 'ps';

    # Build the result
    push(@outbuffer, $text);
}

#
# >>_Description::
# {{Y:_MifHandlerOutput}} handles the output directive.
#
sub _MifHandlerOutput {
    local(*outbuffer, $text, %attr) = @_;
#   local();
    local($offset, @component_data);
    local($component_type);
    local($file);

    # Finalise the current component, if requested
    if ($text eq '-') {
        # If there is no current component, do nothing
        return unless @_mif_component_offset;

        # Find the component type
        $component_type = $_mif_component_type[$_mif_component_cursor++];

        # Generate the mif
        $offset = pop(@_mif_component_offset);
        @component_data = splice(@outbuffer, $offset + 1);
        @component_data = &_MifFinalise(*component_data, $component_type);

        # Output the mif
        $file = pop(@_mif_component_file);
        unless (open(CHAPTER, ">$file")) {
            &AppMsg("error", "unable to write to component file '$file'");
            return;
        }
        print CHAPTER join("\n", @component_data), "\n";
        close(CHAPTER);
    }

    # Otherwise, save the output filename and the current offset
    # Note: the type is pushed onto @_mif_component_type by MifNewComponent.
    else {
        push(@_mif_component_file, $text);
        push(@_mif_component_offset, $#outbuffer);
    }
}

#
# >>_Description::
# {{Y:_MifHandlerImport}} handles the import directive.
#
sub _MifHandlerImport {
    local(*outbuffer, $filepath, %attr) = @_;
#   local();
    local($ref_id);

    # Add the figure to the internal buffers
    $ref_id = &_MifAddFigure($filepath, *attr);

    # Reference this object in the main flow
    &_MifUpdateMainFlow(*outbuffer, 'figure', $ref_id, $attr{'title'},
      $attr{'wide'});
}

#
# >>_Description::
# {{Y:_MifAddFigure}} adds a figure to the internal buffers.
# The reference id of the figure is returned.
#
sub _MifAddFigure {
    local($filepath, *attr) = @_;
    local($ref_id);
    local($fullname);
    local($ext);

    # Get the complete pathname and the file extension
    $fullname = $attr{'fullname'};
    $ext = (&NameSplit($fullname))[2];

    # Get the reference in the output buffer
    if ($ext eq 'mif') {
        $ref_id = &_MifAdd($fullname, 'figure', 1, *attr);
    }
    elsif ($attr{'mif_figure'}) {
        $ref_id = &_MifAdd($fullname, 'figure', $attr{'mif_figure'}, *attr);
    }
    else {
        $attr{'position'} = 'RunIntoParagraph' if $attr{'wrap_text'};
        $attr{'position'} = 'below' unless $attr{'position'};
        $ref_id = &_MifAddRef($filepath, %attr);
    }

    # Return result
    return $ref_id;
}

#
# >>_Description::
# {{Y:_MifHandlerObject}} handles the 'object' directive.
#
sub _MifHandlerObject {
    local(*outbuffer, $type, %attrs) = @_;
#   local();
    local($fn);
    local($name, $parent);

    # Find the object handler, if any
    $fn = "_MifObjectHandler$type";
    if (defined &$fn) {

        # Get the name and parent
        $name = $attrs{'Name'};
        delete $attrs{'Name'};
        $parent = $attrs{'Parent'};
        delete $attrs{'Parent'};

        # Jump to the routine which handles this object
        &$fn(*outbuffer, $name, $parent, %attrs);
    }
}

#
# >>_Description::
# {{Y:_MifAddToCatalog}} adds an object to a catalog of objects.
# If {{$parent}} and {{$root}} are set and equal, then {{%root_attr}} is
# used instead of retrieving the parent attributes from the catalog.
# This is done to improve performance.
#
sub _MifAddToCatalog {
    local(*catalog, $type, $name, $parent, *attr, *root, *root_attr) = @_;
#   local();
    local(%parent_attr);

    # Get the parent definition, if any
    %parent_attr = ();
    if ($parent ne '') {
        if ($parent eq $root) {
            %parent_attr = %root_attr;
        }
        else {
            %parent_attr = &_MifAttrSplit($catalog{$parent});
        }
        unless (%parent_attr) {
            &AppMsg("warning", "unknown parent '$parent' in definition of mif $type '$name'");
            return;
        }
    }

    # Merge in the new attributes
    @parent_attr{keys %attr} = values %attr;

    # Store the new definition
    $catalog{$name} = &_MifAttrJoin(*parent_attr);

    # Save the root, if necessary
    if ($root eq '' && $parent eq '') {
        $root = $name;
        %root_attr = %attr;
    }
}

#
# >>_Description::
# {{Y:_MifObjectHandlerVariable}} defines 'Variable' objects.
#
sub _MifObjectHandlerVariable {
    local(*outbuffer, $name, $parent, %attr) = @_;
#   local();
    local($value);

    $name = $_MIF_VAR_MAP{$name} if $_MIF_VAR_MAP{$name};
    $value = $attr{'value'};
    if ($name =~ /^MIF_/) {
        return if $name eq 'MIF_TABLE_UNIT';
        return if $name eq 'MIF_TABLE_UNIT_WIDE';
        if ($name eq 'MIF_COVER') {
            $_mif_cover = $value;
        }
        else {
            $name = 'D' . &MiscUpperToMixed($');
            $_mif_ctrls{$name} = $value;
        }
    }
    else {
        $_mif_vars{$name} = $value;
    }
}

#
# >>_Description::
# {{Y:_MifObjectHandlerXref}} defines 'Xref' objects.
#
sub _MifObjectHandlerXref {
    local(*outbuffer, $name, $parent, %attr) = @_;
#   local();

    $_mif_xrefs{$name} = $attr{'value'};
}

#
# >>_Description::
# {{Y:_MifObjectHandlerPara}} defines 'Para' objects,
# i.e. it generates a new paragraph format in the output.
#
sub _MifObjectHandlerPara {
    local(*outbuffer, $name, $parent, %attr) = @_;
#   local();

    &_MifAddToCatalog(*_mif_paras, 'paragraph', $name, $parent, *attr,
      *_mif_pararoot_name, *_mif_pararoot_attr);
}

#
# >>_Description::
# {{Y:_MifObjectHandlerPhrase}} defines 'Phrase' objects,
# i.e. it generates a new font format in the output.
#
sub _MifObjectHandlerPhrase {
    local(*outbuffer, $name, $parent, %attr) = @_;
#   local();

    &_MifAddToCatalog(*_mif_fonts, 'font', $name, $parent, *attr,
      *_mif_fontroot_name, *_mif_fontroot_attr);
}

#
# >>_Description::
# {{Y:_MifObjectHandlerTable}} defines 'Table' objects,
# i.e. it generates a new table format in the output.
# {{tags}} contains the new and base tags separated by a space.
#
sub _MifObjectHandlerTable {
    local(*outbuffer, $name, $parent, %attr) = @_;
#   local();

    &_MifAddToCatalog(*_mif_tbls, 'table', $name, $parent, *attr,
      *_mif_tblroot_name, *_mif_tblroot_attr);
}

#
# >>_Description::
# {{Y:_MifObjectHandlerFrame}} defines 'Frame' objects,
# i.e. it generates a reference frame in the output.
#
sub _MifObjectHandlerFrame {
    local(*outbuffer, $name, $parent, %attr) = @_;
#   local();

    &_MifAddToCatalog(*_mif_frames, 'frame', $name, $parent, *attr,
      *_mif_frameroot_name, *_mif_frameroot_attr);
}

#
# >>_Description::
# {{Y:_MifObjectHandlerList}} defines 'List' objects.
# i.e. it defines the layout of the TOC (Table of Contents), etc.
#
sub _MifObjectHandlerList {
    local(*outbuffer, $name, $parent, %attr) = @_;
#   local();

    &_MifAddToCatalog(*_mif_lists, 'lists', $name, $parent, *attr,
      *_mif_listroot_name, *_mif_listroot_attr);
}

#
# >>_Description::
# {{Y:_MifObjectHandlerIndex}} defines 'Index' objects.
# i.e. it defines the layout of an index
#
sub _MifObjectHandlerIndex {
    local(*outbuffer, $name, $parent, %attr) = @_;
#   local();

    &_MifAddToCatalog(*_mif_indexes, 'indexes', $name, $parent, *attr,
      *_mif_indexroot_name, *_mif_indexroot_attr);
}

#
# >>_Description::
# {{Y:_MifPhraseHandlerChar}} handles the 'char' phrase directive.
#
sub _MifPhraseHandlerChar {
    local(*para, $text, %attr) = @_;
#   local();
    local($char);
    local($hex);

    $char = $_MIF_CHAR{$text};
    if ($text =~ /^\d+/) {
        $hex = sprintf("%x", $text);
        $para .= "  \n";
    }
    elsif ($char =~ /^\W/) {
        $para .= "  \n";
    }
    elsif ($char) {
        $para .= "  \n";
    }
    else {
        &AppMsg("warning", "ignoring unknown character '$text'");
    }

    # Hard returns must be the last thing in a ParaLine
    if ($char eq 'HardReturn' || $text == $_MIF_HARDRETURN_CODE) {
        $para .= " > # end of ParaLine\n" .
            " >_Description::
# {{Y:_MifPhraseHandlerInline}} handles the 'inline' phrase directive.
#
sub _MifPhraseHandlerInline {
    local(*para, $text, %attr) = @_;
#   local();

    # Build the result
    $para .= $text;
}

#
# >>_Description::
# {{Y:_MifPhraseHandlerImport}} handles the 'import' phrase directive.
#
sub _MifPhraseHandlerImport {
    local(*para, $filepath, %attr) = @_;
#   local();

    # Add the figure to the internal buffers
    $attr{'position'} = 'inline' unless $attr{'position'};
    $ref_id = &_MifAddFigure($filepath, *attr);

    # Add the reference to the paragraph
    $para .= "  \n";
}

#
# >>_Description::
# {{Y:_MifPhraseHandlerVariable}} handles the 'variable' phrase directive.
#
sub _MifPhraseHandlerVariable {
    local(*para, $text, %attr) = @_;
#   local();

    $para .= "  \n" .
             "  > # end of Variable\n";
}

#
# >>_Description::
# {{Y:_MifPhraseHandlerXRef}} handles the 'xref' phrase directive.
#
sub _MifPhraseHandlerXRef {
    local(*para, $para_text, %attr) = @_;
#   local();
    local($format, $text, $file);

    # Get the text and file from the jump attribute.
    $format = $attr{'xref'};
    ($file, $text) = split(/#/, $attr{'jump'}, 2);

    # Assume the Frame file, if any, has a doc extension.
    if ($file ne '') {
        $file = &NameSubExt($file, 'doc');
    }

    # Build the cross-reference
    $para .= "  \n" .
             "   \n" .
             "   \n" .
             "  > # end of XRef\n";
}

#
# >>_Description::
# {{Y:_MifPhraseHandlerPageNum}} handles the 'pagenum' phrase directive.
#
sub _MifPhraseHandlerPageNum {
    local(*para, $para_text, %attr) = @_;
#   local();

    &_MifPhraseHandlerVariable(*para, 'Current Page #');
}

#
# >>_Description::
# {{Y:_MifPhraseHandlerPageCount}} handles the 'pagecount' phrase directive.
#
sub _MifPhraseHandlerPageCount {
    local(*para, $para_text, %attr) = @_;
#   local();

    &_MifPhraseHandlerVariable(*para, 'Page Count');
}

#
# >>_Description::
# {{Y:_MifPhraseHandlerParaText}} handles the 'paratext' phrase directive.
#
sub _MifPhraseHandlerParaText {
    local(*para, $tags, %attr) = @_;
#   local();

    &_MifRunningHF(*para, 'paratext', $tags);
}

#
# >>_Description::
# {{Y:_MifPhraseHandlerParaNum}} handles the 'paranum' phrase directive.
#
sub _MifPhraseHandlerParaNum {
    local(*para, $tags, %attr) = @_;
#   local();

    &_MifRunningHF(*para, 'paranum', $tags);
}

#
# >>_Description::
# {{Y:_MifPhraseHandlerParaNumOnly}} handles the 'paranumonly' phrase directive.
#
sub _MifPhraseHandlerParaNumOnly {
    local(*para, $tags, %attr) = @_;
#   local();

    &_MifRunningHF(*para, 'paranumonly', $tags);
}

#
# >>_Description::
# {{Y:_MifPhraseHandlerParaShort}} handles the 'parashort' phrase directive.
#
sub _MifPhraseHandlerParaShort {
    local(*para, $tags, %attr) = @_;
#   local();

    &_MifRunningHF(*para, 'marker1');
}

#
# >>_Description::
# {{Y:_MifPhraseHandlerParaLast}} handles the 'paralast' phrase directive.
#
sub _MifPhraseHandlerParaLast {
    local(*para, $tags, %attr) = @_;
#   local();

    &_MifRunningHF(*para, 'paratext', "+,$tags");
}

#
# >>_Description::
# {{Y:_MifRunningHF}} defines and inserts a Running H/F variable.
# {{type}} is one of paratext, paranum, paranumonly,
# marker1 or marker2. For the first 3 of these, {{tags}} is a
# comma separated list of paragraph tags.
#
sub _MifRunningHF {
    local(*para, $type, $tags) = @_;
#   local();
    local($defn);
    local(@tags, $tag, $fmtag);
    local($num);
    local($varname);

    # Build the definition
    if ($tags eq '') {
        $defn = "<\$$type>";
    }
    else {
        # Convert the SDF tag names to Frame ones
        @tags = split(/,/, $tags);
        for $tag (@tags) {
            $fmtag = $SDF_USER'parastyles_to{$tag};
            $tag =  $fmtag if $fmtag ne '';
        }
        $defn = "<\$$type\[" . join(",", @tags) . "]>";
    }

    # If the definition matches an existing running h/f variable, reuse it
    for ($num = 1; $num <= $_mif_runninghf_cnt; $num++) {
        last if $_mif_vars{"Running H/F $num"} eq $defn;
    }

    # If necessary, update the running h/f counter,
    # checking we haven't used them all
    if ($num  > 4) {
        &AppMsg("warning", "ignoring MIF directive '$type' - Running H/F 4 already used");
        return;
    }
    elsif ($num > $_mif_runninghf_cnt) {
        $_mif_runninghf_cnt++;
    }

    # Insert the variable
    $varname = "Running H/F $num";
    $_mif_vars{$varname} = $defn;
    &_MifPhraseHandlerVariable(*para, $varname);
}

#
# >>_Description::
# {{Y:_MifParaAppend}} merges {{para}} into the last paragraph
# in {{@result}}.
# (This is used to workaround Frame putting blank lines between
# each example paragraph when it converts documents to text.)
#
sub _MifParaAppend {
    local(*result, $para) = @_;
#   local();
    local($body_start);

    # find the location of the first ParaLine in the paragraph
    $body_start = index($para, " = 0) {
        substr($result[$#result], - $_MIF_PARA_END_LEN) = 
          "  \n >\n" . substr($para, $body_start) .
          $_MIF_PARA_END;
    }
    else {
        &AppMsg("failed", "bad paragraph format in '_MifParaAppend'");
    }
}
       
#
# >>_Description::
# {{Y:_MifAdd}} adds an object to the internal lists. These
# lists are merged with the converted text in {{Y:_MifFinalise}}
# to produce the final MIF file. {{id}} can be either:
#
# * a number (the internal object number in the file), or
# * a string (a pattern matched in the text just before the object
# is referenced in the main text flow of the file)
#
sub _MifAdd {
    local($file, $what, $id, *attr) = @_;
    local($ref_id);
    local($ok);
    local(@file);
    local($obj_id, $tag, $tbl_begin, $fmt_id, $fmt_ok);

    # Fetch the file
    ($ok, @file) = &_MifFetchAlbum($file);
    unless ($ok) {
        &AppMsg("warning", "failed to fetch file '$file'");
        return 0;
    }

    # If a pattern is passed as the id, first convert it to an
    # object reference
    if ($id =~ /^\d+$/) {
        $obj_id = $id;
    }
    else {
        $obj_id = &MifIdLookupBySymbol(*file, $_MIF_REF{$what}, $id);
    }

    # Add the object itself & format, if any, onto our stacks
    if ($obj_id) {
        if ($what eq 'table') {
            ($ref_id, $tbl_begin) = &_MifAddObject(*file,
              'Tbl', 'TblID', $obj_id, 'stack', *_mif_table);

            # Assume the table format id is the second attribute
            if ($ref_id) {
                $file[$tbl_begin + 2] =~ /TblTag (.*)\>/;
                $fmt_id = $1;
                $_mif_tblstyle_used{$fmt_id}++;
                ($fmt_ok) = &_MifAddObject(*file, 'TblFormat',
                  'TblTag', $fmt_id, 'byname', *_mif_tbls);
                unless ($fmt_ok) {
                    &AppMsg("warning", "MIF table format clash ($file, $id, $fmt_id)");
                }
            }
        }
        else {
            ($ref_id) = &_MifAddObject(*file,
              'Frame', 'ID', $obj_id, 'stack', *_mif_figure, *attr);
        }
    }

    # Check object was found
    unless ($ref_id) {
        &AppMsg("warning", "mif object '$what $id' not found in file '$file'");
    }

    # Return result
    return $ref_id;
}

#
# >>_Description::
# {{Y:_MifAddRef}} adds a referenced figure to the internal lists. These
# lists are merged with the converted text in {{Y:_MifFinalise}}
# to produce the final MIF file.
# {{%attr}} contains tuning attributes.
#
sub _MifAddRef {
    local($name, %attr) = @_;
    local($ref_id);
    local($fullname);
    local($width, $height);
    local($mif_path);
    local($shape_rect_params);
    local(@frame);

    # Default the height and width, if we can
    $fullname = $attr{'fullname'};
    ($width, $height) = &SdfSizeGraphic($fullname);
    $attr{'width'}  = $width  ? $width  : 20 unless $attr{'width'};
    $attr{'height'} = $height ? $height : 20 unless $attr{'height'};

    # points is the default measurement
    $width = $attr{'width'};
    $height = $attr{'height'};
    $width  .= "pt" if $width  =~ /^[\d\.]+$/;
    $height .= "pt" if $height =~ /^[\d\.]+$/;

    # Convert the name into a MIF device-independent pathname
    #if (! &NameIsAbsolute($name) && $attr{'root'} ne '') {
        #$name = &NameJoin($attr{'root'}, $name);
    #}
    if ($SDF_USER'var{'OPT_TARGET'} eq 'hlp') {
        $mif_path = &_MifPathName($name);
    }
    else {
        $mif_path = &_MifPathName($fullname);
    }

    # Build the Frame body
    $shape_rect_params = "0\" 0\" $width $height";
    @body = (
        "  ",
        "   ",
        "  > # end of ImportObject");

    # Build the frame
    $ref_id = scalar(@_mif_figure) + $_MIF_OBJ_REF_START;
    @frame = &_MifBuildFrame($ref_id, $shape_rect_params, *attr, *body);

    # Add the frame to the internal list
    push(@_mif_figure, join("\n", @frame));

    # Return result
    return $ref_id;
}

#
# >>_Description::
# {{_MifBuildFrame}} build a 'Frame' object, given its id, size, attributes
# and body.
#
sub _MifBuildFrame {
    local($ref_id, $shape_rect_params, *attr, *body) = @_;
    local(@frame);
    local($frametype);

    # Map the attributes to MIF names
    $frametype = $attr{'position'};
    $frametype = 'Below' unless $frametype;
    substr($frametype, 0, 1) =~ tr/a-z/A-Z/;

    # Build the figure frame header
    @frame = (
        " ",
        "  ",
        "  ");

    # Add the optional stuff
    if ($attr{'align'}) {
        substr($attr{'align'}, 0, 1) =~ tr/a-z/A-Z/;
        push(@frame, "  ");
    }
    if ($attr{'clipped'}) {
        push(@frame, "  ");
    }
    if ($attr{'floating'}) {
        push(@frame, "  ");
    }
    if ($attr{'bl_offset'}) {
        $attr{'bl_offset'}  .= "pt" if $attr{'bl_offset'}  =~ /^[\d\.]+$/;
        push(@frame, "  ");
    }
    if ($attr{'ns_offset'}) {
        $attr{'ns_offset'}  .= "pt" if $attr{'ns_offset'}  =~ /^[\d\.]+$/;
        push(@frame, "  ");
    }

    # Return result
    return (@frame, @body, " > # end of Frame");
}

#
# >>_Description::
# {{Y:_MifUpdateMainFlow}} adds a reference to the main text flow.
# If {{nested}} is set, the object is nested inside a TectRect
# which is allocated that percentage of the text column height and
# rotated by {{angle}}.
#
sub _MifUpdateMainFlow {
    local(*outbuffer, $what, $ref_id, $title, $wide, $nested, $angle) = @_;
#   local();
    local($tag);
    local(@para);

    # Get the paragraph tag: 'Title' or 'Body'?
    if ($title ne '') {
        $tag = $SDF_USER'parastyles_to{$_MIF_TITLE_TAG{$what}};

        # Escape special characters
        $title =~ s/([\>\\])/\\$1/g;
        $title =~ s/([\t])/\\t/g;
        $title =~ s/(['])/\\q/g;
        $title =~ s/([`])/\\Q/g;
    }
    else {
        $tag = $SDF_USER'parastyles_to{$_MIF_NOTITLE_TAG{$what}};
    }

    # Build the paragraph
    $_mif_parastyle_used{$tag}++;
    @para = (
        "\n" .
        " \n") if $wide;
    push(@para, "  \n") if $angle;
    push(@para,
        " >\n" .
        " \n" .
        "  <$_MIF_REF{$what} $ref_id>\n" .
        " >\n" .
        "> # end of Para");

    # Handle nested objects
    if ($nested ne '') {
        @para = &_MifAddNestedText(*para, $nested, $angle);
    }

    # Add a reference directly into the output
    push(@outbuffer, @para);
}

#
# >>_Description::
# {{Y:_MifAddObject}} adds an object to the nominated internal list.
# {{lookup_id}} is the object reference id (numeric).
# If {{%attr}} is passed and {{how}} is stack, the object
# is assumed to be a figure and the Frame header is built
# from the attributes passed in.
#
sub _MifAddObject {
    local(*source, $type, $id_str, $lookup_id, $how, *where, *attr) = @_;
    local($new_id, $first, $last);
    local(@this_obj, $this_index, $i);
    local($shape_rect_params);
    local(@body);

    # Search for object using lookup_id
    record:
    for ($i = 0; $i < $#source; $i++) {
        if ($first && $source[$i] =~ /\> \# end of $type\s*$/) {
            $last = $i;
            last record;
        }
        if ($source[$i] =~ /\<$type\s*$/ &&
          $source[$i + 1] =~ /\<$id_str $lookup_id\>/) {
            $first = $i;
            $i += 2;
        }
    }
    return 0 unless $last;

    # Save object
    if ($how eq 'stack') {
        $this_index = scalar(@where) + $_MIF_OBJ_REF_START;
        if (%attr) {
            ($shape_rect_params, @body) =
                &_MifRemoveFrameAttrs(@source[$first + 2 .. $last - 1]);
            @this_obj = &_MifBuildFrame($this_index, $shape_rect_params, *attr,
                *body);
        }
        else {
            @this_obj = (" <$type", "  <$id_str $this_index>",
              @source[$first + 2 .. $last]);
        }
        push(@where, join("\n", @this_obj));
    }
    elsif ($how eq 'byname') {
        $this_index = $lookup_id;
        $this_obj = join("\n", @source[$first .. $last]);
        if ($where{$this_index}) {
            if ($where{$this_index} ne $this_obj) {
                $this_index = "";
            }
        }
        else {
            $where{$this_index} = $this_obj;
        }
    }

    # Return result
    return $this_index, $first, $last;
}

#
# >>_Description::
# {{_MifRemoveFrameAttrs}} removes attributes from a Frame object.
#
sub _MifRemoveFrameAttrs {
    local(@frame) = @_;
    local($shape_rect_params, @body);
    local($junk);
    local($index);

    # Copy across the lines except those between ShapeRect and Cropped
    @body = ();
    $junk = 0;
    for ($index = 0; $index <= $#frame; $index++) {
        $line = $frame[$index];
        last if $line =~ /^\s*]+)\>/) {
            $shape_rect_params = $1;
            $junk = 1;
        }
        elsif (! $junk) {
            push(@body, $line);
        }
    }
    push(@body, @frame[$index + 1 .. $#frame]);

    # Return result
    return ($shape_rect_params, @body);
}

#
# >>_Description::
# {{Y:_MifAddNestedText}} adds paragraph text as a nested object.
# {{@text}} is the text to add. The new text to add into the main text
# flow is returned. {{nested}} is the percentage of the text column
# to allocate to the object and {{angle}} is the angle.
#
sub _MifAddNestedText {
    local(*text, $nested, $angle) = @_;
    local(@result);
    local($textflow_id);
    local($width, $height, $adj_height);
    local($ref_id);
    local(@frame);
    local($tag);

    # Create the new text flow
    $textflow_id = &_MifAddTextFlow(*text, '', 1);

    # Calculate the width and height of the rotated text column.
    # For simplicity, the width is always the column width.
    # The height is calculated as a percentage of the text column
    # height. We also need an "adjusted height" for the embedded
    # text rectangle, otherwise Frame crops the table border.
    $width = $SDF_USER'var{'DOC_TEXT_WIDTH'};
    if ($nested == 1) {
        $height = $SDF_USER'var{'DOC_TEXT_HEIGHT'};
    }
    elsif ($nested =~ /^(\d+)\%?$/) {
        $height = $SDF_USER'var{'DOC_TEXT_HEIGHT'} * $1 / 100;
    }
    else {
        $height = &SdfPoints($nested);
    }
    $adj_height = $height - 2;

    # Build the rotated text column
    $ref_id = scalar(@_mif_figure) + $_MIF_OBJ_REF_START;
    @frame = (
        " ",
        "  ",
        "  ",
        "  ",
        "  ");
    push(@frame,
        "   ") if $angle != 0;
    push(@frame,
        "   ",
        "  > # end of TextRect",
        " > # end of Frame");

    # Add it to the internal buffers
    push(@_mif_figure, join("\n", @frame));

    # Build the new text
    $tag = $SDF_USER'parastyles_to{'N'};
    $_mif_parastyle_used{$tag}++;
    @result = (
        "\n" .
        " \n" .
        " >\n" .
        "> # end of Para");

    # return result
    return @result;
}

#
# >>Description::
# {{Y:MifIdLookupBySymbol}} searches in {{@source}}
# for {{symbol}} closely followed by a reference of type {{ref}}.
# If found, the ID of the object is returned. Otherwise, 0 is returned.
#
sub MifIdLookupBySymbol {
    local(*source, $ref, $symbol) = @_;
    local($id);
    local($safe, $i);

    # escape any metacharacters if symbol
    $safe = $symbol;
    $safe =~ s/(\W)/\\\1/g;

    # search
    for ($i = 0; $i < $#source; $i++) {
        if ($source[$i] =~ /\/ &&
          $source[$i + 1] =~ /\<$ref\s+(\d+)\>/) {
            return $1;
        }
    }

    # If reach here, no luck
    return 0;
}

#
# >>_Description::
# {{Y:_MifPathName}} converts a pathname into a MIF device-independent
# pathname.
# (Thanks to Prachin Ranavat for the initial code.)
#
sub _MifPathName {
    local($name) = @_;
    local($mif);
    local($k);
	my ($is_absolute, $os_name);
	my @components = NamePathComponentSplit($name);

    # check if path is absolute
	$is_absolute = &NameIsAbsolute($name);
	$os_name = &NameOS;
	
	SWITCH_OS: {
		$mif = '', last SWITCH_OS if $os_name eq 'unix' && $is_absolute;
		$mif = '' . shift @components, last SWITCH_OS if $os_name eq 'mac' && $is_absolute;
		$mif = '' . shift @components, last SWITCH_OS if $os_name eq 'dos' && $is_absolute;
	}
    foreach $k (@components) {
		next if !$k;
	    if ($k eq '..' || $k eq '::') {
    	    # parent directory in path - replace by 
	        $mif .= "";
        }
        else {
	        # directory name in path - replace by directory_name
	        $mif .= "".$k;
    	}
    }

    # Return result
    return ($mif);
}

#
# >>Description::
# {{Y:MifLink}} converts a hypertext link in URL format to a frame one.
# {{mif_ext}} is the extension to use on Frame files in hypertext jumps.
# The default value is {{fvo}}.
#
sub _MifLink {
    local($url, $mif_ext) = @_;
    local($mif_link);
    local($file, $topic);
    local($spec_char);

    # Setup special characters match string
    $spec_char = "\\>\\\\";

    # Default the file extension to fvo, if necessary
    $mif_ext = 'fvo' unless $mif_ext ne '';

    if ($url =~ /^([-\w\/\.]*)#/) {
        ($file, $topic) = ($1, $');
        if ($file ne '') {
            $file =~ s/\.html$//;
            $file .= ".$mif_ext";
        }
        $topic =~ s/([$spec_char])/\\$1/g;
        $mif_link = "gotolink " . ($file ? "$file:$topic" : $topic);
    }
    elsif ($url =~ /^([-\w\/\.]*)$/) {
        $url =~ s/\.html$//;
        $url .= ".$mif_ext";
        $mif_link = "gotopage $url:firstpage";
    }
    else {
        $mif_link = "gotourl $url";
        #$mif_link = "sdf url=$url";    # once TJH fixes fm2html
    }

    # Return result
    return $mif_link;
}

#
# >>_Description::
# {{Y:MifEscapeNewlink}} escapes a newlink.
# (Thanks to Tim Hudson for the code.)
#
sub _MifEscapeNewlink {
    local($link) = @_;
    local($result);
    local($spec_char);

    ##print STDERR "NEWLINK-IN: $link\n";

    # Assign default special characters match string, if necessary
    $spec_char = "\\>\\\\" if $spec_char eq '';

    $link =~ s/([$spec_char])/\\$1/g;

    # escape quotes
    $link =~ s/\'/\\q/g;

    # strip backquotes 
    $link =~ s/\`//g;

    1 while $link =~ s/{{.:([^}]*)}}/$1/e;

    $link =~ s/^\s+//;

    ##print STDERR "NEWLINK-OUT: $link\n";

    return $link;
}

#
# >>Description::
# {{Y:MifNewComponent}} is an event processing routine for
# paragraphs which begin a new component.
#
sub MifNewComponent {
    local($type) = @_;
    local($cname);

    # Save away the component details (so a book can be constructed later)
    $cname = &_MifComponentName($SDF_USER'var{'DOC_BASE'});
    $type = 'chapter' if $type eq '1';
    push(@_mif_component_tbl, "$cname|$type");
    push(@_mif_component_type, "\U$type");

    # Ensure that each component gets placed into its own output file.
    # (stdlib/mif.sdt takes care of the first part, so ignore it)
    if (scalar(@_mif_component_tbl) > 2) {
        &SDF_USER'PrependText(
            "!DOC_COMPONENT_END",
            "!output '-'",
            "!output '$cname'",
            "!define DOC_COMPONENT '$type'",
            "!DOC_COMPONENT_BEGIN");
    }
    else {
        $SDF_USER'var{'DOC_COMPONENT'} = $type;
    }

    # Return the component name (needed for stdlib/mif.sdt)
    return $cname;
}

#
# >>_Description::
# {{Y:_MifComponentName}} generates a name for a component,
# given the basename of the document.
#
sub _MifComponentName {
    local($base) = @_;
    local($cname);

    $_mif_component_cntr++;
    $cname = $SDF_USER'var{'MIF_COMPONENT_PATTERN'};
    $cname = '$b_$n.$o' if $cname eq '';
    $cname =~ s/\$b/$base/g;
    $cname =~ s/\$n/$_mif_component_cntr/;
    $cname =~ s/\$o/$out_ext/;
    return $cname;
}

#
# >>_Description::
# {{Y:_MifBookBuild}} builds a book from information collected
# during the generation of components.
#
sub _MifBookBuild {
    local(*book, $base) = @_;
#   local(@result);
    local(@newbook);
    local(@batch);
    local($added_toc);
    local(@flds, %values, $i);
    local($mif_file, $type);

    # Build a new book table which includes the derived components.
    # As we go, we also:
    # * generate the mif for each derived component
    # * build a set of fmbatch commands which
    #   generate binary documents for each part
    # * collect the set of mif files so we can delete them later.
    @newbook = ($book[0]);
    @batch = ();
    @sdf_book_files = ();
    $added_toc = 0;
    @flds = &TableFields($book[0]);
    for ($i = 1; $i <= $#book; $i++) {
        %values = &TableRecSplit(*flds, $book[$i]);
        $type = $values{'Type'};
        if ($added_toc == 0 && $type ne 'front' && $type ne 'pretoc') {
            if ($SDF_USER'var{'DOC_TOC'}) {
                $mif_file = &_MifBookDerived($base, 'toc', 'Table of Contents');
                &_MifBookAddPart(*newbook, *batch, $mif_file, 'toc');
                push(@sdf_book_files, $mif_file);
            }
            if ($SDF_USER'var{'DOC_LOF'}) {
                $mif_file = &_MifBookDerived($base, 'lof', 'List of Figures');
                &_MifBookAddPart(*newbook, *batch, $mif_file, 'lof');
                push(@sdf_book_files, $mif_file);
            }
            if ($SDF_USER'var{'DOC_LOT'}) {
                $mif_file = &_MifBookDerived($base, 'lot', 'List of Tables');
                &_MifBookAddPart(*newbook, *batch, $mif_file, 'lot');
                push(@sdf_book_files, $mif_file);
            }
            $added_toc = 1;
        }

        # Add this part
        $mif_file = $values{'Part'};
        &_MifBookAddPart(*newbook, *batch, $mif_file, $type);
        push(@sdf_book_files, $mif_file);
    }
    if ($SDF_USER'var{'DOC_IX'}) {
        $mif_file = &_MifBookDerived($base, 'ix', 'Index');
        &_MifBookAddPart(*newbook, *batch, $mif_file, 'ix');
        push(@sdf_book_files, $mif_file);
    }

    # Pass the batch commands to fmbatch
    &_MifRunBatch(*batch, $verbose);

    # Cleanup the MIF for each part
    &SDF_USER'SdfBookClean();

    # Return result
    return &MifBook(*newbook, $SDF_USER'var{'OPT_NUMBER_PER_COMPONENT'});
}

#
# >>_Description::
# {{Y:_MifBookDerived}} creates a derived component for a book.
# {{mainbase}} is the base component (e.g. ug_doc) of the main file.
# {{type}} is the type of derived component (e.g. toc).
# The {{default_title}} is used if the appropriate SDF variable is not set.
# The name of the new file is returned.
#
sub _MifBookDerived {
    local($mainbase, $type, $default_title) = @_;
    local($newfile);
    local($upper_type, $tag, $title);
    local(@sdf_text, @mif_data);

    # Build the sdf
    $upper_type = "\U$type";
    $tag = $upper_type . 'T';
    $title = $SDF_USER'var{"DOC_${upper_type}_TITLE"};
    $title = $default_title if $title eq '';
    @sdf_text = ("$tag:$title");

    # Convert the sdf to mif
    @mif_data = ();
    &_MifAddSection(*mif_data, *sdf_text);
    @mif_data = &_MifFinalise(*mif_data, $upper_type);

    # Output the mif
    $newfile = &NameJoin('', $mainbase . "_$type", $out_ext);
    if (open(DERIVED, ">$newfile")) {
        print DERIVED join("\n", @mif_data), "\n";
    }
    else {
        &AppMsg("warning", "unable to create file '$newfile'");
    }
    close(DERIVED);

    # Return result
    return $newfile;
}

#
# >>_Description::
# {{_MifBookAddPart}} is the common processing required in {{_MifBookBuild}}
# to add a part to a book for each mif file.
#
sub _MifBookAddPart {
    local(*newbook, *batch, $mif_file, $type) = @_;
#   local();
    local($doc_file);

    $doc_file = &NameSubExt($mif_file, 'doc');
    push(@newbook, &TableRecJoin(*flds, 'Part', $doc_file, 'Type', $type));
    push(@batch, "Open \"$mif_file\"");
    push(@batch, "SaveAs d \"$mif_file\" \"$doc_file\"");
    push(@batch, "Quit \"$mif_file\"");
#print STDERR "adding $doc_file,$type.\n";
}

#
# >>_Description::
# {{_MifRunBatch}} executes a set of fmbatch commands ({{@batch}}).
# If {{verbose}} is set, the results are keep in a temporary file.
#
sub _MifRunBatch {
    local(*batch, $verbose) = @_;
#   local();
    local($fmbatch, $tmp_file);

    $fmbatch = "fmbatch -i";
    $tmp_file = "/tmp/sdf$$";
    if (open(FMBATCH, "|$fmbatch > $tmp_file")) {
        printf FMBATCH "%s\n", join("\n", @batch);
    }
    else {
        &AppMsg("error", "failed to pipe data to fmbatch");
    }
    close(FMBATCH);
    unlink($tmp_file) unless $verbose;
}

#
# >>Description::
# {{Y:MifBook}} returns a mif book built from the components given in
# {{@book}}. If {{number_per_component}} is set:
#
# * parts before the first chapter have roman page numbering
# * remaining parts are numbered per section (i.e. 1-1, 1-2, etc.)
#
sub MifBook {
    local(*book, $number_per_component) = @_;
    local(@mif);
    local(@flds, %values, $i);
    local($partfile, $type);
    local($suffix, @tags, %settings);
    local($j);
    local($sectnum, $chapter_cnt, $appendix_cnt);

    # Build the title
    $title = sprintf(" # Generated by %s %s",
            $app_product_name, $app_product_version);
    @mif = ($title);

    # Add the paragraph catalog so that the PDF table of contents works
    #push(@mif, &_MifParasToText(*_mif_tpl_paras));

    # Process the list of parts
    @flds = &TableFields($book[0]);
    $chapter_cnt = 0;
    $appendix_cnt = 0;
    for ($i = 1; $i <= $#book; $i++) {

        # Get the attributes
        %values = &TableRecSplit(*flds, $book[$i]);
        $partfile = $values{'Part'};
        $type = $values{'Type'};

        # For derived components, get the suffix, list of tags and settings.
        $suffix = '';
        @tags = ();
        %settings = ();
        if ($type eq 'toc') {
            $suffix = 'TOC';
            @tags = ();
            for ($j = 1; $j <= $SDF_USER'var{'DOC_TOC'}; $j++) {
                push(@tags, $SDF_USER'parastyles_to{"H$j"},
                  $SDF_USER'parastyles_to{"A$j"}, $SDF_USER'parastyles_to{"P$j"});
            }
            push(@tags, $SDF_USER'parastyles_to{"LOFT"});
            push(@tags, $SDF_USER'parastyles_to{"LOTT"});
            push(@tags, $SDF_USER'parastyles_to{"IXT"});
        }
        elsif ($type eq 'lof') {
            $suffix = 'LOF';
            @tags = ($SDF_USER'parastyles_to{"FT"});
            $settings{'StartPageSide'} = 'NextAvailableSide';
        }
        elsif ($type eq 'lot') {
            $suffix = 'LOT';
            @tags = ($SDF_USER'parastyles_to{"TT"});
            $settings{'StartPageSide'} = 'NextAvailableSide';
        }
        elsif ($type eq 'ix') {
            $suffix = 'IX';
            @tags = ('Index');
            %settings = ();
        }

        # If requested, number per component once a chapter is found
        if ($number_per_component) {
            if ($type eq 'chapter') {
                $sectnum = ++$chapter_cnt;
            }
            elsif ($type eq 'appendix') {
                $sectnum = sprintf("%c", ord('A') + $appendix_cnt++);
            }
            elsif ($type eq 'ix') {
                $sectnum = "Index";
            }
            elsif (! $_MIF_FRONT_PART{$type}) {
                $sectnum = "\u$type";
            }
            if ($sectnum ne '') {
                # Note: "\\x15 " is FrameMaker's nonbreaking hyphen
                $settings{'PageNumbering'} = 'Restart';
                $settings{'PageNumPrefix'} = "$sectnum\\x15 ";
            }
        }

        # Build result
        push(@mif, &MifBookComponent($partfile, $suffix, *tags, %settings));
    }

    # Add a closing comment (to match output as generated by Frame)
    push(@mif, "# End of Book");

    # Return result
    return @mif;
}

#
# >>Description::
# {{Y:MifBookComponent}} returns a book component object
# for {{file}}. If {{suffix}} is supplied, a derived book
# component is returned which includes derived tags for each
# member in {{@derived}}. The book attributes can be
# changed from the defaults using {{attrs}}. No checking
# is done on {{attrs}} so take care.
#
# >>Limitations::
# {{Y:MifBookComponent}} currently assumes the referenced file will
# be in the same directory as the output. i.e. only the file's
# local name (including extension) is stored.
#
sub MifBookComponent {
    local($file, $suffix, *derived, %attrs) = @_;
    local(@result);
    local(%book_attrs);
    local($dir, $base, $ext, $short_name, $tag);
    local($derive_type);

    # Generate the book attributes to be used
    %book_attrs = %_MIF_DFLT_BOOK_ATTRS;
    @book_attrs{keys %attrs} = values %attrs;

    # Build the header
    ($dir, $base, $ext) = &NameSplit($file);
    $short_name = &NameJoin('', $base, $ext);
    @result = ("%s'>",
      $short_name));

    # Add the derived stuff, if any
    $derive_type = $suffix eq 'IX' ? 'IDX' : $suffix;
    if ($suffix) {
        push(@result, " ",
          " ",
          " ");
        for $tag (@derived) {
            push(@result, " ");
        }
    }

    # Add the attributes
    push(@result,
      sprintf(" ", $book_attrs{'StartPageSide'}),
      sprintf(" ", $book_attrs{'PageNumbering'}),
      sprintf(" ", $book_attrs{'PgfNumbering'}),
      sprintf(" ", $book_attrs{'PageNumPrefix'}),
      sprintf(" ", $book_attrs{'PageNumSuffix'}),
      sprintf(" ", $book_attrs{'DefaultPrint'}),
      sprintf(" ", $book_attrs{'DefaultApply'}));

    # Add more derived stuff, if applicable.
    # Note that we add this here rather than above
    # to keep the same ordering as Frame uses.
    if ($suffix) {
        push(@result, " ");
    }

    # End the object
    push(@result, "> # end of BookComponent");
    
    # Return result
    return @result;
}

# package return value
1;
xt/;
    return $cname;
}

#
# >>_Description::
# {{Y:_MifBookBuild}} builds a book from information collected
# during the generation of components.
#
sub _MifBookBuild sdf-2.001/perllib/sdf/apiperl.pl010064400042570001753000000072530661420513700163270ustar00iancmtr00000400000236# $Id$
$VERSION{''.__FILE__} = '$Revision$';
#
# >>Title::     Perl API Extraction Driver
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# This library provides a driver for extracting the API from
# [[Perl]] libraries.
#
# >>Description::
#
# >>Limitations::
#
# >>Resources::
#
# >>Implementation::
#

##### Constants #####

##### Variables #####
$_perl_cnt = 0;

##### Routines #####

#
# >>Description::
# {{Y:PerlFetch}} returns ($success, @records). {{success}} is 1
# if the file is opened successfully. Each record is a perl
# line of code. i.e. blank lines are removed.
#
sub PerlFetch {
    local($file) = @_;
    local($success, @records);
    local(
      $strm,
      $state
    );

    # Get the input stream
    $strm = sprintf("perl_s%d", $_perl_cnt++);

    # Open the file
    $success = open($strm, $file);

    # Input the records
    @records = ();
    if ($success) {

        $state = 0;
        perl_record:
        while (<$strm>) {

            # remove the trailing new-line
            chop($_);

            # skip blank lines
            if (/^\s*$/) {
                $state = 0;
                next;
            }

            push(@records, $_);
        }
        close($strm);

    }

    # return results
    return ($success, @records);
}

#
# >>Description::
# {{Y:PerlSymbols}} returns the list of perl symbols in a file.
# Supported symbol types are:
#
# * {{sub}} - subroutines
# * {{var}} - variables
#
# If {{symbol_type}} is supplied, only symbols of those types are
# returned. Otherwise, all symbols are returned. If {{pattern}} is
# supplied, only symbols matching that pattern are returned.
# Each symbol is returned as a record in the format:
#
# =     symbol_type:name:result:parameters
#
# The {{result}} and {{parameters}} fields are only present for
# subroutine symbols.
#
# >>Limitations::
# {{Y:PerlSymbols}} doesn't handle packages yet. i.e. doesn't append
# current package name to the front of each name.
#
sub PerlSymbols {
    local(*perl, $pattern, @symbol_type) = @_;
    local(@symbol);
    local($i, $sub_name, $sub_args, $sub_result);
    local($get_subs, $get_vars);
    local($var_name);

    # Decide on what symbols to extract
    if (@symbol_type) {
        $get_subs = grep(/^sub$/, @symbol_type);
        $get_vars = grep(/^var$/, @symbol_type);
    }
    else {
        $get_subs = 1;
        $get_vars = 1;
    }

    # Extract Interface
    line:
    for ($i = 0; $i < $#perl - 1; $i++) {

        if ($get_subs && $perl[$i] =~ /^sub\s+(\w+)\s*\{/) {
            $sub_name = $1;
            if ($pattern && $sub_name !~ /$pattern/) {
                next line;
            }
            $perl[$i + 1] =~ /local\((.*)\)\s*\=\s*\@\_\;/;
            $sub_args = $1;
            $perl[$i + 2] =~ /local\((.*)\)\s*\;/;
            $sub_result = $1;
            if ($sub_result =~ /,/) {
                $sub_result = "($sub_result)";
            }
            push(@symbol, join(':', 'sub', $sub_name,
              $sub_result, $sub_args));
            $i += 2;
        }
        elsif ($get_vars && $perl[$i] =~ /^([\$\@\%])(\w+)\s+/) {
            $var_type = $1;
            $var_name = $2;
            if ($pattern && $var_name !~ /$pattern/) {
                next line;
            }
            push(@symbol, join(':', 'var', "$var_type$var_name"));
        }
    }

    # return result
    return @symbol;
}

# package return value
1;
You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# This library provides a driver for esdf-2.001/perllib/sdf/values.pl010064400042570001753000000174550661420513700161770ustar00iancmtr00000400000236# $Id$
$VERSION{''.__FILE__} = '$Revision$';
#
# >>Title::     SDF Values Library
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 28-Aug-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# This library provides the built-in value subroutines for
# [[SDF]] files.
#
# >>Description::
# Value functions are used to calculate derived attributes of a class.
# Values should be accessed via the {{SUB:Value}} subroutine.
# The interface of a value subroutine is:
#
# =     $value = class_attr_Value($name, $view);
#
# If a class-attr-specific routine is not found, {{SUB:Value}} looks for
# a class-specific routine. Its interface is:
#
# =     $value = class_Value($attr, $name, $view);
#
# >>Limitations::
#
# >>Resources::
#
# >>Implementation::
#


# Switch to the user package
package SDF_USER;

##### Constants #####

# Useful constants
$SECONDS_PER_DAY = 3600 * 24;

##### Variables #####


##### References #####

# Generate a "print document" icon (if the PostScript file exists)
sub references_Printdoc_Value {
    local($name, $view) = @_;
#   local($result);
    local($jump);
    local($root);
    local($back);
    local($title);

    # Get the filename and check it exists
    $jump = &Value("references", $name, "Jump", $view);
    $jump = &'NameSubExt($jump, "ps");
    return '' unless -f $jump;

    # Build the cgi call, using DIR_ABS_URL to get the absolute URL of
    # the directory ultimately holding this file. (This is required
    # because the CGI script doesn't have the same position in the
    # URL tree as the documents do.) DIR_ABS_URL is also provided
    # for backwards comptability.
    $root = $var{'PRINTDOC_ROOT'};
    $root = $var{'DIR_ABS_URL'} if $root eq '';
    $back = $var{'PRINTDOC_BACK'};
    $back = "$root$var{'DOC_BASE'}.html" if $back eq '';
    $title = &Value("references", $name, "Document", $view);
    $title =~ s/ /%20/g;
    $jump = "/cgi-bin/printdoc?$root$jump%20$back%20$title";
    return "{{IMPORT[alt=\"(PRINT)\";jump=\"$jump\";base='$var{'IMAGES_BASE'}';border] printer.gif}}";
}

# Generate a Printer icon - old name for Printdoc
sub references_Printer_Value {
    local($name, $view) = @_;
#   local($result);

    return &references_Printdoc_Value($name, $view);
}

#
# Default value routine for references:
# If the attribute is all uppercase (e.g. TXT), generate an image
# for a file with that (lowercase) extension (e.g. mydoc.txt),
# using an image matching the extension name (e.g. txt.gif).
# Likewise, an all uppercase attribute with a leading underscore (e.g. _DIR)
# generates an image for a HTML file with that suffix (e.g. mydoc_dir.html)
# using an image matching the extension name (e.g. dir.gif).
#
sub references_Value {
    local($attr, $name, $view) = @_;
#   local($result);

    return AttrToFile($attr, $name, 'references', $view);
}

# This routine maps an attribute to a filename.
# See the comments above references_Value for details.
sub AttrToFile {
    local($attr, $name, $class, $view) = @_;
    local($suffix);
    local($image);
    local($jump);
    local($dir, $base, $ext);

    # Do nothing unless the attribute matches the necessary pattern
    return (0) unless $attr =~ /^(_?)([A-Z0-9]+)$/;
    $suffix = $1 ne '';
    $image = $2;
    $image =~ tr/A-Z/a-z/;

    # Get the filename
    $jump = &Value($class, $name, "Jump", $view);
    if ($suffix) {
        ($dir, $base, $ext) = &'NameSplit($jump);
        $jump = &'NameJoin($dir, $base . "_$image", $ext);
    }
    else {
        $jump = &'NameSubExt($jump, $image);
    }

    # If the name looks like a URL, assume it exists.
    # Otherwise, we assume it a filename and only return an icon
    # if that file exists.
    return (1, '') unless ($jump =~ /^\w+:/ || -f $jump);

    # Build the result
    return (1,
      "{{IMPORT[alt=\"($attr)\";jump=\"$jump\";base='$var{'IMAGES_BASE'}'] $image.gif}}");
}

# Generate a PS icon (if the PostScript file exists)
sub references_PS_Value {
    local($name, $view) = @_;
#   local($result);
    local($jump);

    # Get the filename
    $jump = &Value("references", $name, "Jump", $view);
    $jump = &'NameSubExt($jump, "ps");

    # If the name looks like a URL, assume it exists.
    # Otherwise, we assume it a filename and only return an icon
    # if that file exists.
    return '' unless ($jump =~ /^\w+:/ || -f $jump);

    # Build the result
    return "{{IMPORT[alt=\"(PS)\";jump=\"$jump\";base='$var{'IMAGES_BASE'}';border] postscript.gif}}";
}

# Generate a PDF icon (if the PDF file exists)
sub references_PDF_Value {
    local($name, $view) = @_;
#   local($result);
    local($jump);

    # Get the filename
    $jump = &Value("references", $name, "Jump", $view);
    $jump = &'NameSubExt($jump, "pdf");

    # If the name looks like a URL, assume it exists.
    # Otherwise, we assume it a filename and only return an icon
    # if that file exists.
    return '' unless ($jump =~ /^\w+:/ || -f $jump);

    # Build the result
    return "{{IMPORT[alt=\"(PDF)\";jump=\"$jump\";base='$var{'IMAGES_BASE'}'] pdf.gif}}";
}

# Generate a TXT icon (if the text file exists)
sub references_TXT_Value {
    local($name, $view) = @_;
#   local($result);
    local($jump);

    # Get the filename
    $jump = &Value("references", $name, "Jump", $view);
    $jump = &'NameSubExt($jump, "txt");

    # If the name looks like a URL, assume it exists.
    # Otherwise, we assume it a filename and only return an icon
    # if that file exists.
    return '' unless ($jump =~ /^\w+:/ || -f $jump);

    # Build the result
    return "{{IMPORT[alt=\"(TXT)\";jump=\"$jump\";base='$var{'IMAGES_BASE'}'] text.gif}}";
}

# Generate a DOC icon (if the .doc file exists)
sub references_DOC_Value {
    local($name, $view) = @_;
#   local($result);
    local($jump);

    # Get the filename
    $jump = &Value("references", $name, "Jump", $view);
    $jump = &'NameSubExt($jump, "doc");

    # If the name looks like a URL, assume it exists.
    # Otherwise, we assume it a filename and only return an icon
    # if that file exists.
    return '' unless ($jump =~ /^\w+:/ || -f $jump);

    # Build the result
    return "{{IMPORT[alt=\"(DOC)\";jump=\"$jump\";base='$var{'IMAGES_BASE'}'] doc.gif}}";
}

# Get the last modified date (unformatted)
sub references_Date_Value {
    local($name, $view) = @_;
    local($modtime);
    local($jump);

    # Get the filename and check it exists
    $jump = &Value("references", $name, "Jump", $view);
    return '' unless -f $jump;

    # Build the result
    $modtime = time - (-M $jump) * $SECONDS_PER_DAY;
    return $modtime;
}

# Get the page count (formatted)
sub references_Pages_Value {
    local($name, $view) = @_;
    local($pages);
    local($jump);
    local($trailers);

    # Get the filename and check it exists
    $jump = &Value("references", $name, "Jump", $view);
    $jump = &'NameSubExt($jump, "ps");
    return '' unless -f $jump;

    # build the result
    if (open(PSSTRM, $jump)) {
        $trailers = 0;
        while () {
            # Assume the page count is at the end as there
            # may be embedded PostScript found first
            if (/^%%Pages:\s+(\d+)/) {
                $pages = $1;
            }

            # Count the page trailers as Word doesn't support %%Pages
            if (/^%%PageTrailer/) {
                $trailers++;
            }
        }
        close(PSSTRM);

        # Format the result. If the page count is zero, guess the
        # count from the PageTrailer count
        $pages = $trailers if $pages == 0;
        $pages .= $pages == 1 ? " page" : " pages";
    }
    else {
        $pages = '';
    }

    # Return result
    return $pages;
}

# package return value
1;
sdf-2.001/perllib/sdf/tohtml.pl010064400042570001753000001356720672221055300162070ustar00iancmtr00000400000236# $Id$
$VERSION{''.__FILE__} = '$Revision$';
#
# >>Title::     HTML Format Driver
#
# >>Copyright::
# Copyright (c) 1992-1999, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#
# >>Purpose::
# This library provides an [[SDF_DRIVER]] which generates
# [[HTML]] files.
#
# >>Description::
#
# >>Limitations::
# Lists which have ordered items, then unordered items, then
# ordered items all at the same level are output as three
# separate lists. As a result, the numbering in the third list
# restarts even if you don't want it to.
#
# After hypertext jumps have been added throughout a paragraph,
# we should go back over the paragraph and unnest any nested jumps.
#
# >>Resources::
#
# >>Implementation::
#

##### Constants #####

# Mapping table for characters
%_HTML_CHAR = (
    'bullet',       '.',
    'c',            '© ',
    'cent',         '¢ ',
    'dagger',       '^',
    'doubledagger', '#',
    'emdash',       '--',
    'endash',       '-',
    'emspace',      '  ',
    'enspace',      '  ',
    'lbrace',       '{',
    'lbracket',     '[',
    'nbdash',       '-',
    'nbspace',      '  ',
    'nl',           '
      ',
    'pound',        '£ ',
    'r',            '® ',
    'rbrace',       '}',
    'rbracket',     ']',
    'tab',          '	 ',
    'tm',           '™ ',       # not sure about this
    'yen',          '¥ ',
);

# Directive mapping table
%_HTML_HANDLER = (
    'tuning',         '_HtmlHandlerTuning',
    'endtuning',      '_HtmlHandlerEndTuning',
    'table',            '_HtmlHandlerTable',
    'row',              '_HtmlHandlerRow',
    'cell',             '_HtmlHandlerCell',
    'endtable',         '_HtmlHandlerEndTable',
    'import',           '_HtmlHandlerImport',
    'inline',           '_HtmlHandlerInline',
    'output',           '_HtmlHandlerOutput',
    'object',           '_HtmlHandlerObject',
    'stylesheet',       '_HtmlHandlerStyleSheet',
    'div',              '_HtmlHandlerDiv',
    'enddiv',           '_HtmlHandlerEndDiv',
);

# Phrase directive mapping table
%_HTML_PHRASE_HANDLER = (
    'char',             '_HtmlPhraseHandlerChar',
    'import',           '_HtmlPhraseHandlerImport',
    'inline',           '_HtmlPhraseHandlerInline',
    'variable',         '_HtmlPhraseHandlerVariable',
);

# Table states
$_HTML_INTABLE = 1;
$_HTML_INROW   = 2;
$_HTML_INCELL  = 3;

# Attribute types - this is used to decide if an attribute is legal,
# and if it is, whether to quote the value (string) or not.
# 'class' types get made into a class attribute.
%_HTML_ATTR_TYPES = (
    'align',    'string',
    'alt',      'string',
    'border',   'integer',
    'class',    'string',
    'changed',  'class',
);

# Attributes mapping to styles
%_HTML_STYLE_MAP = (
    'family',   'font-family: %s',
    'size',     'font-size: %s',
    'bold',     'font-weight: bold',
    'italics',  'font-style: italic',
    'underline','text-decoration: underline',
    'color',    'color: %s',
    'bgcolor',  'background-color: %s',
#   'align',    'text-align: %s',
    'first',    'text-indent: %s',
    'left',     'margin-left: %s',
    'right',    'margin-right: %s',
);

##### Variables #####

# Table/cell states
@_html_tbl_state = ();
@_html_tbl_endtokens = ();
@_html_tbl_previndent = ();
$_html_cell_paracnt = ();

# Stack of topic file offsets and filenames
@_html_topic_offset = ();
@_html_topic_file = ();

# Current topic and level
$_html_topic = '';
$_html_topic_level = 0;

# File/text combinations which start a new topic
%_html_topic_start = ();

# File/text lookup to a jump target
%_html_jump_id = ();

## Ordered list state
#$_html_in_olist = 0;

# Topic counter for building derived topic names
$_html_topic_cntr = 0;

# Meta information for this file
@_html_meta = ();

# Links this file
@_html_links = ();

# Stylesheet for this file
@_html_stylesheet = ();

# Counts for each class attribute
%_html_class_count = ();

# Division stack (contents is the name (i.e. class) of opened divisions)
@_html_divs = ();

# Title division text
@_html_title_div = ();

##### Routines #####

#
# >>Description::
# {{Y:HtmlFormat}} is an SDF driver which outputs HTML.
#
sub HtmlFormat {
    local(*data) = @_;
    local(@result);
    local(@contents);
    local(@data2, @contents2, %var2, @result2);
    local($msg_cursor, %msg_counts);
    local($main);
    local(@topics_table, @jumps_table);

    # Init global data
    $_html_topic = '';
    $_html_topic_level = 0;
    $_html_topic_cntr = 0;
    %_html_topic_start = ();
    %_html_jump_id = ();
    @_html_meta = ();
    @_html_links = ();
    @_html_stylesheet = ();
    %_html_class_count = ();
    @_html_divs = ();
    @_html_title_div = ();

    # If we're building topics, save the data for a second pass later
    if ($SDF_USER'var{'HTML_TOPICS_MODE'}) {
        @data2 = @data;

        # Get the current message cursor - we skip the second pass
        # if errors are found
        $msg_cursor = &AppMsgNextIndex();

    }

    # Format the paragraphs
    @contents = ();
    @result = &_HtmlFormatSection(*data, *contents);

    # Save away any unclosed topics
    while (@_html_topic_file) {
        &_HtmlHandlerOutput(*result, '-');
    }

    # Build the final result.
    ## Note that we must do this AFTER the subtopics stuff in order
    ## to get the next/previous topic data needed for the default
    ## header/footer.
    @result = &_HtmlFinalise(*result, *contents);

    # If there were no problems in the first pass,
    # build the sub-topics, if requested
    %msg_counts = &AppMsgCounts($msg_cursor);
    if ($msg_counts{'error'} || $msg_counts{'abort'} || $msg_counts{'fatal'} ) {
        # do nothing
    }
    elsif ($SDF_USER'var{'HTML_TOPICS_MODE'}) {

        $main = $SDF_USER'var{'DOC_BASE'};
        @topics_table = ();
        @jumps_table = ();
        &_HtmlBuildTopicsData($main, *topics_table, *jumps_table);

        # Save the topics and jump data, so users can (eventually) rebuild
        # just a single topic.
        if ($SDF_USER'var{'HTML_SDJ'}) {
            &_HtmlSaveTopicsData($main, *topics_table, *jumps_table);
        }

        # Initialise things ready for the next pass
        %var2 = %convert_var;      # get the original set of variables
        $var2{'HTML_MAIN_TITLE'} = $SDF_USER'var{'DOC_TITLE'};
        $var2{'HTML_URL_CONTENTS'} = $SDF_USER'var{'DOC_BASE'} . ".html";
        $var2{'HTML_TOPICS_MODE'} = 0;
        $var2{'HTML_SUBTOPICS_MODE'} = 1;
        &SdfInit(*var2);
        &SDF_USER'topics_Filter(*topics_table, 'data', 1);
        &SDF_USER'jumps_Filter(*jumps_table, 'data', 1);

        # Build the sub-topics
        @contents2 = ();
#printf "DATA2:\n%s\nENDDATA2\n", join("\n", @data2);
        @result2 = &_HtmlFormatSection(*data2, *contents2);

        # Save away any unclosed topics
        while (@_html_topic_file) {
            &_HtmlHandlerOutput(*result2, '-');
        }
    }

    # Return the result
    return @result;
}

#
# >>_Description::
# {{Y:_HtmlBuildTopicsData}} builds the topics data
# needed for sub-topic building.
#
sub _HtmlBuildTopicsData {
    local($main, *topics_table, *jumps_table) = @_;
#   local();
    local($topic, $level, $label, $next, $prev, $up, %last_at);
    local($jump, $physical);

    # Ensure that the main topic is first and that it has the highest level
    #if ($SDF_USER'topics[0] eq $main) {
    #    $SDF_USER'levels[0] = 0;
    #}
    #else {
    #    unshift(@SDF_USER'topics, pop(@SDF_USER'topics));
    #    pop(@SDF_USER'levels);
    #    unshift(@SDF_USER'levels, 0);
    #}
    unshift(@SDF_USER'topics, $main);
    unshift(@SDF_USER'levels, 0);

    # Build the topics table
    @topics_table = ("Topic|Label|Level|Next|Prev|Up");
    $prev = $SDF_USER'topics[$#SDF_USER'topics];
    %last_at = ();
    for ($i = 0; $i <= $#SDF_USER'topics; $i++) {
        $topic = $SDF_USER'topics[$i];
        $level = $SDF_USER'levels[$i];
        $label = $SDF_USER'topic_label{$topic};
        $next  = $i < $#SDF_USER'topics ? $SDF_USER'topics[$i + 1] : $SDF_USER'topics[0];
        $up    = $last_at{$level - 1};
        push(@topics_table, "$topic|$label|$level|$next|$prev|$up");

        # Save state for later iterations
        $prev = $topic;
        $last_at{$level} = $topic;
    }

    # Build the jumps table
    @jumps_table = ("Jump|Physical");
    for $jump (sort keys %SDF_USER'jump) {
        $physical = $SDF_USER'jump{$jump};
        push(@jumps_table, "$jump|$physical");
    }
}

#
# >>_Description::
# {{Y:_HtmlSaveTopicsData}} dumps topic and jump data to a file.
#
sub _HtmlSaveTopicsData {
    local($main, *topics_table, *jumps_table) = @_;
#   local();
    local($file);

    # Save the topic and jump data
    $file = &NameJoin('', $main, 'sdj');
    unless (open(SDM, ">$file")) {
        &AppMsg("warning", "unable to update topics file '$file'");
    }
    else {
        # Output a warning message at the top
        print SDM "# WARNING: This file is automatically generated\n";
        print SDM "# by SDF, so any changes you make will be lost!\n";

        # Dump the topics data
        print SDM "\n";
        print SDM "!block topics; data\n";
        print SDM join("\n", @topics_table), "\n";
        print SDM "!endblock\n";

        # Dump the jumps data
        print SDM "\n";
        print SDM "!block jumps\n";
        print SDM join("\n", @jumps_table), "\n";
        print SDM "!endblock\n";

        # Close the file
        close(SDM);
    }
}

#
# >>_Description::
# {{Y:_HtmlFormatSection}} formats a set of SDF paragraphs into HTML.
# If a parameter is passed to contents, then that array is populated
# with a generated Table of Contents. If {{division}} is set, the
# result is placed in a DIV element with that class.
#
sub _HtmlFormatSection {
    local(*data, *contents, $division) = @_;
    local(@result);
    local($prev_tag, $prev_indent);
    local($para_tag, $para_text, %para_attrs);
    local($directive);

    ## Reset the ordered list state. I'm not absolutely sure that
    ## this is the best place to do this, but TJH had it here
    ## and I trust him (most of the time :-)
    #$_html_in_olist = 0;

    # Process the paragraphs
    @result = $division eq '' ? () : ("
      ");
    $prev_tag = '';
    $prev_indent = '';
    while (($para_text, $para_tag, %para_attrs) = &SdfNextPara(*data)) {

        # handle directives
        if ($para_tag =~ /^__(\w+)$/) {
            $directive = $_HTML_HANDLER{$1};
            if (defined &$directive) {
                &$directive(*result, $para_text, %para_attrs);
            }
            else {
                &AppTrace("html", 5, "ignoring internal directive '$1'");
            }
            next;
        }

        # Add the paragraph
        &_HtmlParaAdd(*result, $para_tag, $para_text, *para_attrs, $prev_tag,
          $prev_indent, *contents);
    }

    # Do this stuff before starting next loop iteration
    continue {
        $prev_tag = $para_tag;
        $prev_indent = $para_attrs{'in'};
    }

    ## Filter out the dummy tag we use to get lists right
    #for ($i = 0; $i < $#result; $i++) {
    #    $result[$i] =~ s###g;
    #}

    # Close off the DIV element, if any
    push(@result, "
      ") if $division ne '';

    # Return result
    return @result;
}
       
#
# >>_Description::
# {{Y:_HtmlParaAdd}} adds a paragraph.
#
sub _HtmlParaAdd {
    local(*result, $para_tag, $para_text, *para_attrs, $prev_tag, $prev_indent, *contents) = @_;
#   local();
    local($is_example);
    local($para_fmt);
    local($para_override);
    local($para);
    local($hdg_level);
    local($toc_jump);
    local($label);
    local($indent);
    local($list_tag);
    local($note_line_width);
    local($note_attrs);

    # Get the example flag
    $is_example = $SDF_USER'parastyles_category{$para_tag} eq 'example';

    # Enumerated lists are the same as list paragraphs at the previous level,
    # except that we bold the text
    if ($para_tag =~ /^LI(\d)$/) {
        $para_tag = $1 > 1 ? "L" . ($1 - 1) : 'N';
        $para_attrs{'bold'} = 1;
    }

    # Get the target format name
    $para_fmt = $SDF_USER'parastyles_to{$para_tag};
    $para_fmt = $is_example ? 'PRE' : 'P' if $para_fmt eq '';

    # Map the attributes
    &SdfAttrMap(*para_attrs, 'html', *SDF_USER'paraattrs_to,
      *SDF_USER'paraattrs_map, *SDF_USER'paraattrs_attrs,
      $SDF_USER'parastyles_attrs{$para_tag});

    # Build the Table of Contents as we go
    $toc_jump = '';
    if ($para_tag =~ /^([HAP])(\d)$/) {
        $hdg_level = $2;
        my $orig_para_text = $para_text;
        $para_text = &SdfHeadingPrefix($1, $2) . $para_text;
        if ($SDF_USER'var{'HTML_SUBTOPICS_MODE'}) {
            $para_fmt = "H" . substr($para_attrs{'orig_style'}, 1);
        }
        else {
            $para_fmt = "H" . $hdg_level;
        }
        if ($hdg_level <= $SDF_USER'var{'DOC_TOC'} && !$para_attrs{'notoc'}) {

            # Build a plain list in SDF. If we're building topics and we're
            # building the contents, make sure the jumps go to the right spot.
            if ($SDF_USER'var{'HTML_TOPICS_MODE'}) {
                #$toc_jump = &NameJoin('', $SDF_USER'var{'FILE_BASE'}, "html");
                #if ($SDF_USER'topic_label{$SDF_USER'var{'FILE_BASE'}} ne $para_text) {
                #    $toc_jump .= "#" . $para_attrs{'id'};
                #}
                $toc_jump = $_html_jump_id{$SDF_USER'var{'FILE_BASE'},$orig_para_text};
            }
            else {
                $toc_jump = "#" . $para_attrs{'id'};
                $toc_jump = "#HDR" . ($#contents + 1) if $toc_jump eq '#';
            }
            #$toc_jump =~ s/(['\\])/\\$1/g;
            #push(@contents, "L${hdg_level}" . "[jump='$toc_jump']$para_text");
            push(@contents, &SdfJoin("L${hdg_level}", $para_text,
                "jump", $toc_jump));
        }
    }

    # Handle lists
    elsif ($para_tag =~ /^(L[FUN]?)(\d)$/) {
        $para_attrs{'in'} = $2;
        if ($1 eq 'LU') {
            $para_fmt = 'UL';
        }
        elsif ($1 eq 'L') {
            $para_fmt = 'UL PLAIN';
        }
        else {
            $para_fmt = 'OL';
        }
    }

    # Handle user-defined formatting
    if ($para_attrs{'out_style'}) {
        $para_fmt = $para_attrs{'out_style'};
        delete $para_attrs{'out_style'};
    }

    # Prepend the label, if any (replacing tabs with spaces)
    $label = $para_attrs{'label'};
    $label = 'Note: ' if ($para_tag eq 'Note' || $para_tag eq 'NB') &&
             $label eq '';
    $label =~ s/\\t/ /g;
    $para_text = "{{2:$label}}$para_text" if $label ne '';

    # Indent examples, if necessary
    if ($is_example && $para_attrs{'in'}) {
        $para_text = " " x ($para_attrs{'in'} * 4) . $para_text;
        delete $para_attrs{'in'};
    }

    # Format the paragraph body
    if ($para_attrs{'verbatim'}) {
        $para = &_HtmlEscape($para_text);
        delete $para_attrs{'verbatim'};
    }
    else {
        $para = &_HtmlParaText($para_text);
    }

    # Add surrounding lines for a note
    $note_line_width = 80;              # Hard-coded for now
    $note_attrs = "WIDTH=\"$note_line_width%\" ALIGN=\"Left\"";
    if ($para_tag eq 'Note') {
        $para = "
      \n$para\n
      ";
    }
    elsif ($para_tag eq 'NB') {
        $para = "
      \n$para";
    }
    elsif ($para_tag eq 'NE') {
        $para = "
      ";
    }

    # Empty cells look ugly so the hack below
    # puts a space in empty paragraphs inside cells.
    # Unfortunately, this means truly empty paragraphs
    # inside cells are not handled. Is this an issue?
    $para = ' ' if $para eq '' && @_html_tbl_state;

    ## Examples with change bars currently come out as separate
    ## paragraphs - this fixes the problem, for now
    #delete $para_attrs{'changed'} if $para_attrs{'changed'};

    # Build result
    $indent = $para_attrs{'in'};
    #if ($is_example && $para_tag eq $prev_tag && !%para_attrs) {
    if ($is_example && $para_tag eq $prev_tag) {
        &_HtmlParaAppend(*result, $para);
    }
    elsif ($indent && $prev_indent != 0) {
        $item = &_HtmlElement($para_fmt, $para, %para_attrs);
        &_HtmlItemAppend(*result, $item, $indent, $prev_indent, $para_tag,
          $prev_tag, *para_attrs);
    }

    # If the first paragraph inside a table cell is a plain paragraph,
    # then we do not surrounded it by 
       and 
       as
    # Netscape then outputs too much whitespace.
    elsif (@_html_tbl_state && $_html_cell_paracnt++ == 0 && $para_fmt eq 'P') {
        push(@result, $para);
    }
    else {
        $para = &_HtmlElement($para_fmt, $para, %para_attrs);

        # Handle lists which begin at an indent greater than 1
        $list_tag = substr($para, 1, 2) if $indent;
        while (--$indent > 0) {
            $para = "<$list_tag>$para";
        }

        # Prepend the table of contents jump id, if necessary
        if ($toc_jump =~ /^#HDR\d+$/) {
            $para = " \n$para";
        }
        push(@result, $para);
    }
}

#
# >>_Description::
# {{Y:_HtmlParaText}} converts SDF paragraph text into HTML.
# 
sub _HtmlParaText {
    local($para_text) = @_;
    local($para);
    local($state);
    local($sect_type, $char_tag, $text, %sect_attrs);
    local($url);
    local($added_anchors);
    local(@char_fonts);
    local($char_font);
    local($directive);
    local($char_attrs);

    # Process the text
    $para = '';
    $state = 0;
    while (($sect_type, $text, $char_tag, %sect_attrs) =
      &SdfNextSection(*para_text, *state)) {

        # Build the paragraph
        if ($sect_type eq 'string') {
            $para .= &_HtmlEscape($text);
        }

        elsif ($sect_type eq 'phrase') {

            # Expand out link phrases
            if ($char_tag eq 'L') {
                ($text, $url) = &SDF_USER'ExpandLink($text);
                $sect_attrs{'jump'} = $url;
            }

            # Escape any special characters
            $text = &_HtmlEscape($text);

            # Expand non-breaking spaces, if necessary
            if ($char_tag eq 'S') {
                $text =~ s/ / /g;
            }

            # Empty cells look ugly so the hack below
            # puts a space in empty phrases inside cells.
            # Unfortunately, this means truly empty phrases
            # inside cells are not handled. Is this an issue?
            $text = ' ' if $text eq '' && @_html_tbl_state;

            # If this is a jump, ignore the style (i.e. make it 'as-is')
            #$char_tag = 'A' if $sect_attrs{'jump'} ne '';

            # Add hypertext stuff
            $added_anchors = &_HtmlAddAnchors(*text, *sect_attrs);

            # Process formatting attributes
            &SdfAttrMap(*sect_attrs, 'html', *SDF_USER'phraseattrs_to,
              *SDF_USER'phraseattrs_map, *SDF_USER'phraseattrs_attrs,
              $SDF_USER'phrasestyles_attrs{$char_tag});
            $char_attrs = &_HtmlAttr(*sect_attrs);
#print STDERR "char_attrs is $char_attrs<\n";

            # Map the font
            $char_font = $SDF_USER'phrasestyles_to{$char_tag};
            $char_font = $char_tag if $char_font eq '' && !$added_anchors;

            # If attributes are specified for an SDF font, use a SPAN
            if ($char_font =~ /^SDF/ && $char_attrs ne '') {
                $char_font = 'SPAN';
            }

            # Add the text for this phrase
            push(@char_fonts, $char_font);
            if ($char_font ne '' && $char_font !~ /^SDF/) {
                $para .= "<$char_font$char_attrs>$text";
            }
            else {
                $para .= $text;
            }
        }

        elsif ($sect_type eq 'phrase_end') {
            $char_font = pop(@char_fonts);
            $para .= "" if $char_font ne '' && $char_font !~ /^SDF/;
        }

        elsif ($sect_type eq 'special') {
            $directive = $_HTML_PHRASE_HANDLER{$char_tag};
            if (defined &$directive) {
                &$directive(*para, $text, %sect_attrs);
            }
            else {
                &AppMsg("warning", "ignoring special phrase '$1' in HTML driver");
            }
        }

        else {
            &AppMsg("warning", "unknown section type '$sect_type' in HTML driver");
        }
    }

    # Return result
    return $para;
}

#
# >>_Description::
# {{Y:_HtmlFinalise}} generates the final HTML file.
#
sub _HtmlFinalise {
    local(*body, *contents) = @_;
#   local(@result);
    local($title, @sdf_title, @title);
    local($version, @head);
    local($body);

    # Build the BODY opening stuff
    $body = "BODY";
    $body .= sprintf(' BACKGROUND="%s"', $SDF_USER'var{"HTML_BG_IMAGE"}) if
                                  defined($SDF_USER'var{"HTML_BG_IMAGE"});
    $body .= sprintf(' BGPROPERTIES="FIXED"') if $SDF_USER'var{"HTML_BG_FIXED"};
    $body .= sprintf(' BGCOLOR="%s"', $SDF_USER'var{"HTML_BG_COLOR"}) if
                               defined($SDF_USER'var{"HTML_BG_COLOR"});
    $body .= sprintf(' TEXT="%s"',    $SDF_USER'var{"HTML_TEXT_COLOR"}) if
                               defined($SDF_USER'var{"HTML_TEXT_COLOR"});
    $body .= sprintf(' LINK="%s"',    $SDF_USER'var{"HTML_LINK_COLOR"}) if
                               defined($SDF_USER'var{"HTML_LINK_COLOR"});
    $body .= sprintf(' VLINK="%s"',   $SDF_USER'var{"HTML_VLINK_COLOR"}) if
                               defined($SDF_USER'var{"HTML_VLINK_COLOR"});

    # Convert the title, if any, to HTML
    $title = $SDF_USER'var{'HTML_TITLE'};
    $title = $SDF_USER'var{'DOC_TITLE'} if !defined($title);
    if ($title) {
        @sdf_title = ("TITLE:$title");
        @title = &_HtmlFormatSection(*sdf_title, *dummy);
    }
    else {
        @title = ();
    }

    # Prepend some useful things to the stylesheet, if applicable
    if ($_html_class_count{'changed'}) {
        my $changed_color = $SDF_USER'var{'HTML_CHANGED_COLOR'};
        unshift(@_html_stylesheet,
          ".changed {background-color: $changed_color}");
    }

    # Build the HEAD element (and append BODY opening)
    $version = $SDF_USER'var{'SDF_VERSION'};
    @head = (
        '',
        '',
        '',
        '',
        "',
        '',
        '',
    );
    push(@head, @title) if @title;
    push(@head, @_html_meta) if @_html_meta;
    push(@head, @_html_links) if @_html_links;
    if (@_html_stylesheet) {
        push(@head,
            '',
        );
    }
    push(@head, '', "<$body>", '');

    # Build the body contents, unless we're generating an input file for
    # the HTMLDOC package
    unless ($SDF_USER'var{'HTMLDOC'}) {
        &_HtmlFinaliseBodyContents(*body, *contents);
    }

    # Return result
    push(@body, '', '', '');
    return (@head, @body);
}

#
# >>_Description::
# {{Y:_HtmlFinaliseBodyContents}} generates the final BODY contents.
#
sub _HtmlFinaliseBodyContents {
    local(*body, *contents) = @_;
#   local(@result);
    local($macro, @header, @footer);
    local(@dummy);
    local(@html_contents);
    #local($rec, $toc_posn);

    # Wrap the main body in a main division
    unshift(@body, '
      ');
    push(@body, '
      ');

    # Prepend the Table of Contents, if any
    if (@contents) {

        # Finish formatting the table of contents
        # Note: we use a filter so that experts can override things!
        &SDF_USER'toc_html_Filter(*contents);

        # Now convert it to HTML
        @html_contents = &_HtmlFormatSection(*contents, *dummy, 'contents');

        # If this is a MAIN document, make the body the contents
        # (i.e. ditch the contents). Otherwise, prepend it.
        if ($SDF_USER'var{'HTML_TOPICS_MODE'}) {
            @body = @html_contents;
        }
        else {
            unshift(@body, join("\n", @html_contents));
        }
    }

    # If this is not a topic, prepend the title division, if any
    unless ($SDF_USER'var{'HTML_SUBTOPICS_MODE'}) {
        unshift(@body, @_html_title_div);
    }

    # Convert the header, if any, to HTML
    $macro = 'HTML_HEADER';
    if ($SDF_USER'var{'HTML_SUBTOPICS_MODE'} &&
        $SDF_USER'macro{'HTML_TOPIC_HEADER'}) {
        $macro = 'HTML_TOPIC_HEADER';
    }
    if ($SDF_USER'macro{$macro} ne '') {
        @header = ("!$macro");
        unshift(@body, &_HtmlFormatSection(*header, *dummy, 'header'));
    }

    # Convert the footer, if any, to HTML
    $macro = 'HTML_FOOTER';
    if ($SDF_USER'var{'HTML_SUBTOPICS_MODE'} &&
        $SDF_USER'macro{'HTML_TOPIC_FOOTER'}) {
        $macro = 'HTML_TOPIC_FOOTER';
    }
    if ($SDF_USER'macro{$macro} ne '') {
        @footer = ("!$macro");
        push(@body, &_HtmlFormatSection(*footer, *dummy, 'footer'));
    }

    # Add the pre-header and post-footer, if any
    my $pre_header = $SDF_USER'var{'HTML_PRE_HEADER'};
    unshift(@body, $pre_header) if $pre_header ne '';
    my $post_footer = $SDF_USER'var{'HTML_POST_FOOTER'};
    push(@body, $post_footer) if $post_footer ne '';
}

#
# >>_Description::
# {{Y:_HtmlEscape}} escapes special symbols in HTML text.
# 
sub _HtmlEscape {
    local($text) = @_;
#   local($result);
    local($old_match_flag);

    # Enable multi-line matching
    $old_match_flag = $*;
    $* = 1;

    # Escape the symbols
    $text =~ s/\&/&/g;
    $text =~ s/\/>/g;
    $text =~ s/\"/"/g;

    # Reset multi-line matching flag
    $* = $old_match_flag;

    # Return result
    $text;
}

#
# >>_Description::
# {{Y:_HtmlAttr}} formats a set of attributes into HTML.
# 
sub _HtmlAttr {
    local(*attrs) = @_;
    local($html);
    local($attr, $value, $type);
    local($style);
    local($style_map);

    # get the specified style info, if any
    $style = $attrs{'style'};
    delete $attr{'style'};

    for $attr (sort keys %attrs) {

        # get the attribute value
        $value = $attrs{$attr};

        # get the attribute type & map to style info
        if ($attr =~ s/^html\.//) {
            $type = $_HTML_ATTR_TYPES{$attr};
            $type = "string" if $type eq '';
        }
        else {
            $type = $_HTML_ATTR_TYPES{$attr};
#print STDERR "attr: $attr, type: $type<\n";
        }
        $style_map = $_HTML_STYLE_MAP{$attr};
        if ($style_map ne '') {
            $style .= '; ' if $style ne '';
#           if ($attr eq 'align') {
#               if ($value eq '1' || $value eq 'Full') {
#                   $value = 'justify';
#               }
#               else {
#                   $value = "\l$value";
#               }
#           }
            $style .= sprintf($style_map, $value);
        }
        next unless $type;

        # build the result (using uppercase attribute names)
        if ($type eq 'string') {
            $attr =~ tr/a-z/A-Z/;
            $value = &_HtmlEscape($value);
            $html .= " $attr=\"" . $value . '"';
        }
        elsif ($type eq 'class') {
            $value = $attr;
            $attr = 'CLASS';
            $html .= " $attr=\"" . $value . '"';
        }
        else {
            $attr =~ tr/a-z/A-Z/;
            $html .= " $attr=$value";
        }

        # Keep some stats on classes used so we can conditionally
        # add things to the stylesheet later
        $_html_class_count{$value}++ if $attr eq 'CLASS';
    }

    # Add the style info, if any
    if ($style ne '') {
            $html .= " STYLE=\"" . &_HtmlEscape($style) . '"';
    }
        
    # Return result
    $html;
}

#
# >>_Description::
# {{Y:_HtmlElement}} formats a HTML element from a
# tag, text and set of attributes.
#
sub _HtmlElement {
    local($tag, $text, %attr) = @_;
#   local($html);

    # For preformatted sections, tags go on separate lines
    $text = "\n$text\n" if $tag eq 'PRE';

    # Add hypertext stuff
    &_HtmlAddAnchors(*text, *attr);

    # Bold the text, if requested
    if ($attr{'bold'}) {
        $text = "$text";
    }

    # For list items, add the item stuff
    #$text = "\n
    • $text" if $tag =~ /^[UOx]L$/;
    $text = "\n
    • $text" if $tag =~ /^[UO]L$/;
    if ($tag eq 'UL PLAIN') {
        $tag = 'UL';
        $text = "\n$text";
    }

    # Return result
    if ($tag eq 'HR') {
        return "<$tag>$text";
    }
    else {
        return "<$tag" . &_HtmlAttr(*attr) . ">$text";
    }
}

#
# >>_Description::
# {{Y:_HtmlAddAnchors}} adds hypertext jumps and ids to a section of text.
# of text. It returns true if anchors were added.
# 
sub _HtmlAddAnchors {
    local(*text, *attr) = @_;
    local($result);
    local($value);
    local($user_ext);
    local($old_match_flag);

    # Enable multi-line matching
    $old_match_flag = $*;
    $* = 1;

    # For hypertext jumps, surround the text. If the
    # text contains a jump, the existing jump is removed.
    if ($attr{'jump'} ne '') {

        # Get the jump value. If an extension other than html is
        # requested, change the jump value accordingly. Also,
        # we make sure than any special characters are escaped.
        $value = $attr{'jump'};
        $user_ext = $SDF_USER'var{'HTML_EXT'};
        if ($user_ext) {
            $value =~ s/\.html/.$user_ext/;
        }
        $value = &_HtmlEscape($value);

        $text =~ s/\]+\>(.*)\<\/A\>/$1/;
        $text = "$text";
        delete $attr{'jump'};
        $result++;
    }

    # For hypertext ids, surround the text if it doesn't already contain
    # a jump. Otherwise, prefix the text with a dummy target so that
    # jump and id definitions don't clash.
    if ($attr{'id'} ne '') {
        $value = &_HtmlEscape($attr{'id'});
        if ($text =~ /\ $text";
        }
        else {
            $text = "$text";
        }
        delete $attr{'id'};
        $result++;
    }

    # Reset multi-line matching flag
    $* = $old_match_flag;

    # Return result
    return $result;
}

#
# >>_Description::
# {{Y:_HtmlParaAppend}} merges {{para}} into the last paragraph
# in {{@result}}. Both paragraphs are assumed to be PREformatted.
#
sub _HtmlParaAppend {
    local(*result, $para) = @_;
#   local();

    substr($result[$#result], -6) = "$para\n
    "; } # # >>_Description:: # {{Y:_HtmlItemAppend}} merges a list item {{item}} into the current # output. The item before is assumed to be a list item too. # sub _HtmlItemAppend { local(*result, $item, $indent, $prev_indent, $para_tag, $prev_tag, *para_attrs) = @_; # local(); local($type, $prev_type); local($posn, $end_tokens); # Get the list type and previous type $type = substr($item, 1, 2); $prev_type = substr($result[$#result], -3, 2); # Indent is increasing if ($indent > $prev_indent) { $posn = -5 * $prev_indent; while (++$prev_indent < $indent) { $item = "<$type>$item"; } } # Indent is descreasing or the same else { # plain items are compatible with both ordered and unordered lists, so # we need to handle them separately if (substr($item, 4, 5) ne "\n
  • ") { $posn = -5 * $indent; $item = substr($item, 4, length($item) - 9); $item = "\n
    $item"; ## If the previous tag is the same but the indents differ, ## this is an enumerated list item so prepend another newline. #if ($para_tag eq $prev_tag && $prev_indent != $indent) { # $item = "\n
    $item"; #} } # handle items of an existing list elsif ($type eq $prev_type) { $posn = -5 * $indent; $item = substr($item, 4, length($item) - 9); } # item is not compatible with the current list - start a new one else { $indent--; $posn = $indent ? (-5 * $indent) : length($result[$#result]); } } # Merge the item $end_tokens = substr($result[$#result], $posn); substr($result[$#result], $posn) = "$item$end_tokens"; } # # >>_Description:: # {{Y:_HtmlHandlerTuning}} handles the 'tuning' directive. # sub _HtmlHandlerTuning { local(*outbuffer, $style, %attr) = @_; # local(); # do nothing } # # >>_Description:: # {{Y:_HtmlHandlerEndTuning}} handles the 'endtuning' directive. # sub _HtmlHandlerEndTuning { local(*outbuffer, $style, %attr) = @_; # local(); # do nothing } # # >>_Description:: # {{Y:_HtmlHandlerTable}} handles the 'table' directive. # sub _HtmlHandlerTable { local(*outbuffer, $columns, %attr) = @_; # local(); local($indent, $previous_indent, $posn, $begin_tokens, $end_tokens); local($header); local($tbl_title); # Handle tables inside a list # Note: the previous indent is available as a dynamically # scoped variable in &HtmlFormatSection $indent = $attr{'listitem'}; $begin_tokens = ''; $end_tokens = ''; if ($indent) { $previous_indent = $prev_indent; # get dynamically scoped var if ($indent > $previous_indent) { $posn = -5 * $previous_indent; while ($previous_indent++ < $indent) { $begin_tokens .= "
      "; $end_tokens .= "
    "; } } else { $posn = -$indent * 5; } if ($posn < 0) { $end_tokens .= substr($outbuffer[$#outbuffer], $posn); substr($outbuffer[$#outbuffer], $posn) = $begin_tokens; } else { push(@outbuffer, $begin_tokens); } } # Update the state push(@_html_tbl_state, $_HTML_INTABLE); push(@_html_tbl_endtokens, $end_tokens); push(@_html_tbl_previndent, $indent); # Build the header $header = ' CLASS="' . &_HtmlEscape($attr{'style'}) . '"'; if ($attr{'style'} ne 'plain') { $header .= " BORDER"; } if (defined($attr{'cellspacing'})) { $header .= " CELLSPACING='$attr{'cellspacing'}'"; } if (defined($attr{'cellpadding'})) { $header .= " CELLPADDING='$attr{'cellpadding'}'"; } if ($attr{'align'}) { my $align = $attr{'align'}; $align = 'Left' if $align eq 'Inner'; $align = 'Right' if $align eq 'Outer'; $header .= " ALIGN='$align'"; } if ($attr{'bgcolor'}) { $header .= " BGCOLOR='$attr{'bgcolor'}'"; } # Update the output buffer push(@outbuffer, ""); # Add the title, if any $tbl_title = $attr{'title'}; if ($tbl_title ne '') { push(@outbuffer, "" . $tbl_title . ""); } } # # >>_Description:: # {{Y:_HtmlHandlerRow}} handles the 'row' directive. # sub _HtmlHandlerRow { local(*outbuffer, $text, %attr) = @_; # local(); local($state); # Finalise the old cell/row, if any $state = $_html_tbl_state[$#_html_tbl_state]; if ($state eq $_HTML_INCELL) { push(@outbuffer, "", ""); } elsif ($state eq $_HTML_INROW) { push(@outbuffer, ""); } # Update the state $_html_tbl_state[$#_html_tbl_state] = $_HTML_INROW; # Update the output buffer if ($text ne '' && $text ne 'Body') { push(@outbuffer, ""); } else { push(@outbuffer, ""); } } # # >>_Description:: # {{Y:_HtmlHandlerCell}} handles the 'cell' directive. # sub _HtmlHandlerCell { local(*outbuffer, $text, %attr) = @_; # local(); local($state); local($header); # Reset the paragraph counter for this cell $_html_cell_paracnt = (); # If the cell is hidden, output nothing return if $attr{'hidden'}; # Finalise the old cell, if any $state = $_html_tbl_state[$#_html_tbl_state]; if ($state eq $_HTML_INCELL) { push(@outbuffer, ""); } # Update the state $_html_tbl_state[$#_html_tbl_state] = $_HTML_INCELL; # Build the header $header = ''; if (defined($attr{'align'})) { $header .= " ALIGN='$attr{'align'}'"; } if (defined($attr{'valign'})) { $header .= " VALIGN='$attr{'valign'}'"; } if ($attr{'cols'} != 1) { $header .= " COLSPAN='$attr{'cols'}'"; } if ($attr{'rows'} != 1) { $header .= " ROWSPAN='$attr{'rows'}'"; } if (defined($attr{'nowrap'})) { $header .= " NOWRAP"; } if (defined($attr{'bgcolor'})) { $header .= " BGCOLOR='$attr{'bgcolor'}'"; } # Update the output buffer push(@outbuffer, ""); } # # >>_Description:: # {{Y:_HtmlHandlerEndTable}} handles the 'endtable' directive. # sub _HtmlHandlerEndTable { local(*outbuffer, $text, %attr) = @_; # local(); local($state); local($end_tokens); # Finalise the table $state = pop(@_html_tbl_state); if ($state eq $_HTML_INCELL) { push(@outbuffer, "", ""); } elsif ($state eq $_HTML_INROW) { push(@outbuffer, ""); } push(@outbuffer, ""); # Terminate the list, if any $end_tokens = pop(@_html_tbl_endtokens); push(@outbuffer, $end_tokens); # Restore the previous indent. We do this by hacking the # %para_attrs hash dynamically scoped in &HtmlFormatSection. :-( $para_attrs{'in'} = pop(@_html_tbl_previndent); } # # >>_Description:: # {{Y:_HtmlHandlerImport}} handles the import directive. # sub _HtmlHandlerImport { local(*outbuffer, $filepath, %attr) = @_; # local(); local($para); # Build the result &_HtmlPhraseHandlerImport(*para, $filepath, %attr); push(@outbuffer, &_HtmlElement('P', $para)); } # # >>_Description:: # {{Y:_HtmlHandlerInline}} handles the inline directive. # sub _HtmlHandlerInline { local(*outbuffer, $text, %attr) = @_; # local(); # Check we can handle this format my $target = $attr{'target'}; return unless $target eq 'html'; # Build the result push(@outbuffer, $text); } # # >>_Description:: # {{Y:_HtmlHandlerOutput}} handles the output directive. # sub _HtmlHandlerOutput { local(*outbuffer, $text, %attr) = @_; # local(); local($offset, @topic_data, @dummy_contents); local($file); local($this_topic); # Finalise the current topic, if requested if ($text eq '-') { # If there is no current topic, do nothing return unless @_html_topic_offset; # Generate the html for the topic $offset = pop(@_html_topic_offset); @topic_data = splice(@outbuffer, $offset + 1); #printf "TOPIC:\n%s\nENDTOPIC\n", join("\n", @topic_data); @topic_data = &_HtmlFinalise(*topic_data, *dummy_contents); # Output the topic $file = pop(@_html_topic_file); #print STDERR "offset: $offset, file: $file.\n"; unless (open(TOPIC, ">$file")) { &AppMsg("error", "unable to write to topic file '$file'"); return; } print TOPIC join("\n", @topic_data), "\n"; close(TOPIC); } # Otherwise, save the output filename and the current offset else { push(@_html_topic_file, $text); push(@_html_topic_offset, $#outbuffer); } # Update the current topic name (without the extension) $this_topic = $_html_topic_file[$#_html_topic_file]; $this_topic =~ s/\.html$//; $SDF_USER'var{'HTML_TOPIC'} = $this_topic; #print STDERR "HTML_TOPIC: $this_topic.\n"; } # # >>_Description:: # {{Y:_HtmlHandlerObject}} handles the 'object' directive. # sub _HtmlHandlerObject { local(*outbuffer, $text, %attrs) = @_; # local(); if ($text eq 'meta') { push(@_html_meta, "'); } if ($text eq 'link') { push(@_html_links, "'); } } # # >>_Description:: # {{Y:_HtmlHandlerStyleSheet}} handles the 'stylesheet' directive. # sub _HtmlHandlerStyleSheet { local(*outbuffer, $text, %attrs) = @_; # local(); push(@_html_stylesheet, $text); } # # >>_Description:: # {{Y:_HtmlHandlerDiv}} handles the 'div' directive. # sub _HtmlHandlerDiv { local(*outbuffer, $text, %attrs) = @_; # local(); push(@_html_divs, $text); push(@outbuffer, '
    '); } # # >>_Description:: # {{Y:_HtmlHandlerEndDiv}} handles the 'enddiv' directive. # sub _HtmlHandlerEndDiv { local(*outbuffer, $text, %attrs) = @_; # local(); push(@outbuffer, '
    '); # If we've just finished building the title, save it away # and re-initialise the buffer if (pop(@_html_divs) eq 'title') { @_html_title_div = @outbuffer; @outbuffer = (); } } # # >>_Description:: # {{Y:_HtmlPhraseHandlerChar}} handles the 'char' phrase directive. # sub _HtmlPhraseHandlerChar { local(*para, $text, %attr) = @_; # local(); # Map the symbolic names if (defined($_HTML_CHAR{$text})) { $para .= $_HTML_CHAR{$text}; } else { # Numbers are ISO character codes $para .= $text =~ /\D/ ? "&$text;" : "&#$text;"; } } # # >>_Description:: # {{Y:_HtmlPhraseHandlerImport}} handles the 'import' phrase directive. # sub _HtmlPhraseHandlerImport { local(*para, $filepath, %attr) = @_; # local(); local($name, $value); local($jump); local($pre, $post); if ( $attr{'align'} eq 'center' ) { $pre='
    '; $post='
    '; } else { $pre=''; $post=''; } # Map the attributes to HTML while (($name, $value) = each %attr) { # Simple for now delete $attr{$name} if $name eq 'fullname'; delete $attr{$name} if $name eq 'width'; delete $attr{$name} if $name eq 'height'; } # Build the result $para .= $pre; if ($attr{'jump'} ne '') { $jump = $attr{'jump'}; delete $attr{'jump'}; # Disable the border unless it is explicitly asked for $attr{'border'} = 0 unless $attr{'border'}; $para .= "" . ""; } else { $para .= ""; } $para .= $post; } # # >>_Description:: # {{Y:_HtmlPhraseHandlerInline}} handles the 'inline' phrase directive. # sub _HtmlPhraseHandlerInline { local(*para, $text, %attr) = @_; # local(); # Build the result $para .= $text; } # # >>_Description:: # {{Y:_HtmlPhraseHandlerVariable}} handles the 'variable' phrase directive. # sub _HtmlPhraseHandlerVariable { local(*para, $text, %attr) = @_; # local(); # do nothing } package SDF_USER; # # >>Description:: # {{Y:HtmlTopicsModeHeading}} is an event processing routine for # headings when topics mode is enabled. # sub HtmlTopicsModeHeading { # local() = @_; # local(); local($level, $file_base); local($jump); local($topic_base, $topic_file); local(@prepend); local($new_level, $close_count, $i); local($title); # As the heading for the main document might be built in the # "front" component, we explicitly ignore headings in sdm files return if $var{'FILE_EXT'} eq 'sdm'; # If this heading doesn't have an id, ignore it return if $attr{'noid'}; # Get the heading level and containing file $level = substr($style, 1, 1); $file_base = $var{'FILE_BASE'}; # When processing the main file: # * detect the first heading in each SDF file or a # certain level heading as a topic boundary (and save # the heading text as the label for that topic) # * save the file each section lives in, so that # section jumps work as expected if ($var{'HTML_TOPICS_MODE'}) { if (! $topic_label{$file_base} && $file_base ne $var{'DOC_BASE'}) { $'_html_topic = $file_base; push(@levels, $level); push(@topics, $'_html_topic); $topic_label{$'_html_topic} = $text; $topic_level{$'_html_topic} = $level; $jump = $'_html_topic . ".html"; $'_html_topic_start{$file_base,$text} = $'_html_topic; } elsif ($level <= $var{'OPT_SPLIT_LEVEL'}) { if ($'_html_topic_start{$file_base,$text}) { &'AppMsg("warning", "file base '$file_base' & topic heading '$text' combination is not unique'"); return; } $'_html_topic = &HtmlTopicName($var{'DOC_BASE'}); push(@levels, $level); push(@topics, $'_html_topic); $topic_label{$'_html_topic} = $text; $topic_level{$'_html_topic} = $level; $jump = $'_html_topic . ".html"; $'_html_topic_start{$file_base,$text} = $'_html_topic; } else { if ($attr{'id'} ne '') { $jump = $'_html_topic . ".html#" . $attr{"id"}; } else { $jump = $'_html_topic . ".html#" . &TextToId($text); } } # Save the jump for this file/text combination. # This is used for TOC generation. $'_html_jump_id{$file_base,$text} = $jump; # Save the place to jump to for this text. # The jump table is used to resolve SECT jumps (in topics mode). if ($jump{$text} eq '') { $jump{$text} = $jump; $jump_level{$text} = $level; } else { # Override the jump if the new jump is more important if ($level < $jump_level{$text}) { $jump{$text} = $jump; $jump_level{$text} = $level; } } } # Otherwise, we're creating sub-topics else { # If this heading starts a topic: # * prepend the necessary output directives # * make it the title # * prevent a line above it by setting the notoc attribute. $topic_base = $'_html_topic_start{$file_base,$text}; if ($topic_base) { $topic_file = "$topic_base.html"; @prepend = (); $new_level = $topic_level{$topic_base}; $close_count = $'_html_topic_level - $new_level + 1; $'_html_topic_level = $new_level; for ($i = 0; $i < $close_count; $i++) { push(@prepend, "!output '-'"); } $title = $text; $title =~ s/(['\\])/\\$1/g; push(@prepend, "[jump='$topic_file'] $text", "!output '$topic_file'", #"!define HTML_TOPIC '$topic_base'", "!define DOC_TITLE '$title'", "!HTML_BUILD_TITLE"); &PrependText(@prepend); $attr{'notoc'} = 1; } } } # Generate a name for a topic sub HtmlTopicName { local($base) = @_; local($tname); $'_html_topic_cntr++; $tname = $var{'HTML_TOPIC_PATTERN'}; $tname = '$b_$n' if $tname eq ''; $tname =~ s/\$b/$base/g; $tname =~ s/\$n/$'_html_topic_cntr/; return $tname; } # package return value 1; $end_tokens = pop(@_html_tbl_endtokens); push(@outbuffer, $end_tsdf-2.001/perllib/sdf/topod.pl010075500042570001753000000456470671163465700160470ustar00iancmtr00000400000236# $Id$ $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: POD Format Driver # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 10-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # This library provides an [[SDF_DRIVER]] which generates # [[POD]] files. # # >>Description:: # # >>Limitations:: # SDF features which do not yet have a POD equivalent generally do not # work, although some features (e.g. simple tables) are emulated with # varying degrees of success. # # Multi-line cells in tables (including nested tables) do not work. # # >>Resources:: # # >>Implementation:: # ##### Constants ##### # Default right margin (used for table wrapping) $_POD_DEFAULT_MARGIN = 70; # Mapping of characters %_POD_CHAR = ( 'bullet', '.', 'c', '(c)', 'cent', 'c', 'dagger', '^', 'doubledagger', '#', 'emdash', '-', 'endash', '-', 'emspace', ' ', 'enspace', ' ', 'lbrace', '{', 'lbracket', '[', 'nbdash', '-', 'nbspace', ' ', 'nl', "\n", 'pound', 'L', 'r', '(r)', 'rbrace', '}', 'rbracket', ']', 'tab', "\t", 'tm', '(tm) ', 'yen', 'y', ); # Directive mapping table %_POD_HANDLER = ( 'tuning', '_PodHandlerTuning', 'endtuning', '_PodHandlerEndTuning', 'table', '_PodHandlerTable', 'row', '_PodHandlerRow', 'cell', '_PodHandlerCell', 'endtable', '_PodHandlerEndTable', 'import', '_PodHandlerImport', 'inline', '_PodHandlerInline', 'output', '_PodHandlerOutput', 'object', '_PodHandlerObject', 'stylesheet', '', ); # Phrase directive mapping table %_POD_PHRASE_HANDLER = ( 'char', '_PodPhraseHandlerChar', 'import', '_PodPhraseHandlerImport', 'inline', '_PodPhraseHandlerInline', 'variable', '_PodPhraseHandlerVariable', ); # Table states $_POD_INTABLE = 1; $_POD_INROW = 2; $_POD_INCELL = 3; ##### Variables ##### # Right margin position $_pod_margin = $_POD_DEFAULT_MARGIN; # Counter for ordered lists $_pod_list_num = 0; # Table states @_pod_tbl_state = (); # Column number & starting positions for current table $_pod_col_num = 0; @_pod_col_posn = (); # Flag to indicate current paragraph is an example $_pod_in_example = 0; # Lookup table for list types at each indent level @_pod_list_type = (); ##### Routines ##### # # >>Description:: # {{Y:PodFormat}} is an SDF driver which outputs POD. # sub PodFormat { local(*data) = @_; local(@result); local(@contents); # Init things $_pod_list_num = 0; @_pod_tbl_state = (); $_pod_col_num = 0; @_pod_col_posn = (); $_pod_in_example = 0; @_pod_list_type = (); # Format the paragraphs @contents = (); @result = &_PodFormatSection(*data, *contents); # Turn into final form and return return &_PodFinalise(*result, *contents); } # # >>_Description:: # {{Y:_PodFormatSection}} formats a set of SDF paragraphs into POD. # If a parameter is passed to contents, then that array is populated # with a generated Table of Contents. # sub _PodFormatSection { local(*data, *contents) = @_; local(@result); local($prev_tag, $prev_indent); local($para_tag, $para_text, %para_attrs); local($directive); # Process the paragraphs @result = (); $prev_tag = ''; $prev_indent = ''; while (($para_text, $para_tag, %para_attrs) = &SdfNextPara(*data)) { # Set the indent for Item paragraphs #$para_attrs{'in'} = 1 if $para_tag eq 'Item'; # handle directives if ($para_tag =~ /^__(\w+)$/) { $directive = $_POD_HANDLER{$1}; if (defined &$directive) { &$directive(*result, $para_text, %para_attrs); } else { &AppTrace("pod", 5, "ignoring internal directive '$1'"); } next; } # Add the paragraph &_PodParaAdd(*result, $para_tag, $para_text, *para_attrs, $prev_tag, $prev_indent, *contents); } # Do this stuff before starting next loop iteration continue { $prev_tag = $para_tag; $prev_indent = $para_attrs{'in'}; } # Return result return @result; } # # >>_Description:: # {{Y:_PodParaAdd}} adds a paragraph. # sub _PodParaAdd { local(*result, $para_tag, $para_text, *para_attrs, $prev_tag, $prev_indent, *contents) = @_; # local(); local($para_fmt); local($para_override); local($para); local($hdg_level); local($toc_jump); local($label); local($indent); # Set the example flag $_pod_in_example = $SDF_USER'parastyles_category{$para_tag} eq 'example'; # Get the target format name $para_fmt = $SDF_USER'parastyles_to{$para_tag}; $para_fmt = $para_tag if $para_fmt eq ''; # Map the attributes &SdfAttrMap(*para_attrs, 'pod', *SDF_USER'paraattrs_to, *SDF_USER'paraattrs_map, *SDF_USER'paraattrs_attrs, $SDF_USER'parastyles_attrs{$para_tag}); # Build the Table of Contents as we go $toc_jump = ''; if ($para_tag =~ /^[HAP](\d)$/) { $hdg_level = $1; if ($hdg_level <= $SDF_USER'var{'DOC_TOC'} && !$para_attrs{'notoc'}) { # Build a plain list in SDF $toc_jump = $para_attrs{'id'}; $toc_jump = "HDR" . ($#contents + 1) if $toc_jump eq ''; push(@contents, "L${hdg_level}[jump='#$toc_jump']$para_text"); } } # Handle lists elsif ($para_tag =~ /^(L[FUNI]?)(\d)$/) { $para_attrs{'in'} = $2; if ($1 eq 'LU') { $para_fmt = "item *"; } elsif ($1 eq 'L') { #$para_fmt = "item $para_attr{'label'}"; $para_fmt = "item"; } elsif ($1 eq 'LF') { $para_fmt = "item 1."; $_pod_list_num = 1; } elsif ($1 eq 'LI') { $para_fmt = "item " . &_PodParaText($para_text); $para_text = ''; } else { $_pod_list_num++; $para_fmt = "item $_pod_list_num."; } } # Prepend the label, if any (replacing tabs with spaces) $label = $para_attrs{'label'}; $label = 'Note: ' if ($para_tag eq 'Note' || $para_tag eq 'NB') && $label eq ''; $label =~ s/\\t/ /g; $para_text = "{{2:$label}}$para_text" if $label ne ''; # Format the paragraph body if ($para_attrs{'verbatim'}) { $para = $para_text; delete $para_attrs{'verbatim'}; } else { $para = &_PodParaText($para_text); } # If we're in a table, prepend the paragraph onto the current row if (@_pod_tbl_state) { $result[$#result] .= $para; return; } # Build result $indent = $para_attrs{'in'}; if ($_pod_in_example) { &_PodAddExample(*result, $para, $para_tag, $prev_tag, $indent, $prev_indent); } elsif ($indent) { $item = &_PodElement($para_fmt, $para, %para_attrs); &_PodAddItem(*result, $item, $indent, $prev_indent, $para_tag); } else { $para = &_PodElement($para_fmt, $para, %para_attrs); push(@result, $para); } } # # >>_Description:: # {{Y:_PodParaText}} converts SDF paragraph text into POD. # sub _PodParaText { local($para_text) = @_; local($para); local($state); local($sect_type, $char_tag, $text, %sect_attrs); local($added_anchors); local(@char_fonts); local($char_font); local($directive); # Process the text $para = ''; $state = 0; while (($sect_type, $text, $char_tag, %sect_attrs) = &SdfNextSection(*para_text, *state)) { # Build the paragraph: # * if we're inside a table or example, just use the text # * otherwise, build things "normally" if (@_pod_tbl_state || $_pod_in_example) { $para .= $text; } elsif ($sect_type eq 'string') { $text = &_PodEscape($text, 0); $para .= $text; } elsif ($sect_type eq 'phrase') { # Escape any special characters $text = &_PodEscape($text, 1); # Process formatting attributes &SdfAttrMap(*sect_attrs, 'pod', *SDF_USER'phraseattrs_to, *SDF_USER'phraseattrs_map, *SDF_USER'phraseattrs_attrs, $SDF_USER'phrasestyles_attrs{$char_tag}); # Map the font - italics is the default $char_font = $SDF_USER'phrasestyles_to{$char_tag}; $char_font = 'I' if $char_font eq ''; # Add the text for this phrase push(@char_fonts, $char_font); if ($char_font ne '') { $para .= "$char_font<$text"; } else { $para .= $text; } } elsif ($sect_type eq 'phrase_end') { $char_font = pop(@char_fonts); $para .= ">" if $char_font ne ''; } elsif ($sect_type eq 'special') { $directive = $_POD_PHRASE_HANDLER{$char_tag}; if (defined &$directive) { &$directive(*para, $text, %sect_attrs); } else { &AppMsg("warning", "ignoring special phrase '$1' in POD driver"); } } else { &AppMsg("warning", "unknown section type '$sect_type' in POD driver"); } } # Return result return $para; } # # >>_Description:: # {{Y:_PodFinalise}} generates the final POD file. # sub _PodFinalise { local(*body, *contents) = @_; # local(@result); # Return result return @body; } # # >>_Description:: # {{Y:_PodEscape}} escapes special symbols in POD text. # {{nested}} should be true if {{text}} will be nested # within an interior sequence. # sub _PodEscape { local($text, $nested) = @_; # local($result); local($old_match_flag); # Enable multi-line matching $old_match_flag = $*; $* = 1; # Escape the symbols my $gt = $nested ? 'E' : '>'; $text =~ s/([A-Z])\<|\>/length($&) == 1 ? $gt : "$1E"/eg; # Reset multi-line matching flag $* = $old_match_flag; # Return result $text; } # # >>_Description:: # {{Y:_PodAttr}} formats a set of attributes into POD. # sub _PodAttr { local(*attrs) = @_; local($pod); # Currently, pod doesn't support attributes (other than jump -> L?) $pod = ''; # Return result $pod; } # # >>_Description:: # {{Y:_PodElement}} formats a POD element from a # tag, text and set of attributes. # sub _PodElement { local($tag, $text, %attr) = @_; # local($pod); local($over); # For list items, add the over/back stuff $over = 4 * $attr{'in'}; if ($tag =~ /^item/) { if ($text ne '') { $text = &MiscTextWrap($text, 70, '', '', 1); return "=over $over\n\n=$tag\n\n$text\n\n=back\n"; } else { return "=over $over\n\n=$tag\n\n=back\n"; } } # For lines, output a 'line' if ($tag eq 'Line') { return " " . ("_" x 40) . "\n"; } # For headings, map the tag to a command if ($tag =~ /^head/) { return "=$tag $text\n"; } # Otherwise, format as a plain paragraph return &MiscTextWrap($text, 70, '', '', 1) . "\n"; } # # >>_Description:: # {{Y:_PodAddExample}} adds an example paragraph to the result # sub _PodAddExample { local(*result, $para, $tag, $prev_tag, $indent, $prev_indent) = @_; # local(); if ($prev_indent == 0) { if ($tag eq $prev_tag) { #$para =~ s/^\S/ $&/; # Prepend a space if necessary $result[$#result] .= "$para\n"; } else { $para =~ s/^\S/ $&/; # Prepend a space if necessary push(@result, $para . "\n"); } } else { # Insert the text before the old "=back\n" my $posn = -(6 * $prev_indent + $prev_indent - 1); my $end_tokens = substr($result[$#result], $posn); $posn-- if $tag eq $prev_tag; substr($result[$#result], $posn) = "$para\n\n$end_tokens"; } } # # >>_Description:: # {{Y:_PodAddItem}} adds an item paragraph to the result buffer. # sub _PodAddItem { local(*result, $item, $indent, $prev_indent, $para_tag) = @_; # local(); local($type); local($i); local($over); local($posn, $end_tokens); local($in); # Get the list type $type = substr($para_tag, 0, 2); $type = 'LN' if $type eq 'LF'; # Indent is increasing if ($indent > $prev_indent) { $_pod_list_type[$indent] = $type; $posn = -(6 * $prev_indent + $prev_indent - 1); for ($i = $indent - 1; $i > $prev_indent; $i--) { $_pod_list_type[$i] = $type; $over = $i * 4; $item = "=over $over\n\n$item\n=back\n"; } if ($prev_indent == 0) { push(@result, $item); return; } else { $item .= "\n"; } } # Indent is decreasing or the same else { # plain items are compatible with both ordered and unordered lists, # so handle them separately if ($para_tag =~ /^L\d$/) { # ignore the new "=item\n\n" $item = substr($item, 7); $posn = -(6 * $indent + $indent - 1); $item = substr($item, 9, length($item) - 15); } # handle items of an existing list elsif ($type eq $_pod_list_type[$indent]) { $posn = -(6 * $indent + $indent - 1); $item = substr($item, 9, length($item) - 15); } # item is not compatible with the current list - start a new one else { $item = "\n" . $item; if ($indent > 1) { $in = $indent - 1; $posn = -(6 * $in + $in - 1); } else { $posn = length($result[$#result]); } # Update the list type $_pod_list_type[$indent] = $type; } } # Merge the item $end_tokens = substr($result[$#result], $posn); #print STDERR "indent: $indent.\n"; #print STDERR "posn: $posn.\n"; #print STDERR "item: $item.\n"; #print STDERR "end_tokens: $end_tokens.\n"; substr($result[$#result], $posn) = "$item$end_tokens"; } # # >>_Description:: # {{Y:_PodHandlerTuning}} handles the 'tuning' directive. # sub _PodHandlerTuning { local(*outbuffer, $style, %attr) = @_; # local(); # do nothing } # # >>_Description:: # {{Y:_PodHandlerEndTuning}} handles the 'endtuning' directive. # sub _PodHandlerEndTuning { local(*outbuffer, $style, %attr) = @_; # local(); # do nothing } # # >>_Description:: # {{Y:_PodHandlerTable}} handlers the 'table' directive. # sub _PodHandlerTable { local(*outbuffer, $columns, %attr) = @_; # local(); local($tbl_title); # Update the state push(@_pod_tbl_state, $_POD_INTABLE); # Calculate the column positions (rounded) @_pod_col_posn = &SdfColPositions($columns, $attr{'format'}, $_pod_margin); # Add the title, if any $tbl_title = $attr{'title'}; if ($tbl_title ne '') { push(@outbuffer, "I<$tbl_title>\n"); } } # # >>_Description:: # {{Y:_PodHandlerRow}} handlers the 'row' directive. # sub _PodHandlerRow { local(*outbuffer, $text, %attr) = @_; # local(); # Start the new row (a leading space makes it fixed-width text) push(@outbuffer, " "); $_pod_col_num = 0; # Update the state $_pod_tbl_state[$#_pod_tbl_state] = $_POD_INROW; } # # >>_Description:: # {{Y:_PodHandlerCell}} handles the 'cell' directive. # sub _PodHandlerCell { local(*outbuffer, $text, %attr) = @_; # local(); local($state); local($padding); # Finalise the old cell, if any $state = $_pod_tbl_state[$#_pod_tbl_state]; if ($state eq $_POD_INCELL) { if ($_pod_col_num > 0) { $padding = $_pod_col_posn[$_pod_col_num - 1] - length($outbuffer[$#outbuffer]); $outbuffer[$#outbuffer] .= " " x $padding; } } # Update the state $_pod_tbl_state[$#_pod_tbl_state] = $_POD_INCELL; $_pod_col_num++; } # # >>_Description:: # {{Y:_PodHandlerEndTable}} handles the 'endtable' directive. # sub _PodHandlerEndTable { local(*outbuffer, $text, %attr) = @_; # local(); local($state); # Finalise the table $state = pop(@_pod_tbl_state); if ($state eq $_POD_INCELL) { $outbuffer[$#outbuffer] .= "\n"; } elsif ($state eq $_POD_INROW) { $outbuffer[$#outbuffer] .= "\n"; } } # # >>_Description:: # {{Y:_PodHandlerImport}} handles the import directive. # sub _PodHandlerImport { local(*outbuffer, $filepath, %attr) = @_; # local(); local($para); # Build the result &_PodPhraseHandlerImport(*para, $filepath, %attr); push(@outbuffer, "$para\n"); } # # >>_Description:: # {{Y:_PodHandlerInline}} handles the inline directive. # sub _PodHandlerInline { local(*outbuffer, $text, %attr) = @_; # local(); # Tell POD this is for another format, if necessary my $target = $attr{'target'}; $text = "=for $target $text\n" unless $target eq 'pod'; # Build the result push(@outbuffer, $text); } # # >>_Description:: # {{Y:_PodHandlerOutput}} handles the 'output' directive. # sub _PodHandlerOutput { local(*outbuffer, $text, %attrs) = @_; # local(); # do nothing } # # >>_Description:: # {{Y:_PodHandlerObject}} handles the 'object' directive. # sub _PodHandlerObject { local(*outbuffer, $text, %attrs) = @_; # local(); # Save the margin, if necessary if ($text eq 'Variable' && $attrs{'Name'} eq 'POD_MARGIN') { $_pod_margin = $attrs{'value'}; } } # # >>_Description:: # {{Y:_PodPhraseHandlerChar}} handles the 'char' phrase directive. # sub _PodPhraseHandlerChar { local(*para, $text, %attr) = @_; # local(); # Map those we know about it if (defined($_POD_CHAR{$text})) { $para .= $_POD_CHAR{$text}; } else { # Assume character is to be escaped $para .= "E<$text>" } } # # >>_Description:: # {{Y:_PodPhraseHandlerImport}} handles the 'import' phrase directive. # sub _PodPhraseHandlerImport { local(*para, $filepath, %attr) = @_; # local(); local($name, $value); $para .= "** I **"; } # # >>_Description:: # {{Y:_PodPhraseHandlerInline}} handles the 'inline' phrase directive. # sub _PodPhraseHandlerInline { local(*para, $text, %attr) = @_; # local(); # Build the result $para .= $text; } # # >>_Description:: # {{Y:_PodPhraseHandlerVariable}} handles the 'variable' phrase directive. # sub _PodPhraseHandlerVariable { local(*para, $text, %attr) = @_; # local(); # do nothing } # package return value 1; if ($char_font ne '') { $para .= "$char_font<$text"; sdf-2.001/perllib/sdf/tosgml.pl010075500042570001753000000564600671163472200162130ustar00iancmtr00000400000236# $Id$ $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: SGML Format Driver # # >>Copyright:: # Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 14-Aug-97 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # This library provides an [[SDF_DRIVER]] which generates # [[SGML]] files. # # >>Description:: # # >>Limitations:: # Cross-references and URLs aren't there yet. # # Indented tables within a bulleted list don't work yet. # # Tagged lists aren't mapped as well as they could be. # # Special character support still needs some work (for dagger and # doubledagger, if not a few others). # # Lists which have ordered items, then unordered items, then # ordered items all at the same level are output as three # separate lists. As a result, the numbering in the third list # restarts even if you don't want it to. # # >>Resources:: # # >>Implementation:: # ##### Constants ##### # These are the tags which don't have/need a closing tag %_SGML_NOENDTAG = ( 'title', 1, 'author', 1, 'date', 1, 'sect', 1, 'sect1', 1, 'sect2', 1, 'sect3', 1, 'sect4', 1, 'sect5', 1, 'p', 1, ); # Mapping table for characters %_SGML_CHAR = ( 'bullet', '.', 'c', '©', 'cent', '¢', 'dagger', '^', 'doubledagger', '#', 'emdash', '—', 'endash', '–', 'emspace', ' ', 'enspace', ' ', 'lbrace', '{', 'lbracket', '[', 'nbdash', '-', 'nbspace', ' ', 'nl', '&nl;', 'pound', '£', 'r', '®', 'rbrace', '}', 'rbracket', ']', 'tab', ' ', 'tm', '™', # not sure about this 'yen', '¥', ); # Directive mapping table %_SGML_HANDLER = ( 'tuning', '_SgmlHandlerTuning', 'endtuning', '_SgmlHandlerEndTuning', 'table', '_SgmlHandlerTable', 'row', '_SgmlHandlerRow', 'cell', '_SgmlHandlerCell', 'endtable', '_SgmlHandlerEndTable', 'import', '_SgmlHandlerImport', 'inline', '_SgmlHandlerInline', 'output', '_SgmlHandlerOutput', 'object', '_SgmlHandlerObject', 'stylesheet', '', ); # Phrase directive mapping table %_SGML_PHRASE_HANDLER = ( 'char', '_SgmlPhraseHandlerChar', 'import', '_SgmlPhraseHandlerImport', 'inline', '_SgmlPhraseHandlerInline', 'variable', '_SgmlPhraseHandlerVariable', ); # Table states $_SGML_INTABLE = 1; $_SGML_INROW = 2; $_SGML_INCELL = 3; ##### Variables ##### # Table states @_sgml_tbl_state = (); @_sgml_tbl_endtokens = (); @_sgml_tbl_previndent = (); @_sgml_tbl_title = (); ##### Routines ##### # # >>Description:: # {{Y:SgmlFormat}} is an SDF driver which outputs SGML. # sub SgmlFormat { local(*data) = @_; local(@result); # Format the paragraphs @result = &_SgmlFormatSection(*data); # Build the final result. @result = &_SgmlFinalise(*result); # Return the result return @result; } # # >>_Description:: # {{Y:_SgmlFormatSection}} formats a set of SDF paragraphs into SGML. # sub _SgmlFormatSection { local(*data) = @_; local(@result); local($prev_tag, $prev_indent); local($para_tag, $para_text, %para_attrs); local($directive); # Process the paragraphs @result = (); $prev_tag = ''; $prev_indent = ''; while (($para_text, $para_tag, %para_attrs) = &SdfNextPara(*data)) { # handle directives if ($para_tag =~ /^__(\w+)$/) { $directive = $_SGML_HANDLER{$1}; if (defined &$directive) { &$directive(*result, $para_text, %para_attrs); } else { &AppTrace("sgml", 5, "ignoring internal directive '$1'"); } next; } # Add the paragraph &_SgmlParaAdd(*result, $para_tag, $para_text, *para_attrs, $prev_tag, $prev_indent); } # Do this stuff before starting next loop iteration continue { $prev_tag = $para_tag; $prev_indent = $para_attrs{'in'}; } # Return result return @result; } # # >>_Description:: # {{Y:_SgmlParaAdd}} adds a paragraph. # sub _SgmlParaAdd { local(*result, $para_tag, $para_text, *para_attrs, $prev_tag, $prev_indent) = @_; # local(); local($is_example); local($para_fmt); local($para_override); local($para); local($hdg_level); local($label); local($indent); local($list_tag); # Get the example flag $is_example = $SDF_USER'parastyles_category{$para_tag} eq 'example'; # Enumerated lists are the same as list paragraphs at the previous level, # except that we bold the text if ($para_tag =~ /^LI(\d)$/) { $para_tag = $1 > 1 ? "L" . ($1 - 1) : 'N'; $para_attrs{'bold'} = 1; } # Get the target format name $para_fmt = $SDF_USER'parastyles_to{$para_tag}; $para_fmt = $is_example ? 'tscreen' : 'p' if $para_fmt eq ''; # Map the attributes &SdfAttrMap(*para_attrs, 'sgml', *SDF_USER'paraattrs_to, *SDF_USER'paraattrs_map, *SDF_USER'paraattrs_attrs, $SDF_USER'parastyles_attrs{$para_tag}); # Handle headings if ($para_tag =~ /^[HAP](\d)$/) { $hdg_level = $1 - 1; $para_fmt = $hdg_level ? "sect$hdg_level" : "sect"; } # Handle lists elsif ($para_tag =~ /^(L[FUN]?)(\d)$/) { $para_attrs{'in'} = $2; if ($1 eq 'LU') { $para_fmt = 'itemize'; } elsif ($1 eq 'L') { $para_fmt = 'list'; } else { $para_fmt = 'enum'; } } # Prepend the label, if any (replacing tabs with spaces) $label = $para_attrs{'label'}; $label = 'Note: ' if ($para_tag eq 'Note' || $para_tag eq 'NB') && $label eq ''; $label =~ s/\\t/ /g; $para_text = "{{2:$label}}$para_text" if $label ne ''; # Indent examples, if necessary if ($is_example && $para_attrs{'in'}) { $para_text = " " x ($para_attrs{'in'} * 4) . $para_text; delete $para_attrs{'in'}; } # Format the paragraph body if ($para_attrs{'verbatim'}) { $para = &_SgmlEscape($para_text); delete $para_attrs{'verbatim'}; } else { $para = &_SgmlParaText($para_text); } ## Examples with change bars currently come out as separate ## paragraphs - this fixes the problem, for now #delete $para_attrs{'changed'} if $para_attrs{'changed'}; # Build result $indent = $para_attrs{'in'}; #if ($is_example && $para_tag eq $prev_tag && !%para_attrs) { if ($is_example && $para_tag eq $prev_tag) { &_SgmlParaAppend(*result, $para); } elsif ($indent && $prev_indent != 0) { $item = &_SgmlElement($para_fmt, $para, %para_attrs); &_SgmlItemAppend(*result, $item, $indent, $prev_indent, $para_tag, $prev_tag, *para_attrs); } # Plain paragraphs inside tables are not preceded by

    elsif (@_sgml_tbl_state && $para_fmt eq 'p') { push(@result, $para); } else { # After a heading, make sure the next entity is another heading # or a plain paragraph if ($prev_tag =~ /^[HAP]\d$/ && $para_fmt ne 'p' && $para_fmt !~ /^sect\d?$/) { push(@result, '

    '); } # Add this element, handling lists which begin at an indent # greater than 1 $para = &_SgmlElement($para_fmt, $para, %para_attrs); $list_tag = $para_fmt; while (--$indent > 0) { $para = "<$list_tag>$para"; } push(@result, $para); } } # # >>_Description:: # {{Y:_SgmlParaText}} converts SDF paragraph text into SGML. # sub _SgmlParaText { local($para_text) = @_; local($para); local($state); local($sect_type, $char_tag, $text, %sect_attrs); local($url); local($added_anchors); local(@char_fonts); local($char_font); local($directive); # Process the text $para = ''; $state = 0; while (($sect_type, $text, $char_tag, %sect_attrs) = &SdfNextSection(*para_text, *state)) { # Build the paragraph if ($sect_type eq 'string') { $para .= &_SgmlEscape($text); } elsif ($sect_type eq 'phrase') { # Expand out link phrases if ($char_tag eq 'L') { ($text, $url) = &SDF_USER'ExpandLink($text); $sect_attrs{'jump'} = $url; } # Escape any special characters $text = &_SgmlEscape($text); # Expand non-breaking spaces, if necessary if ($char_tag eq 'S') { $text =~ s/ /~/g; } # Add hypertext stuff $added_anchors = &_SgmlAddAnchors(*text, *sect_attrs); # Process formatting attributes &SdfAttrMap(*sect_attrs, 'sgml', *SDF_USER'phraseattrs_to, *SDF_USER'phraseattrs_map, *SDF_USER'phraseattrs_attrs, $SDF_USER'phrasestyles_attrs{$char_tag}); # Map the font $char_font = $SDF_USER'phrasestyles_to{$char_tag}; $char_font = 'em' if $char_font eq '' && !$added_anchors; # Add the text for this phrase push(@char_fonts, $char_font); if ($char_font ne '' && $char_font !~ /^SDF/) { $para .= "<$char_font>$text"; } else { $para .= $text; } } elsif ($sect_type eq 'phrase_end') { $char_font = pop(@char_fonts); $para .= "" if $char_font ne '' && $char_font !~ /^SDF/; } elsif ($sect_type eq 'special') { $directive = $_SGML_PHRASE_HANDLER{$char_tag}; if (defined &$directive) { &$directive(*para, $text, %sect_attrs); } else { &AppMsg("warning", "ignoring special phrase '$1' in SGML driver"); } } else { &AppMsg("warning", "unknown section type '$sect_type' in SGML driver"); } } # Return result return $para; } # # >>_Description:: # {{Y:_SgmlFinalise}} generates the final SGML file. # sub _SgmlFinalise { local(*body) = @_; # local(@result); local(@head); # Build the preamble my $dtd = $var{'SGML_DTD'} || 'linuxdoc'; my @head = ( "", '', '

    ', '', ); # Add the ending stuff push(@body, '', '
    '); # Return result return (@head, @body); } # # >>_Description:: # {{Y:_SgmlEscape}} escapes special symbols in SGML text. # sub _SgmlEscape { local($text) = @_; # local($result); local($old_match_flag); # Enable multi-line matching $old_match_flag = $*; $* = 1; # Escape the special symbols. Note that it isn't exactly clear # from the SGML-Tools and/or QWERTZ DTD documentation as to # whether all of these are mandatory, but they shouldn't cause # any harm (I hope!) $text =~ s/\&/&/g; $text =~ s/\/>/g; $text =~ s/\"/&dquot;/g; $text =~ s/\$/$/g; $text =~ s/\~/˜/g; $text =~ s/\#/#/g; $text =~ s/\%/%/g; $text =~ s/\\/\/g; $text =~ s/\|/|/g; $text =~ s/\[/&ftag;/g; # Reset multi-line matching flag $* = $old_match_flag; # Return result $text; } # # >>_Description:: # {{Y:_SgmlAttr}} formats a set of attributes into SGML. # sub _SgmlAttr { local(*attrs) = @_; local($sgml); local($attr, $value, $type); for $attr (sort keys %attrs) { # get the attribute value $value = $attrs{$attr}; # get the attribute type if ($attr =~ s/^sgml\.//) { $type = $_SGML_ATTR_TYPES{$attr}; $type = "string" if $type eq ''; } else { $type = $_SGML_ATTR_TYPES{$attr}; } next unless $type; # Map the attribute name to uppercase $attr =~ tr/a-z/A-Z/; # build the result if ($type eq 'string') { $sgml .= " $attr=\"" . &_SgmlEscape($value) . '"'; } else { $sgml .= " $attr=$value"; } } # Return result $sgml; } # # >>_Description:: # {{Y:_SgmlElement}} formats a SGML element from a # tag, text and set of attributes. # sub _SgmlElement { local($tag, $text, %attr) = @_; # local($sgml); # For preformatted sections, tags go on separate lines $text = "\n$text\n" if $tag eq 'tscreen'; # Add hypertext stuff &_SgmlAddAnchors(*text, *attr); # Bold the text, if requested if ($attr{'bold'}) { $text = "$text"; } # For list items, add the item stuff $text = "\n$text" if $tag =~ /^(itemize|enum|list)$/; # Return result if ($_SGML_NOENDTAG{$tag}) { return "<$tag>$text"; } else { #return "<$tag" . &_SgmlAttr(*attr) . ">$text"; return "<$tag>$text"; } } # # >>_Description:: # {{Y:_SgmlAddAnchors}} adds hypertext jumps and ids to a section of text. # of text. It returns true if anchors were added. # sub _SgmlAddAnchors { local(*text, *attr) = @_; local($result); local($value); local($user_ext); local($old_match_flag); # Skip this routine for now return 0; # Enable multi-line matching $old_match_flag = $*; $* = 1; # For hypertext jumps, surround the text. If the # text contains a jump, the existing jump is removed. if ($attr{'jump'} ne '') { # Get the jump value. If an extension other than sgml is # requested, change the jump value accordingly. Also, # we make sure than any special characters are escaped. $value = $attr{'jump'}; $user_ext = $SDF_USER'var{'SGML_EXT'}; if ($user_ext) { $value =~ s/\.sgml/.$user_ext/; } $value = &_SgmlEscape($value); $text =~ s/\]+\>(.*)\<\/A\>/$1/; $text = "$text"; delete $attr{'jump'}; $result++; } # For hypertext ids, surround the text if it doesn't already contain # a jump. Otherwise, prefix the text with a dummy target so that # jump and id definitions don't clash. if ($attr{'id'} ne '') { $value = &_SgmlEscape($attr{'id'}); if ($text =~ /\ $text"; } else { $text = "$text"; } delete $attr{'id'}; $result++; } # Reset multi-line matching flag $* = $old_match_flag; # Return result return $result; } # # >>_Description:: # {{Y:_SgmlParaAppend}} merges {{para}} into the last paragraph # in {{@result}}. Both paragraphs are assumed to be fixed-width. # sub _SgmlParaAppend { local(*result, $para) = @_; # local(); #$para = " " if $para eq ''; substr($result[$#result], -10) = "$para&nl;\n"; } # # >>_Description:: # {{Y:_SgmlItemAppend}} merges a list item {{item}} into the current # output. The item before is assumed to be a list item too. # sub _SgmlItemAppend { local(*result, $item, $indent, $prev_indent, $para_tag, $prev_tag, *para_attrs) = @_; # local(); local($type, $prev_type); local($posn, $end_tokens); # Get the list type and previous type if ($item =~ /^<(\w+)/) { $type = $1; } else { &AppMsg("warning", "unable to get list type during item merge"); } if ($result[$#result] =~ /(\w+)>$/) { $prev_type = $1; } else { &AppMsg("warning", "unable to get previous type during item merge"); } # Indent is increasing if ($indent > $prev_indent) { if ($result[$#result] =~ s/(<\/\w+>){$prev_indent}$//) { $end_tokens = $&; } else { &AppMsg("warning", "unable to get endtokens during item merge"); } while (++$prev_indent < $indent) { $item = "<$type>$item"; } } # Indent is descreasing or the same else { # handle items of an existing list if ($type eq $prev_type) { if ($result[$#result] =~ s/(<\/\w+>){$indent}$//) { $end_tokens = $&; } else { &AppMsg("warning", "unable to get endtokens during item merge"); } if ($item =~ /^<\w+>(.+)<\/\w+>$/s) { $item = $1; } else { &AppMsg("warning", "unable to get item during item merge"); } } # item is not compatible with the current list - start a new one else { $end_tokens = ''; $indent--; if ($indent) { if ($result[$#result] =~ s/(<\/\w+>){$indent}$//) { $end_tokens = $&; } else { &AppMsg("warning", "unable to get endtokens during item merge"); } } } } # Merge the item $result[$#result] .= "$item$end_tokens"; } # # >>_Description:: # {{Y:_SgmlHandlerTuning}} handles the 'tuning' directive. # sub _SgmlHandlerTuning { local(*outbuffer, $style, %attr) = @_; # local(); # do nothing } # # >>_Description:: # {{Y:_SgmlHandlerEndTuning}} handles the 'endtuning' directive. # sub _SgmlHandlerEndTuning { local(*outbuffer, $style, %attr) = @_; # local(); # do nothing } # # >>_Description:: # {{Y:_SgmlHandlerTable}} handles the 'table' directive. # sub _SgmlHandlerTable { local(*outbuffer, $columns, %attr) = @_; # local(); local($indent, $previous_indent, $posn, $begin_tokens, $end_tokens); # Handle tables inside a list # Note: the previous indent is available as a dynamically # scoped variable in &SgmlFormatSection $indent = $attr{'listitem'}; $begin_tokens = ''; $end_tokens = ''; if ($indent) { $previous_indent = $prev_indent; # get dynamically scoped var if ($indent > $previous_indent) { $posn = -7 * $previous_indent; while ($previous_indent++ < $indent) { $begin_tokens .= ""; $end_tokens .= ""; } } else { $posn = -$indent * 7; } if ($posn < 0) { $end_tokens .= substr($outbuffer[$#outbuffer], $posn); substr($outbuffer[$#outbuffer], $posn) = $begin_tokens; } else { push(@outbuffer, $begin_tokens); } } # Update the state push(@_sgml_tbl_state, $_SGML_INTABLE); push(@_sgml_tbl_endtokens, $end_tokens); push(@_sgml_tbl_previndent, $indent); push(@_sgml_tbl_title, $attr{'title'}); # Build the layout my @col_aligns = split(//, 'l' x $columns); my @user_aligns = split(/,/, $attr{'colaligns'}); my $i; for ($i = 0; $i <= $#user_aligns; $i++) { $col_aligns[$i] = lc(substr($user_aligns[$i], 0, 1)); } my $col_sep = $attr{'style'} eq 'plain' ? '' : "|"; my $layout = join($col_sep, @col_aligns); # Update the output buffer push(@outbuffer, "", ""); } # # >>_Description:: # {{Y:_SgmlHandlerRow}} handles the 'row' directive. # sub _SgmlHandlerRow { local(*outbuffer, $text, %attr) = @_; # local(); local($state); # Finalise the old cell/row, if any $state = $_sgml_tbl_state[$#_sgml_tbl_state]; if ($state eq $_SGML_INCELL) { push(@outbuffer, "@"); } elsif ($state eq $_SGML_INROW) { push(@outbuffer, "@"); } # Update the state $_sgml_tbl_state[$#_sgml_tbl_state] = $_SGML_INROW; } # # >>_Description:: # {{Y:_SgmlHandlerCell}} handles the 'cell' directive. # sub _SgmlHandlerCell { local(*outbuffer, $text, %attr) = @_; # local(); local($state); # If the cell is hidden, output nothing return if $attr{'hidden'}; # Finalise the old cell, if any $state = $_sgml_tbl_state[$#_sgml_tbl_state]; if ($state eq $_SGML_INCELL) { push(@outbuffer, "|"); } # Update the state $_sgml_tbl_state[$#_sgml_tbl_state] = $_SGML_INCELL; } # # >>_Description:: # {{Y:_SgmlHandlerEndTable}} handles the 'endtable' directive. # sub _SgmlHandlerEndTable { local(*outbuffer, $text, %attr) = @_; # local(); # Update the state my $state = pop(@_sgml_tbl_state); my $tbl_title = pop(@_sgml_tbl_title); my $end_tokens = pop(@_sgml_tbl_endtokens); # Finalise the table push(@outbuffer, ""); if ($tbl_title ne '') { push(@outbuffer, ""); } push(@outbuffer, "
    " . $tbl_title . "
    "); # Terminate the list, if any push(@outbuffer, $end_tokens); # Restore the previous indent. We do this by hacking the # %para_attrs hash dynamically scoped in &SgmlFormatSection. :-( $para_attrs{'in'} = pop(@_sgml_tbl_previndent); } # # >>_Description:: # {{Y:_SgmlHandlerImport}} handles the import directive. # sub _SgmlHandlerImport { local(*outbuffer, $filepath, %attr) = @_; # local(); local($para); # Build the result &_SgmlPhraseHandlerImport(*para, $filepath, %attr); push(@outbuffer, $para); } # # >>_Description:: # {{Y:_SgmlHandlerInline}} handles the inline directive. # sub _SgmlHandlerInline { local(*outbuffer, $text, %attr) = @_; # local(); # Check we can handle this format my $target = $attr{'target'}; return unless $target eq 'sgml'; # Build the result push(@outbuffer, $text); } # # >>_Description:: # {{Y:_SgmlHandlerOutput}} handles the output directive. # sub _SgmlHandlerOutput { local(*outbuffer, $text, %attr) = @_; # local(); # do nothing } # # >>_Description:: # {{Y:_SgmlHandlerObject}} handles the 'object' directive. # sub _SgmlHandlerObject { local(*outbuffer, $text, %attrs) = @_; # local(); # do nothing } # # >>_Description:: # {{Y:_SgmlPhraseHandlerChar}} handles the 'char' phrase directive. # sub _SgmlPhraseHandlerChar { local(*para, $text, %attr) = @_; # local(); # Map the symbolic names if (defined($_SGML_CHAR{$text})) { $para .= $_SGML_CHAR{$text}; } else { # Numbers are ISO character codes $para .= $text =~ /\D/ ? "&$text;" : "&#$text;"; } } # # >>_Description:: # {{Y:_SgmlPhraseHandlerImport}} handles the 'import' phrase directive. # sub _SgmlPhraseHandlerImport { local(*para, $filepath, %attr) = @_; # local(); # Trim the extension off the filepath $filepath =~ s/\.\w+$//; # Build the result $para .= "
    \n\n
    "; } # # >>_Description:: # {{Y:_SgmlPhraseHandlerInline}} handles the 'inline' phrase directive. # sub _SgmlPhraseHandlerInline { local(*para, $text, %attr) = @_; # local(); # Build the result $para .= $text; } # # >>_Description:: # {{Y:_SgmlPhraseHandlerVariable}} handles the 'variable' phrase directive. # sub _SgmlPhraseHandlerVariable { local(*para, $text, %attr) = @_; # local(); # do nothing } # package return value 1; >>_Description:: # {{Y:_SgmlAddAnchors}} adds hypertext jumps and ids to a section of text. # of text. It returns true if anchors were added. # sub _SgmlAddAnchors { local(*text, *attr) = @_; local(sdf-2.001/perllib/sdf/post_htx.pl010064400042570001753000000042730661420514000165340ustar00iancmtr00000400000236# $Id$ $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: htx Post Processing Filter # # >>Copyright:: # Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 08-Sep-97 ianc Ported Craig Willis' stuff from gendoc # ----------------------------------------------------------------------- # # >>Purpose:: # {{htx_PostFilter}} post filters plain text format to generate # HTX format for MIMS SmartGUI applications. # sub htx_PostFilter { local(*text) = @_; local(@result); local($_); local( $htx_line, $mod_name_sw, $mod_line, $mod_name, $nomove_sw, $write_sw ); for (@text) { local($htx_sw, $line, $tmp_line); chop($line = $_); # Check if module & module_name has been defined if ( $line =~ /^&HTX&MODULE(_NAME)?/ ) { if ( $line =~ /&MODULE_NAME/ ) { $mod_name_sw++; } $line =~ s/^&HTX&MODULE(_NAME)?($|[\t ]+)//; $mod_name = $line if ( $mod_name_sw); $mod_line = $line unless ( $mod_name_sw); } # Setup when to start writing to file and stop if ( $line =~ /$HTX_FIRST_HDR$/ || $HTX_FIRST_HDR eq '' ) { $write_sw++; } elsif ( $line =~ /$HTX_LAST_HDR$/ && $HTX_LAST_HDR ne '' ) { $write_sw = 0; } # Check for HTX lines if ( $line =~ /^&HTX +/ ) { ($htx_line = $line) =~ s/^\&HTX +//; $htx_sw++; } elsif ( $htx_line ne '' && !$htx_sw && $line ne '' ) { $line .= " $htx_line"; $htx_line = ''; } if ( $write_sw ) { push(@result, "$line\n") unless $htx_sw; } } # Need to print the terminating characters for a HTX file ($htx_line = $DOCO) =~ s/^(tmp_)?\d+_|(\.sdf$)//g; $htx_line =~ tr/a-z/A-Z/; push(@result, "$htx_line\n"); push(@result, "$mod_line $mod_name\n"); # Return result return @result; } # package return value 1; sdf-2.001/perllib/sdf/toexpand.pl010064400042570001753000000042720661420514000165050ustar00iancmtr00000400000236# $Id$ $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: Expand Output Driver # # >>Copyright:: # Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 25-Jul-97 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # This library provides an [[SDF_DRIVER]] which generates # expanded text. The output is useful for passing to other programs # like spell checkers. # # >>Description:: # # >>Limitations:: # # >>Resources:: # # >>Implementation:: # ##### Constants ##### # # >>Description:: # {{Y:ExpandFormat}} is a format driver which outputs expanded text. # sub ExpandFormat { local(*data) = @_; local(@result); local($para_tag, $para_text, %para_attrs); # Process the paragraphs while (($para_text, $para_tag, %para_attrs) = &SdfNextPara(*data)) { # handle directives if ($para_tag =~ /^__(\w+)$/) { push(@result, $para_text) if $1 eq 'inline'; next; } # Format the text $para_text = &_ExpandFormatText($para_text) unless $para_attrs{'verbatim'}; # Build result push(@result, $para_text); } # Return result return @result; } # # >>_Description:: # {{Y:_ExpandFormatText}} formats the text of a paragraph. # sub _ExpandFormatText { local($data) = @_; local($para); local($state); local($sect_type, $text, $char_tag, %sect_attrs); # Build the paragraph body while (($sect_type, $text, $char_tag, %sect_attrs) = &SdfNextSection(*data, *state)) { if ($sect_type eq 'string') { $para .= $text; } elsif ($sect_type eq 'phrase') { $para .= $text; } elsif ($sect_type eq 'phrase_end') { # do nothing } elsif ($sect_type eq 'special') { # do nothing } else { &AppMsg("warning", "unknown section type '$sect_type'"); } } # Return result return $para; } # package return value 1; sdf-2.001/perllib/sdf/app.pl010064400042570001753000001547530671633405200154650ustar00iancmtr00000400000236# $Id$ $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: Application Framework Library # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 12-May-99 ianc Added $app_log_strm support # 28-Apr-99 ianc Added output directory support # 24-Oct-98 ianc _AppConfigLibDir() Mac patch (from David Schooley) # 29-Feb-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # This library provides a common application framework # for [[Perl]] scripts. # # >>Description:: # !include "app.sdf" # # >>Limitations:: # On MS-DOS using BigPerl v2 or v3, redirecting STDOUT after {{Y:AppProcess}} # doesn't work. # # >>Resources:: # # >>Implementation:: # # Save these ASAP. $_app_path is a temporary variable which is # copied to its public counterpart ($app_path) below. $app_path is # defined below so that $app_path, $app_dir and $app_name can # be documented together. $_app_start = time; $_app_path = $0; BEGIN { require "locale.pm" if $] >= 5.004; } require "sdf/name.pl"; require "sdf/misc.pl"; require "sdf/table.pl"; ######### Constants ######### # Configuration parameters @_APP_DETAILED_HELP = ( 'Help', 'Type', 'Array', 'Parameter', 'Initial', 'Default', ); # # >>Description:: # {{Y:$APP_STDIN_ARGS}} is the pseudo argument (default '+') which # causes standard input to be processed as a list of arguments. # Some scripts may wish to use another symbol (i.e. '+' might # be required as a genuine argument), or disable this behaviour # altogether. See {{Y:AppProcess}}. # $APP_STDIN_ARGS = '+'; # Tables of configuration parameters, associated routines, and help %_APP_CONFIG_FN = ( 'calltree', "_AppConfigCallTree", 'inifile', "_AppConfigInifile", 'libdir', "_AppConfigLibDir", 'noecho', "_AppConfigNoEcho", 'parts', "_AppConfigParts", 'product', "_AppConfigProduct", 'test', "_AppConfigTest", 'time', "_AppConfigTime", 'version', "_AppConfigVersion", ); %_APP_CONFIG_HELP = ( 'calltree', "display call tree leading to application exit", 'inifile', "initialisation file to load", 'libdir', "library/configuration directory", 'noecho', "disable argument echoing", 'parts', "display program parts and versions", 'product', "product name", 'test', "verify outputs", 'time', "time program execution", 'version', "program version", ); ######### Variables ######### # # >>Description:: # {{Y:$app_path}}, {{Y:$app_dir}} and {{Y:$app_name}} are the full # pathname, directory and name of the application respectively. # $app_path= $_app_path; ( $app_dir, $app_name ) = &NameSplit($app_path); # # >>Description:: # {{Y:$app_lib_dir}} is the library directory for this application, # i.e. the directory containing configuration files. The default # value is the {{Y:$app_dir}}. This directory is typically set by # searching the Perl library path for the {{libdir}} configuration # parameter, if any. # $app_lib_dir = $app_dir; # >>Description:: # {{Y:@app_exit_routines}} is the stack of routines to be executed # on program termination. If you want a routine to be called # on termination (normal and abnormal), push the name of the # routine onto this stack. These routines will be executed when # {{Y:AppExit}} is called. It is thus advisable to ensure that # {{Y:AppExit}} is NOT called within an exit routine. # @app_exit_routines = (); # # >>Description:: # {{Y:%app_config}} contains the application's configuration parameters. %app_config = (); # # >>Description:: # {{@app_option}} defines the options supported by the application. # The default options are {{help}}, {{out_ext}}, {{log_ext}} and {{out_dir}}. # To append to these, push your arguments onto the array. # For example: # # V: push(@app_option, # V: 'report|STR|report file', # V: ); # # If the script will never have a need for 'per file' output # or errors, assign {{Y:@app_option_core}} # to {{Y:@app_option}} before appending your script-specific options. # For example: # # V: @app_option = @app_option_core; # V: push(@app_option, # V: 'report|STR|report file', # V: ); # # To obtain a concise description of each option, use the help # option with no parameter. Alternatively, detailed help # on a given option can be obtained by suppying the option # name as a parameter. # # By default, output goes to standard output and diagnostics # goes to standard error. These rules can be changed by # specifying the {{out_ext}} and {{log_ext}} options # respectively (and calling {{Y:AppProcess}} to process arguments). # If a string is supplied to these options, it # is treated as the extension of the file to send things to # for each file. If supplied without a parameter, the # extensions default to {{out}} and {{log}} respectively. # A minus character (-) or an equals character (=) can be # used to indicate standard output or standard error # respectively. # # By default, output and log files are created in the current # directory. To specify the same directory as the input file, # specify the {{out_dir}} option without an argument. # To specify an explicit directory, pass that directory as the # argument to the {{out_dir}} option. # @app_option_core = ( 'Option|Spec|Help', 'help|STR;;|display help on options', ); @app_option = ( @app_option_core, 'out_ext|STR;;out|output file extension', 'log_ext|STR;;log|log file extension', 'out_dir;O|STR;.;|output to input file\'s (or explicit) directory', ); # # >>Description:: # {{Y:app_msg_table}} defines the known message types. Each type # is defined by the attributes in the table below. # # !block table # Attribute:Description # Type:message type name # Severity:application exit code caused by this message # Layout:format of message text # !endblock # # # Now that TableParse is used, adding new messages is # # more complicated that it use to be so it's no longer supported.. # # # # If you wish to support additional message types in your # # application, simply append them to this table and rebuild # # {{%app_msg_index}} using {{Y:TableIndex}}. # # {{Layout}} can include the symbols given in the table below. # # !block table # Symbol:Description # $text:user text # $type:message type # $app_name:application name # $ARGV:current argument name (usually a file name) # $app_context:current "context" (e.g. 'line ') # $.:current line number # $app_lineno:current line number (if $. is 0) # !endblock # # The standard message types are explained in the table below. # # !block table; format=325; groups # Tag Severity Description # current object: # object 0 general information # warning 8 something you should know # error 16 something you should fix # abort 24 cannot precede processing # whole application: # app 0 general information # app_warning 10 something you should know # app_error 18 something you should fix # fatal 32 cannot precede processing # non-user messages: # debug 0 debugging diagnostics - ignore # failed 64 internal check failed - notify developer # !endblock # # All messages are output to the standard error stream # with a newline appended and prefixed as follows: # # * {{object}} messages by the current object name # * {{warning}}, {{error}} and {{abort}} by current object name, line number and message type # * {{app}} messages by the application name # * {{app_warning}} messages by the application name and 'warning' # * {{app_error}} messages by the application name and 'error' # * {{fatal}} messages by the application name and 'fatal' # * {{debug}} by application name and 'debug' # * {{failed}} by application name and 'internal failure' # # Most applications only use {{fatal}}, {{abort}}, {{error}} and {{warning}}. # {{fatal}} is used when an application decides to terminate. # (e.g. when an option is illegal.) {{abort}} is used when # an application decides not be precede any further on the # current object (e.g. too many errors encountered). {{error}} # is used when a serious error is detected in processing the # current object. {{warning}} is used when a minor error or # possible error is detected. Typically, an application # continues processing the current object when an error or # warning is encountered but errors prevent further # passes on the object while warnings do not. # @app_msg_table = &TableParse ( 'Type Severity Layout', 'object 0 $ARGV: $text\n', 'warning 8 $ARGV $type, $app_context$.: $text\n', 'error 16 $ARGV $type, $app_context$.: $text\n', 'abort 24 $ARGV $type, $app_context$.: $text\n', 'tst_object 0 # $ARGV: $text\n', 'tst_warning8 # $ARGV $type, $app_context$.: $text\n', 'tst_error 16 # $ARGV $type, $app_context$.: $text\n', 'tst_abort 24 # $ARGV $type, $app_context$.: $text\n', '.warning 8 $ARGV $type, $app_context$app_lineno: $text\n', '.error 16 $ARGV $type, $app_context$app_lineno: $text\n', '.abort 24 $ARGV $type, $app_context$app_lineno: $text\n', 'app 0 $app_name: $text\n', 'app_warning10 $app_name warning: $text\n', 'app_error 18 $app_name error: $text\n', 'fatal 32 $app_name $type: $text\n', 'debug 0 $app_name $type: $text\n', 'failed 64 $app_name internal failure: $text\n', ); # # >>Description:: # {{Y:app_context}} and {{Y:app_lineno}} are the context and line number # used in error messages. {{Y:app_lineno}} is only used if $. is 0. # $app_context = 'line '; $app_lineno = 0; # # >>Description:: # {{Y:%app_msg_index}} is the index into the message table. # (Most programmers have no need for this, but it's provided # in case someone does want it.) # @_app_msg_dupl = (); %app_msg_index = &TableIndex(*app_msg_table, *_app_msg_dupl, 'Type'); # # >>Description:: # {{Y:$app_log_strm}} is a stream on which all messages are # logged to if it's set. If required, this stream is opened and # provided by the user. # $app_log_strm = ''; # Message type log and exit code @_app_msg_type = (); $_app_exit_code = 0; # Usage message buffer and counter $_app_usage = ""; $_app_usage_cnt = 0; # display timing flag $_app_timing = 0; # enable/disable argument echoing flags - if neither if set, echoing # occurs if and only if there is more than one argument $_app_echo = 0; $_app_noecho = 0; # Aliases - null-separated lists of options and associated help, if any %_app_alias = (); %_app_alias_help = (); # # >>Description:: # {{Y:app_product_name}} and {{Y:app_product_version}} are the application # name and version respectively. These are typically set during execution # of the {{AppInit}} routine.) # $app_product_name = ''; $app_product_version = ''; # # >>Description:: # {{Y:app_trace_level}} is the highest level of trace messages output by # {{Y:AppTrace}} for each tracing group. # %app_trace_level = (); # Initialisation file handler $_app_ini_handler = ''; # Test counter $_app_test_counter = 0; ######### Routines ######### # # >>Description:: # {{Y:AppMsg}} outputs a message. The format of the message is # determined by the {{type}} parameter which should be # defined in {{Y:app_msg_table}}. If the type is # unknown, behaviour is undefined. # If {{calltree}} is set, a call tree is dumped after the # message is output. # If {{log_only}} is set, the message is only output # to the {{$app_log_strm}}, if any. # # If a message layout includes the current line number ($.) # and it is 0, {{Y:AppMsg}} uses the dot-version (e.g. ".error") # of the message instead. # # The messages output via {{Y:AppMsg}} influence the exit # code returned to the operating system by {{Y:AppExit}}. # If you wish to influence this but not output a message, # specify a {{type}} parameter without a {{text}} parameter. # sub AppMsg { local($type, $text, $calltree, $log_only) = @_; # local(); local(%type, $msg, $code); # lookup message type %type = &TableLookup(*app_msg_table, *app_msg_index, $type); if ($. == 0 && $type{'Layout'} =~ /\$\./) { %type = &TableLookup(*app_msg_table, *app_msg_index, ".$type"); } # output message to stream after stripping any trailing # newlines and formatting if ($text) { $text =~ s/\n+$//; $msg = eval sprintf('"%s"', $type{'Layout'}); if ($type eq 'tst_object') { printf "%s", $msg; # so make test output is not cluttered } else { printf STDERR ("%s", $msg) unless $log_only; printf $app_log_strm ("%s", $msg) if $app_log_strm ne ''; } } # Dump the call tree, if requested &AppShowCallTree() if $calltree; # log message $code = $type{'Severity'}; $_app_exit_code = $code if $code > $_app_exit_code; push(@_app_msg_type, $type); } # # >>Description:: # {{Y:AppMsgCounts}} returns the number of each message type # found. If you are interested in the message counts since # a particular point in time, a starting index to begin the # counting from can be specified. # sub AppMsgCounts { local($start_index) = @_; local(%count); for (@_app_msg_type[$start_index .. $#_app_msg_type]) { $count{$_}++; } return %count; } # # >>Description:: # {{Y:AppMsgNextIndex}} returns the next index to be used # in the message log. The value returned can be used as # the {{start_index}} parameter to the {{Y:AppMsgCounts}} routine. # sub AppMsgNextIndex { # local() = @_; local($index); return $#_app_msg_type + 1; } # # >>Description:: # {{Y:AppExit}} exits the current application. If a message # is specified, it is first output via {{Y:AppMsg}}. The # exit code returned to the operating system is dependent # on the messages output by {{Y:AppMsg}}. # If {{calltree}} is set, a call tree is dumped after the # message is output. # If {{log_only}} is set, the message is only output # to the {{$app_log_strm}}, if any. # sub AppExit { local($type, $text, $calltree, $log_only) = @_; # local(); local($fn); # Output message, if any &AppMsg($type, $text, undef, $log_only) if $type; # Dump the call tree, if requested &AppShowCallTree() if $calltree; # Execute any requested exit routines while ($fn = pop(@app_exit_routines)) { eval {&$fn}; } # Output timing info, if requested if ($_app_timing) { my $msg; if ($NAME_OS eq 'unix') { $msg = sprintf "execution time: %.2f seconds\n", (times)[0]; } else { $msg = sprintf "execution time: %d seconds\n", time - $_app_start; } print $msg unless $log_only; print $app_log_strm $msg if $app_log_strm ne ''; } # Clost the log stream, if any close($app_log_strm) if $app_log_strm ne ''; # Note: If we're in test mode, return 0 exit( $_app_test_counter > 0 ? 0 : $_app_exit_code); } # # >>Description:: # {{Y:AppTrace}} outputs a trace message if {{group}} tracing is supported and # for that group, the trace level is >= {{level}}. The default group is # called {{user}}. # If {{log_only}} is set, the message is only output # to the {{$app_log_strm}}, if any. # sub AppTrace { local($group, $level, $msg, $log_only) = @_; # local(); my $where = ''; if (group eq '' || $group eq 'user') { if ($app_trace_level{'user'} >= $level) { $where = $level; } } elsif ($app_trace_level{$group} >= $level) { $where = "$group-$level"; } if ($where ne '') { printf STDERR ("[%s] %s\n", $where, $msg) unless $log_only; printf $app_log_strm ("[%s] %s\n", $where, $msg) if $app_log_strm ne ''; } } # # >>Description:: # {{Y:AppInit}} processes options and checks the argument count for a # perl script. The supported options are defined by # @app_option. Options must occur before arguments # and begin with a - character for the short format # or -- for the long format. Option processing is # terminated when either an argument or the -- symbol # is detected. If an environment variable of the # form {{app_name}}OPTS is found, options are first # processed from there. # # The expected number of arguments is derived # from the format of the {{arguments}} parameter as # illustrated by the table below. # # !block table; format=24 # Expected Format # 0 "" # 0 or more "..." # 1 "file" # 1 or more "file ..." # 2 "source destination" # 2 or more "pattern file ..." # 2 or more "file ... destination" # !endblock # # The pattern "..." is used to detect if a variable number of # arguments is permitted. If no arguments are supplied and # one or more are expected, then a concise usage message is # output. If an application does not require an argument, # there is no way to output only a concise usage (use the # help option instead). {{purpose}} is displayed as part of # the usage message. {{product}} is an optional parameter. # If it is supplied and a product of that name exists in the # internal product version lookup table, the product version # is included in the usage too. Note that the usage message # always includes a script version, regardless of whether # a product version is displayed or not. # # If {{Y:AppInit}} encounters an error, it outputs a usage # message and returns 0. Otherwise, it returns 1. # sub AppInit { local($arguments, $purpose, $product, $ini_handler) = @_; local($ok); # my variables local(%opt_short, $env_opts, $usage_msg); # local variables local(@badoptions, @badaliases, @badparams); local(@opt_code, %opt_attr); local($param, $value); # treat product like any other configuration parameter if ($product ne '') { $app_config{'product'} = $product; } # Save the ini-file handler $_app_ini_handler = $ini_handler; # initialise lookup tables: # * %opt_attr contains the attribute values for each option # * @opt_code contains the list of short format codes # * %opt_short converts a long format name to a short format one %opt_attr = &_AppOptsIndex(*opt_code, *opt_short, @app_option); # process configuration parameters, ensuring that: # * the library directory, if any, is the first one processed # * the inifile, if any, is the last one processed if ($app_config{'libdir'}) { &_AppSetConfig('libdir', $app_config{'libdir'}); } for $param (keys %app_config) { next if $param eq 'inifile'; next if $param eq 'libdir'; unless (&_AppSetConfig($param, $app_config{$param})) { &AppExit("failed", "bad app_config key '$param'"); } } if ($app_config{'inifile'}) { &_AppSetConfig('inifile', $app_config{'inifile'}); } # prepend options in the environment variable ${name}OPTS $env_opts = "${app_name}OPTS"; $env_opts =~ tr/[a-z]/[A-Z]/; unshift(@ARGV, split(/ /, $ENV{$env_opts})); # apply the default alias, if any if (defined($_app_alias{$app_name})) { unshift(@ARGV, split("\000", $_app_alias{$app_name})); $purpose = $_app_alias_help{$app_name}; } # process the options option: while (@ARGV) { local($opt_prefix, $opt_text, $opt_code); local($rest, %opt, $action); # check for the options terminator $_ = $ARGV[0]; #print "argument: $_<\n"; if ($_ eq '--') { shift(@ARGV); last option; } # Get next option: # * $opt_code is the short version (set for short AND long) # * $rest is the remainder of the text in this argument # aliases begin with '+' if (/^\+(.+)$/) { if (!defined($_app_alias{$1})) { push(@badaliases, $1); } shift(@ARGV); unshift(@ARGV, split("\000", $_app_alias{$1})); next option; } # configuration parameters begin with '-.' elsif (/^\-\.(.+)$/) { $param = $1; if ($param =~ /^(\w+)[:=](.*)$/) { $param = $1; $value = $2; } else { $value = 1; } shift(@ARGV); unless (&_AppSetConfig($param, $value)) { push(@badparams, $1); } next option; } # long options begin with '--' elsif (/^\-\-(.+)$/) { $opt_text = $1; if ($opt_text =~ /^(\w+)[:=](.*)$/) { $opt_text = $1; $rest = $2; } else { $rest = ''; } $opt_code = $opt_short{$opt_text}; # if full name not given, check for shortest unique format unless ($opt_code) { local(@matches); @matches = grep(/^$opt_text/, keys %opt_short); $opt_code = $opt_short{$matches[0]} if $#matches == 0; } } # short options begin with '-' elsif (/^\-(.)(.*)$/) { $opt_code = $1; $rest = $2; } # if reach here, must be an argument else { last option; } # check option exists %opt = &_AppOption($opt_code); unless (%opt) { push(@badoptions, $_); shift(@ARGV); next option; } # get parameter & process according to type # ($opt_text is passed as a boolean to indicate long or short format) ($action, $usage_msg) = &_AppOptProcess($rest, $opt_text, %opt); last option if $usage_msg; eval $action; if ($@) { &AppExit('failed', "option action '$action' error: '$@'"); } } # Reset usage variables $_app_usage = &_AppBuildUsage($arguments, $purpose); $_app_usage_cnt = 0; # Check usage and return return &_AppCheckUsage($arguments, $usage_msg, *badoptions, *badaliases, *badparams); } # # >>_Description:: # {{Y:_AppOptsIndex}} builds an index of option attributes. # %opt_attr is a lookup table with the option code as the key # @opt_code is the set of short format option codes. # %opt_short converts a long format option name to a short format one. # @opt_strings is assumed to be a set of Tbl strings ready for parsing # by {{Y:TableParse}} into records. # sub _AppOptsIndex { local(*opt_code, *opt_short, @opt_strings) = @_; local(%opt_attr); local(@opt_table); local(@field, %o, $code, $name); local($required, $type, $array, $validate, $init, $default); local($str, $n, $v); # Parse the option strings into records @opt_table = &TableParse(@opt_strings); @opt_code = (); %opt_short = (); @field = &TableFields(shift(@opt_table)); for $o (@opt_table) { %o = &TableRecSplit(*field, $o); # determine option code & long name if ($o{'Option'} =~ /;/) { $o{'Option'} = $`; $code = $'; } else { $code = substr($o{'Option'}, 0, 1); } $name = $o{'Option'}; # check option code & name are unique if (grep(/^$code$/, @opt_code)) { &AppExit("failed", "option code '$code' not unique"); } elsif ($opt_short{$name}) { &AppExit("failed", "option name '$name' not unique"); } $o{'Code'} = $code; # determine type-related attributes ($type, $init, $default) = split(/;/, $o{'Spec'}); $array = ''; $validate = ''; $required = ''; if ($type ne 'BOOL') { $required = ($o{'Spec'} =~ /;.*;/) ? 'maybe' : 'yes'; if ($type =~ /^(\w+)\-/) { $type = $1; $validate = $'; } if ($type =~ /(LIST|HASH)$/) { $type = $`; $array = $1; } } $o{'Parameter'} = $required if $required; $o{'Type'} = $type; $o{'Array'} = $array if $array; $o{'Initial'} = $init; $o{'Default'} = $default if $required eq 'maybe'; $o{'Validate'} = $validate if $validate; # some semantic checks unless (grep(/^$type$/, 'BOOL', 'STR', 'INT', 'NUM', 'ROUTINE')) { &AppExit("failed", "unknown option type '$type' for option '$code'"); } if ($type eq 'ROUTINE' && ! $validate) { &AppExit('failed', "unknown routine for option '$name'"); } # initialise option, if required if ($init) { local($action); $action = &_AppAction($init, 1, %o); eval $action; if ($@) { &AppExit('failed', "action '$action' error: '$@'"); } } # save this option $str = ''; $str .= "$n=$v\000" while ($n, $v) = each %o; $opt_attr{$code} = $str; #print "code:$code<\n"; #print "data:$opt_attr{$code}<\n"; push(@opt_code, $code); $opt_short{$name} = $code; } # Return result return %opt_attr; } # # >>_Description:: # {{Y:_AppOption}} returns the attributes of an option. # sub _AppOption { local($opt_code) = @_; local(%opt); local($nv); for $nv (split(/\000/, $opt_attr{$opt_code})) { $opt{$`} = $' if $nv =~ /\=/; } # Return result return %opt; } # # >>_Description:: # {{Y:_AppOptProcess}} processes an option, updating the ARGV array # as it goes. If {{long}} is true, the option is processed as a long # option, otherwise short. # sub _AppOptProcess { local($rest, $long, %opt) = @_; local($action, $usage_msg); local($param, $required, $default_used, $missing); if ($long) { shift(@ARGV); $param = $rest; } else { # handle required parameter $required = $opt{'Parameter'}; if ($required eq 'yes') { shift(@ARGV); if ($rest ne '') { $param = $rest; } elsif (@ARGV) { $param = shift(@ARGV); } else { $missing = $opt{'Option'}; } } # handle optional parameter elsif ($required eq 'maybe') { shift(@ARGV); if ($rest ne '') { $param = $rest; } else { $param = $opt{'Default'}; $default_used = 1; } } # handle no parameter else { if ($rest ne '') { $ARGV[0] = "-$rest"; } else { shift(@ARGV); } } } # Get action (if all ok) if ($missing) { $usage_msg = "parameter required for option $missing"; } else { $param = 1 if $opt{'Type'} eq 'BOOL'; $action = &_AppAction($param, $default_used, %opt); } # Return result return ($action, $usage_msg); } # # >>_Description:: # {{Y:_AppAction}} returns a Perl expression to be eval'ed. # For arrays, if $init is true, the array is initialised # to the value specified, otherwise, the value is appended. # sub _AppAction { local($value, $init, %opt) = @_; local($action); local($id); $id = $opt{'Option'}; if ($opt{'Type'} eq 'ROUTINE') { # Pass parameter as string $value =~ s/(['\\])/\\$1/g; $value = "'$value'"; $action = "&$opt{'Validate'}($value)"; } elsif ($opt{'Array'} eq 'LIST') { if ($opt{'Type'} eq 'STR') { local(@value); @value = split(/,/, $value); for $v (@value) { $v =~ s/(['\\])/\\$1/g; $v = "'$v'"; } $value = join(',', @value); } if ($init) { $action = "\@$id = ($value)"; } else { $action = "push(\@$id, $value)"; } } elsif ($opt{'Array'} eq 'HASH') { local(@key, @value, $key, $v); @key = split(/,/, $value); for $k (@key) { if ($k =~ /^(\w+)[:=]/) { $k = "'$1'"; $v = $'; if ($opt{'Type'} eq 'STR') { $v =~ s/(['\\])/\\$1/g; $v = "'$v'"; } } else { $k = "'$k'"; $v = 1; } push(@value, $v); } $key = join(',', @key); $value = join(',', @value); $action = '@' . $id . "{$key} = ($value)"; $action = "undef %$id;" . $action if $init; } else { if ($opt{'Type'} eq 'STR') { $value =~ s/(['\\])/\\$1/g; $value = "'$value'"; } $action = "\$$id = $value"; } # Return result return $action; } # # >>_Description:: # _AppCheckUsage() checks if a usage message is required. If it is, # it outputs one together with any necessary supporting messages. # It returns 1 if things are fine. # sub _AppCheckUsage { local($arguments, $usage_msg, *badoptions, *badaliases, *badparams) = @_; local($ok); local(%badvalue, %opt, $check, $min, $max, @ok); local($args_reqd, $args_variable, $args_left, $arg_missing); # validate options %badvalue = (); check: for $opt (@opt_code) { %opt = &_AppOption($opt); if ($opt{'Validate'} && $opt{'Type'} ne 'ROUTINE') { # build the check string if ($opt{'Type'} eq 'STR') { $check = 'grep(/^$value$/, ' . $opt{"Validate"} . ')'; } else { ($min, $max) = split(/,/, $opt{'Validate'}); if ($min eq '' && $max ne '') { $check = '$value <= $max'; } elsif ($min ne '' && $max eq '') { $check = '$min <= $value'; } elsif ($min ne '' && $max ne '') { $check = '$min <= $value && $value <= $max'; } else { next check; } } # check the value(s) if ($opt{'Array'} eq 'LIST') { for $value (eval "\@$opt{'Option'}") { if ($opt{'Type'} eq 'STR') { $value =~ s/(\W)/\\$1/g; } unless (eval $check) { $badvalue{$opt{'Option'}} = $value; next check; } } } elsif ($opt{'Array'} eq 'HASH') { for $value (eval "values \%$opt{'Option'}") { if ($opt{'Type'} eq 'STR') { $value =~ s/(\W)/\\$1/g; } unless (eval $check) { $badvalue{$opt{'Option'}} = $value; next check; } } } else { $value = eval "\$$opt{'Option'}"; if ($opt{'Type'} eq 'STR') { $value =~ s/(\W)/\\$1/g; } unless (eval $check) { $badvalue{$opt{'Option'}} = $value; } } } } # check the argument count $args_reqd = split(/ /, $arguments); if ($args_variable = ($arguments =~ /\.\.\./)) { $args_reqd--; } $args_left = scalar(@ARGV); if (! $usage_msg) { if ($args_reqd && $args_left == 0) { $arg_missing = 1; } elsif ($args_variable && $args_left < $args_reqd) { $arg_missing = 1; $usage_msg = "at least $args_reqd arguments required" . " - $args_left supplied"; } elsif (! $args_variable && $args_left != $args_reqd) { $arg_missing = 1; $usage_msg = "$args_reqd arguments required" . " - $args_left supplied"; } } # Output usage, if required $ok = 1; if (defined $help || $usage_msg || @badoptions || @badaliases || @badparams || %badvalue || $arg_missing) { &AppPrintUsage(); $ok = 0; } # Output help on option requested or all options/aliases # if the option requested does not exist, show the options/aliases if (@badoptions || @badaliases || defined $help) { %opt = &_AppOption($help); if (%opt) { printf "Detailed help on option: -%s,--%s\n\n", $help, $opt{'Option'}; printf "%-10.10s %s\n", 'Attribute', 'Value'; for $attr (@_APP_DETAILED_HELP) { if (defined $opt{$attr}) { printf "%-10.10s %s\n", $attr, $opt{$attr}; } } if ($opt{'Validate'} && $opt{'Type'} ne 'ROUTINE') { if ($opt{'Type'} eq 'STR') { @ok = eval "$opt{'Validate'}"; printf "%-10.10s %s\n", 'Legal', join(', ', @ok); } else { ($min, $max) = split(/,/, $opt{'Validate'}); printf "%-10.10s %d..%d\n", 'Range', $min, $max; } } } else { print "options:\n"; for $opt (@opt_code) { %opt = &_AppOption($opt); printf "-%s, --%-15.15s %s\n", $opt, $opt{'Option'}, $opt{'Help'}; } if ($_app_alias{$app_name} eq '' && %_app_alias_help) { print "aliases:\n"; for $opt (sort keys %_app_alias_help) { printf "+%-15.15s %s\n", $opt, $_app_alias_help{$opt}; } } } } # Print configuration parameters if (@badparams) { print "configuration parameters:\n"; for $opt (sort keys %_APP_CONFIG_HELP) { printf "%-10.10s %s\n", $opt, $_APP_CONFIG_HELP{$opt}; } } # Print bad options if (@badoptions) { print "\n"; for $opt (@badoptions) { &AppMsg('fatal', "unknown or non-unique option '$opt'"); } } # Print bad aliases if (@badaliases) { print "\n"; for $opt (@badaliases) { &AppMsg('fatal', "unknown alias '$opt'"); } } # Print bad configuration parameters if (@badparams) { print "\n"; for $opt (@badparams) { &AppMsg('fatal', "unknown configuation parameter '$opt'"); } } # Print bad values if (%badvalue) { for $value (sort keys %badvalue) { &AppMsg('fatal', sprintf("bad %s value '%s'", $value, $badvalue{$value})); } } # Print usage message if ($usage_msg) { &AppMsg('fatal', $usage_msg); } # Return result return $ok; } # # >>Description:: # {{Y:AppPrintUsage}} outputs the usage header message build during the # last call to {{Y:AppInit}}. Only the first call to this routine # (after {{Y:AppInit}} is called) will print the message. This # allows programmers to do additional validation after {{Y:AppInit}} # returns and know that only one usage header message will be output. # sub AppPrintUsage { # local() = @_; # local(); if ($_app_usage_cnt++ == 0) { print $_app_usage; } } # # >>_Description:: # {{Y:_AppBuildUsage}} builds and returns a usage message, based on the # options defined in @app_option. # sub _AppBuildUsage { local($arguments, $purpose) = @_; local($text); local($usage); local(%o, $required, $code, $desc, $version); local($product_info); # build usage string - application name and aliases $text = $app_name; if ($_app_alias{$app_name} eq '' && %_app_alias) { $text .= " [+alias]"; } # build usage string - options for $opt (@opt_code) { %o = &_AppOption($opt); $required = $o{'Parameter'}; # determine usage $code = $o{'Code'}; $desc = $o{'Option'}; $desc .= ",.." if $o{'Array'}; if ($required eq 'yes') { $usage = "$code $desc"; } elsif ($required eq 'maybe') { $usage = $code . "[$desc]"; } else { $usage = "$code"; } $text .= " [-$usage]"; } # Get version: # * use public one if available, otherwise physical version # * strip RCS/SCCS stuff $version = $VERSION{'PUBLIC'}; $version = $VERSION{$app_path} unless $version; if ($version =~ /^\$\w+: (.*)\$$/) { $version = $1; } elsif ($version =~ /^\@\(\#\)\s*(.*)$/) { $version = $1; } # Get product info, if any $product_info = ''; if ($app_product_name) { $product_info = " ($app_product_name $app_product_version)"; } # Return result return "usage : $text $arguments\n". "purpose: $purpose\n". "version: $version$product_info\n"; } # # >>_Description:: # {{Y:_AppSetConfig}} sets a configuration parameter. # It returns true if the parameter is known. # sub _AppSetConfig { local($param, $value) = @_; local($ok); local($fn); # process the associated action $fn = $_APP_CONFIG_FN{$param}; if ($fn) { $app_config{$param} = $value; eval {&$fn($value)}; &AppExit('fatal', $@) if $@; } # Return result return $fn; } # # >>_Description:: # {{Y:_AppConfigLibDir}} sets the library directory. # sub _AppConfigLibDir { local($value) = @_; # local(); local($inc); my $nom_path; # Search the library path for the nominated directory for $inc (@INC) { $nom_path = "$inc/$value"; $nom_path =~ s#:*/+#:#g if $^O eq 'MacOS'; if (-d $nom_path) { $app_lib_dir = $nom_path; return; } } } # # >>_Description:: # {{Y:_AppConfigInifile}} loads an inifile. # sub _AppConfigInifile { local($value) = @_; # local(); local($fname); local(%inidata, $section, %config); local($product); local($alias_name, $alias_help, @alias_opts); local($next_inifile, $param); # Find the file $fname = &NameFind($value, ".", $app_lib_dir); if ($fname eq '') { &AppExit("fatal", "initialisation file '$value' not found"); } # Fetch the file %inidata = &_AppFetchInifile($fname); # Get the configuration for later processing %config = &AppSectionValues($inidata{'Configuration'}); delete $inidata{'Configuration'}; # If this is also the product ini-file, process it accordingly $product = $app_config{'product'}; $product =~ tr/A-Z/a-z/; if ($value eq "$product.ini") { &_AppProductIni($fname, *inidata); } # Process the standard data for $section (sort keys %inidata) { if ($section =~ /^Alias\s+(\w+)/) { $alias_name = $1; ($alias_help) = ($' =~ /^\s*:\s*(.*)$/); @alias_opts = &_AppSectionList($inidata{$section}); for $param (@alias_opts) { $param = "--$param"; } &_AppStoreAlias($alias_name, $alias_help, @alias_opts); # Remove the processed data from the configuration file delete $inidata{$section}; } } # Process the user data if ($_app_ini_handler) { eval {&$_app_ini_handler($fname, *inidata)}; } # Warn about the unknown sections for $section (sort keys %inidata) { &AppMsg("warning", "unknown section '$section' in initialisation file '$fname'"); } # Process the configuration $next_inifile = $config{'inifile'}; delete $config{'inifile'}; for $param (keys %config) { &_AppSetConfig($param, $config{$param}); } if ($next_inifile ne '') { &_AppSetConfig('inifile', $next_inifile); } } # # >>_Description:: # {{Y:_AppFetchInifile}} fetches an inifile. # Each section is returned as an entry in {{%data}}. # Within each section, lines are terminated by a newline. # sub _AppFetchInifile { local($inifile) = @_; local(%data); local($section, $_); # Open the file unless (open(INIFILE, $inifile)) { &AppExit("fatal", "unable to open initialisation file '$inifile'"); } # Read the data while () { # skip blank and comment lines s/^\s+//; s/\s+$//; next if /^$/ || /^#/ || /^;/; # change the section or add data to the current section if (/^\[(.*)\]$/) { $section = $1; } else { $data{$section} .= "$_\n"; } } # Close the file close(INIFILE); # Return result return %data; } # # >>_Description:: # {{Y:_AppSectionList}} converts an inifile section into a list. # sub _AppSectionList { local($text) = @_; local(@data); # Return result return split("\n", $text); } # # >>Description:: # {{Y:AppSectionValues}} converts an inifile section into a set of # name-value pairs. # sub AppSectionValues { local($strs) = @_; local(%values); local($line); # process the lines for $line (split("\n", $strs)) { if ($line =~ /^\s*([\w\.]+)\s*\=\s*(.*)\s*$/) { $values{$1} = $2; } } # Return result return %values; } # # >>_Description:: # {{Y:_AppStoreAlias}} stores an alias. # sub _AppStoreAlias { local($name, $help, @options) = @_; # local(); $_app_alias{$name} = join("\000", @options); $_app_alias_help{$name} = $help; } # # >>_Description:: # {{Y:_AppConfigVersion}} sets the version number of a script. # sub _AppConfigVersion { local($value) = @_; # local(); $VERSION{'PUBLIC'} = $value; } # # >>_Description:: # {{Y:_AppConfigProduct}} makes this script part of the nominated product. # sub _AppConfigProduct { local($value) = @_; # local(); local($inifile); local($fname); local($section); # Save the product name $app_product_name = $value; # Get the product ini-file $value =~ tr/A-Z/a-z/; $inifile = &NameJoin('', $value, 'ini'); # Skip processing it if it's going to be done later return if $inifile eq $app_config{'inifile'}; # Load and process the ini-file data $fname = &NameFind($inifile, ".", $app_lib_dir); if ($fname eq '') { &AppExit("fatal", "initialisation file '$value' not found"); } %inidata = &_AppFetchInifile($fname); &_AppProductIni($fname, *inidata); # Ignore aliases in the product ini-file data for $section (sort keys %inidata) { if ($section =~ /^Alias\s+(\w+)/) { delete $inidata{$section}; } } # Process the user data if ($_app_ini_handler) { eval {&$_app_ini_handler($fname, *inidata)}; # Warn about the unknown sections - but only if the application # has an ini file handler (otherwise, warnings are produced for # commands which share a product ini file) for $section (sort keys %inidata) { &AppMsg("warning", "unknown section '$section' in initialisation file '$fname'"); } } } # # >>_Description:: # {{Y:_AppProductIni}} processes the product-specific ini-file data. # sub _AppProductIni { local($fname, *inidata) = @_; # local(); local($section, %values, $key); # Process the infile for $section (keys %inidata) { if ($section eq 'Product') { %values = &AppSectionValues($inidata{$section}); for $key (keys %values) { if ($key eq 'version') { $app_product_version = $values{$key}; } else { &AppMsg("warning", "unknown [Product] parameter '$key' in initialisation file '$fname'"); } } # Remove the processed data from the configuration file delete $inidata{$section}; } } } # # >>_Description:: # {{Y:_AppConfigTest}} enables verification of the output files. # If value is a number, Perl-style test output is generated and # the first test has that number. Otherwise, the value is the name # of the verification routine to use. # sub _AppConfigTest { local($value) = @_; # local(); # Ensure output and log file are generated & disable argument echoing unshift(@ARGV, '-o', '-l'); $_app_noecho = 1; # The default test handler is _AppVerifyOutputs if ($value =~ /^\d+$/) { $_app_test_fn = '_AppVerifyOutputs'; $_app_test_counter = $value; } else { $_app_test_fn = $value; } } # # >>_Description:: # {{Y:_AppConfigNoEcho}} disables argument echoing. # sub _AppConfigNoEcho { local($value) = @_; # local(); $_app_noecho = 1; } # # >>_Description:: # {{Y:_AppConfigTime}} enables timing the execution of a program. # sub _AppConfigTime { local($value) = @_; # local(); $_app_timing = 1; } # # >>_Description:: # {{Y:_AppConfigParts}} enables the display (upon exit) of the # components (and their versions) making up this application. # sub _AppConfigParts { local($value) = @_; # local(); push(@app_exit_routines, "AppShowParts"); } # # >>_Description:: # {{Y:_AppConfigCallTree}} enables the display (upon exit) of the # call tree of routines. # sub _AppConfigCallTree { local($value) = @_; # local(); push(@app_exit_routines, "AppShowCallTree"); } # # >>_Description:: # {{Y:_AppVerifyOutputs}} compares {{outfile}} and {{logfile}} to # verified files in the {{checked}} directory. Files which match are # deleted. Files which do not match are kept so that the developer # can diff the errors. # sub _AppVerifyOutputs { local($infile, $outfile, $logfile) = @_; # local(); # Verify the output file &_AppVerifyFile($outfile, &NameJoin("checked", $outfile), 'output'); # Verify the log file &_AppVerifyFile($logfile, &NameJoin("checked", $logfile), 'log'); } # # >>_Description:: # {{Y:_AppVerifyFile}} compares a test file against a checked file. # sub _AppVerifyFile { local($test, $check, $type) = @_; local($ok); local($testdata, $checkdata); # Get the data from the test file unless (open(TESTFILE, $test)) { &AppMsg("tst_error", "unable to open $type data file '$test' for testing"); return 0; } $testdata = join('', ); close TESTFILE; # Get the data from the check file unless (open(CHECKFILE, $check)) { &AppMsg("tst_error", "unable to open $type check file '$check' for testing"); return 0; } $checkdata = join('', ); close CHECKFILE; # Compare the data if ($testdata eq $checkdata) { &AppMsg("tst_object", "$type file ok"); printf "ok %d\n", $_app_test_counter++; unlink $test; return 1; } else { &AppMsg("tst_object", "$type file FAILED"); printf "not ok %d\n", $_app_test_counter++; return 0; } } # # >>Description:: # {{Y:AppShowParts}} displays the versions of components making up # this application and exits. To support this facility, each library # should include a line of the form: # # . $VERSION{__FILE__} = "x.y" # # Strings containing SCCS or RCS stuff have the baggage stripped. # For example: # # * '@(#) 3.2' is displayed as '3.2' # * '$Revision: 1.27 $' is displayed as '3.3' # # {{Y:AppShowParts}} is usually called via the '.parts' special # help option. However, certain application code might have a # need to call it directly. # sub AppShowParts { # local = @_; # local(); local($version); for (sort keys %VERSION) { $version = $VERSION{$_}; if ($version =~ /^\$\w+: (.*)\$$/) { $version = $1; } elsif ($version =~ /^\@\(\#\)\s*(.*)$/) { $version = $1; } printf "%-16s %s\n", $version, $_; } } # # >>Description:: # {{Y:AppShowCallTree}} displays the call tree (excluding the call # to itself). The routine is usually called indirectly: # # * via {{Y:AppMsg}} or {{Y:AppExit}} ({{calltree}} parameter set), or # * via the .calltree special help parameter # # Like {{Y:AppShowComponents}}, certain application code may wish to # call {{Y:AppShowCallTree}} directly. # sub AppShowCallTree { # local() = @_; # local(); local($i,$p,$f,$l,$s,$h,$a,@a,@sub); for ($i = 1; ($p,$f,$l,$s,$h,$w) = caller($i); $i++) { @a = @DB'args; for (@a) { if (/^StB\000/ && length($_) == length($_main{'_main'})) { $_ = sprintf("%s",$_); } else { s/'/\\'/g; s/([^\0]*)/'$1'/ unless /^-?[\d.]+$/; s/([\200-\377])/sprintf("M-%c",ord($1)&0177)/eg; s/([\0-\37\177])/sprintf("^%c",ord($1)^64)/eg; } } $w = $w ? '@ = ' : '$ = '; $a = $h ? '(' . join(', ', @a) . ')' : ''; push(@sub, "$f $l: $w&$s$a\n"); } print STDERR "CALL TREE IS..\n"; for ($i=0; $i <= $#sub; $i++) { print STDERR $sub[$i]; } print STDERR "END CALL TREE.\n"; } # # >>Description:: # {{Y:AppProcess}} processes each argument on the command-line. # In particular, it does the following for each argument: # # * if the argument is '+', processes each line of standard input # as an argument # * if a file matching an argument is not found, but {{default_ext}} is # supplied and adding that extension results in a file being found, # then {{default_ext}} is added as an extension to the argument # * echos the argument to standard error if there is more than one # * if $out_ext is set, opens an output file for the current # argument and redirects STDOUT to it # * if $log_ext is set, opens a log file for the current # argument and redirects STDERR to it # * calls {{arg_process_fn}} # * close the output and log files, returning STDOUT and STDERR back # to their initial state # * calls {{arg_post_process_fn}}, if any # # Note that {{arg_post_process}} # is optional - it is only used in scripts which need to # do additional processing on an file {{after}} output streams # have been closed. # # {{arg_process_fn}} has the following interface: # # V: $err = &arg_process_fn($arg) # # {{arg_post_process_fn}} has the following interface: # # V: $err = &arg_post_process_fn($arg, $arg_err) # # where {{arg_err}} is the error code returned by {{arg_process_fn}}. # {{Y:AppProcess}} returns the highest error code it encounters from # the user processing functions it calls. # # If you need to disable the special meaning of '+', set the # {{Y:APP_STDIN_ARGS}} configuration constant to an empty string. # Likewise, you can change the character used by setting it # to another value, although this is not recommended given the # consistency implications. # sub AppProcess { local($arg_process_fn, $arg_post_process_fn, $default_ext) = @_; local($app_err); local($echo_args, $stdin_read, @stdin_args); local($in_dir, $base, $ext, $dir, $outfile, $logfile); local($base_ext); local($arg_err, $post_err); # Decide if we should echo arguments $echo_args = @ARGV > 1 && !$_app_noecho; # Loop through the arguments argument: while ($ARGV = shift(@ARGV)) { # Process stdin as a list of arguments, if requested if (! $stdin_read && $ARGV eq $APP_STDIN_ARGS) { # append the arguments to the front of ARGV @stdin_args = ; chop(@stdin_args); unshift(@ARGV, @stdin_args); # update echoing accordingly $echo_args || ($echo_args = @ARGV > 1 && !$_app_noecho); $stdin_read = 1; next argument; } # Append the default extension, if necessary and supplied if (! -f $ARGV && $default_ext ne '') { $base_ext = &NameJoin('', $ARGV, $default_ext); $ARGV = $base_ext if -f $base_ext; } # init the per argument stuff $arg_err = 0; ($in_dir, $base, $ext) = &NameSplit($ARGV); # echo the argument name if ($echo_args || $_app_echo) { print STDERR "$ARGV:\n"; } # decide the output directory if ($out_dir eq '.') { $dir = ''; } elsif ($out_dir eq '') { $dir = $in_dir; } else { $dir = $out_dir; } # decide on output and log streams $outfile = ''; $logfile = ''; if ($out_ext && -f $ARGV && $out_ext ne '-') { if ($out_ext eq '=') { $outfile = "&STDERR"; } else { $outfile = &NameJoin($dir, $base, $out_ext); } } if ($log_ext && -f $ARGV && $log_ext ne '=') { if ($log_ext eq '-') { $logfile = "&STDOUT"; } else { $logfile = &NameJoin($dir, $base, $log_ext); } } # if required, redirect output and log streams if ($outfile) { unless (open(APP_OUT, ">&STDOUT")) { print STDERR "failed to save stdout: $!"; } unless (open(STDOUT, "> $outfile")) { print STDERR "failed to redirect stdout: $!"; } } if ($logfile) { unless (open(APP_ERR, ">&STDERR")) { print STDERR "failed to save stderr: $!"; } unless (open(STDERR, "> $logfile")) { print APP_ERR "failed to redirect stderr: $!"; } } # process each argument $arg_err = &$arg_process_fn($ARGV); # if required, close the output/log files if ($logfile) { unless (close(STDERR)) { print APP_ERR "failed to close stderr: $!"; } unless (open(STDERR, ">&APP_ERR")) { print STDERR "failed to re-open stderr: $!"; } } if ($outfile) { unless (close(STDOUT)) { print STDERR "failed to close stdout: $!"; } unless (open(STDOUT, ">&APP_OUT")) { print STDERR "failed to re-open stdout: $!"; } } # do the post processing, if any if ($arg_post_process_fn) { $post_err = &$arg_post_process_fn($ARGV, $arg_err); } # do the test function, if any if ($_app_test_fn) { &$_app_test_fn($ARGV, $outfile, $logfile); } # update the overall error code $app_err = $arg_err if $arg_err > $app_err; $app_err = $post_err if $post_err > $app_err; } # return result return $app_err; } # package return value 1; test_fn = $value; sdf-2.001/perllib/sdf/dict.pl010064400042570001753000000167310661420514000156110ustar00iancmtr00000400000236# $Id$ $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: Dictionary Library # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 04-Oct-97 ianc Fixed bug with * in reports # 29-Feb-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # This library provides support for reading and processing # dictionaries stored in text files. # # >>Description:: # A dictionary is a collection of items where each item has: # # * a unique key # * a description # # >>Limitations:: # # >>Resources:: # # >>Implementation:: # ##### Constants ##### # # >>Description:: # {{Y:DICT_DFLT_REPORT}} is the default report for {{Y:DictPrint}}. It: # # * outputs items in the order found, separated by blank lines # * outputs each item as: # - key on one line # - description on the next # @DICT_DFLT_REPORT = &TableParse ( 'Key Format', '* "$key\n$data\n\n"', ); ##### Variables ##### # # >>Description:: # {{Y:dict_rest}} is the set of lines in the last file processed # by {{Y:DictFetch}} which are not in the dictionary. # @dict_rest = (); $_dict_cnt = 0; $_dict_debug = 0; ##### Routines ##### # # >>Description:: # {{Y:DictFetch}} inputs filename as a dictionary. # sub DictFetch { local($file, $begin, $delimiter, $end, $prefix) = @_; local($success); local($strm, $line, $key, @desc, $new_key, $rest, $ch); local($Buffers); local(@bufferlist) = 'main'; # array of buffer names local($get_scope) = 0; local($doc_scope) = 0; # scope of doco to be extracted local($bufref); # initialise the default buffer entry $Buffers = new Sdfget; # set the scope for the documentation to be extracted $get_scope = $Buffers->getScope($scope); # Open the input stream $strm = sprintf("dct_s%d", $_dict_cnt++); open($strm, $file) || return (0, ()); # Input the data @dict_rest = (); line: while (<$strm>) { # Handle the line prefix, if any $line = $_; if ($prefix && ! s/^$prefix//) { # Save away the previous record, if any. if ($key) { print STDERR "Key: $key - Text: @desc...\n" if $_dict_debug; $Buffers->addText ($key, \@desc, @bufferlist); $key = ""; @desc = (); } push(@dict_rest, $line); next line; } # Check for end line. Note that this test must be before # the "check for begin line", so that things work as expected. # (Thanks to Keith Ponting for fixing this.) if (/^$end/) { # Save away the previous record, if any. if ($key) { print STDERR "Key: $key - Text: @desc...\n" if $_dict_debug; $Buffers->addText($key, \@desc, @bufferlist); $key = ""; @desc = (); } } # process possible `sdfget' directives if ( /^$begin!use .*$/ ) { print STDERR "In use...line: $line\n" if $_dict_debug; ($doc_scope, @bufferlist) = &Sdfget::UseArgs($line); while ($doc_scope > $get_scope ) { # terminate processing of there is no more input last line if ! $doc_scope; # consume the rest of this section ($doc_scope, @bufferlist) = $Buffers->NextSection ($strm); } next line; } # Check for begin line elsif (/^$begin(.+)$delimiter(.*)$/) { $new_key = $1; $rest = $2; print STDERR "Key: $key - Text: @desc...\n" if $key && $_dict_debug; # Save away the previous record, if any. $Buffers->addText($key, \@desc, @bufferlist) if $key; # Check for description on same line if ($rest) { # Save away the new record @desc = ($rest); print STDERR "Key: $new_key - Text: @desc...\n" if $_dict_debug; $Buffers->addText($new_key, \@desc, @bufferlist); $key = ""; @desc = (); } else { $key = $new_key; @desc = (); } } # Check for description line elsif ($key) { push(@desc, $_); } # Otherwise, not part of dictionary else { push(@dict_rest, $line); } } close($strm); # Save away the previous record, if any. if ($key) { print STDERR "Key: $key - Text: @desc...\n" if $_dict_debug; $Buffers->addText($key, \@desc, \@bufferlist); } # trim the trailing new-line on each description $Buffers->TrimDesc(); # return results return (1, $Buffers); } # # >>Description:: # {{Y:DictPrint}} outputs a dictionary using report. If no # report is specified, {{Y:DICT_DFLT_REPORT}} is used. # sub DictPrint { local($strm, $level, $buffer_name, $bufref, @report) = @_; local($ok); local(@item, $itemarrayref, %item, $itemhashref); local(@rep_field, %val, @local_report); local($key, $fmt, $err); local($dict_ref, $dict_hash, $dict_keys); local($alt_buffer); # Init things ($itemarrayref, $itemhashref) = $bufref->Sdfget::getKeysDocs($buffer_name); @item = @$itemarrayref; %item = %$itemhashref; @report = @DICT_DFLT_REPORT unless @report; @my_report = @report; # Check report table has required fields @rep_field = &TableFields(shift(@my_report)); return 0 unless grep(/^Key$/, @rep_field); return 0 unless grep(/^Format$/, @rep_field); # Output report for $report (@my_report) { %val = &TableRecSplit(*rep_field, $report); $key = $val{'Key'}; $fmt = $val{'Format'}; # Handle 'all remaining' if ($key eq '*') { for $item (@item) { if (defined $item{$item}) { $err += &_DictItemFmt($strm, $fmt, $item, $item{$item}); } } } # Handle free text elsif ($key eq '-') { $err += &_DictItemFmt($strm, $fmt); } elsif ($key =~ /\+.*/ && ! $level) { $key =~ /\+(.*)/; if ($1 eq '*') { foreach $alt_buffer (keys %$bufref){ next if ( $alt_buffer eq 'main'); print $strm "# Buffer: $alt_buffer\n"; print $strm "!slide_down\n"; &DictPrint($strm, ++$level, $alt_buffer, $bufref, @report); print $strm "!slide_up\n"; } } else { print $strm "!slide_down\n"; print $strm "Buffer: $alt_buffer\n"; &DictPrint($strm, ++$level, $1, $bufref, @report); print $strm "!slide_up\n"; } } # Handle this item else { if ($fmt && $item{$key}) { $err += &_DictItemFmt($strm, $fmt, $key, $item{$key}); } delete $item{$key}; } } # Return result return $err == 0; } # # >>_Description:: # {{Y:_DictItemFmt}} formats and prints an item on a stream. # {{$fmt}} is a Perl string to be evaluated. # {{$key}} and {{$data}} are the key and description of the item. # {{$ARGV}} is assumed to be the current file. # sub _DictItemFmt { local($strm, $fmt, $key, $data) = @_; local($err); local($str); local($dir, $base, $ext, $short); # Get file info ($dir, $base, $ext, $short) = &NameSplit($ARGV); # Print item $str = eval $fmt; if ($@) { &AppMsg('error', $@); return 1; } print $strm $str; # Return result return 0; } # package return value 1; sdf-2.001/perllib/sdf/calc.pl010064400042570001753000000626040661420514000155700ustar00iancmtr00000400000236# $Id$ $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: Calculation Library # # >>Copyright:: # Copyright (c) 1996, Tim Hudson (tjh@mincom.com) # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 19-Feb-97 tjh worked around a perl4 bug with complex substitution # ................. expressions with escaped double quotes # 18-Feb-97 tjh handle money (i.e. $1,250.75 is okay now) and # ................. FORMAT("money",EXPR) is supported too # 17-Feb-97 tjh FORMAT and PRECISION added along with ROWPRODUCT # ................. ROWAVERAGE, COLUMNPRODUCT, COLUMNAVERAGE # 17-Feb-97 tjh report errors with AppMsg so we get line numbers # ................. so we can actually debug things without poking into # ................. the code when things go wrong # 03-Jan-97 tjh added recursion support and extra functions # 03-Jan-97 tjh expanded prototype into new format for SDF2beta8 # 02-Jan-97 tjh original coding # ----------------------------------------------------------------------- # # >>Purpose:: # This library provides basically a mini-spreadsheet for using in tables # inside SDF # # >>Description:: # This requires SDF verion 2beta8 or above (which adds in a few new things # so that we have a nice syntax for calculations) # # This can be made to work in SDF2beta7c but it is worth upgrading to # a supported release :-) # # Calculation support for a table is activated by adding in an attribute # of calc (which triggers keeping track of the table contents in a cell # grid for later processing). # # A simple example: # # !block comment # !block table; format="10,20,70"; style="box" # Count Price Total # 10 5 \[\[=ROWPROD\]\] # 15 5.23 \[\[=ROWPROD\]\] # \[\[=COLSUM]] \[\[=COLSUM\]\] \[\[=COLSUM\]\] # !endblock # !endblock # # NB: # values are available until the next table is processed so # you can refer to data inside "normal" paragraphs after the table # NE: # # >>Limitations:: # # >>Resources:: # # >>Implementation:: # # (Yes Ian ... I did mean to add in the stanard SDF-like header stuff # above so it actually looks more like part of SDF but I've still got # a lot more documenting to do so that this is generally usable by # people that don't know how to read perl code :-) --tjh # # - check the value of the cell being used and if it is being used # inside a multiplication and is a text value then use 1 and if # inside an addition and is a text value then use 0 so that we can # use operations over cells with "random" text it them safely without # having to think too hard # - document how to use this sufficiently so that I don't get asked # questions about it # - implement a recursive decent parser so that we don't get confused # with really complex things (it works fine for my requirements at the # moment so I've not bothered) # package SDF_USER; sub chr { local($ascii)=@_; return sprintf("%c",$ascii); } # ---------------------------------------------------------------------------- # This requires SDF verion 2beta8 or above (which adds in a few new things # so that we have a nice syntax for calculations) # # This can be made to work in SDF2beta7c but it is worth upgrading to # a supported release :-) # # Calculation support for a table is activated by adding in an attribute # of calc (which triggers keeping track of the table contents in a cell # grid for later processing). # # A simple example: # # !block table; format="10,20,70"; style="box" # Count Price Total # 10 5 [[=ROWPROD]] # 15 5.23 [[=ROWPROD]] # [[=COLSUM]] [[=COLSUM]] [[=COLSUM]] # !endblock # # Note: values are available until the next table is processed so # you can refer to data inside "normal" paragraphs after the table # # ---------------------------------------------------------------------------- # The following are the target list of things that will be eventually # implemented (those starting with * have not yet been done): # (this is modelled off the standard things that I use in Excel) # + - * / # AVERAGE # SUM # MIN # MAX # *ROUND # COUNT # PRODUCT # *SUMPRODUCT # ROW ROW() is current row number # COLUMN COLUMN() is current column number # *IF IF(EXPR,TRUESTMT,FALSESTMT) # # Columns are named A-Z ... and rows are numbered sequentially starting # at 1 from the first non-header row ... # # Cells are labeled [A-Z][1-9]+ (I call these labels cellids) # # Ranges are done via cellid:cellid ... e.g. A1:C2 # # Example valid things ... that should be handled when I get around # to doing the general stuff later # # A1+A3-A2*B1 # # SUM(A1:A10,B1:B10,1,25) # SUMPRODUCT(A1:B3,D1:E3) # SUM(A1:B3*D1:E3) # # SDF usage is as follows: # [[=EXPRESSION]] # # [[=B1+B2+B3]] # [[=SUM(B1:B3)]] # [[=SUM(B1:B3,A1:A3)]] # [[=A1]] # # (it used to be !CALC EXPRESSION which was enhanced to be terser) # # Extra non-standard things that I've added that mean you can add # rows and columns into tables without having to play with the # calc values which by default require cellids # (yes I know ... I cannot help myself "extending" things) # # ROWSUM -> sum values of current row # COLSUM -> sum values of current column # ROWPROD -> multiply values of current row # COLPROD -> multiply values of current column # # multiplier for specifying precision # 100 = two decimal places (default) $_calc_restrict_precision=1; $calc_precision=2; $calc_strip_zeros=0; $_calc_last_strip_zeros=$calc_strip_zeros; $_calc_default_format='%.2f'; $_calc_default_units="numbers"; $_calc_test=0; $_calc_debug=0; $_calc_eval_debug=0; # data about the current table being processed is held here @_calc_data=(); $_calc_rows=0; $_calc_cols=0; # maximum depth we will recurse ... to stop infinite loops $_calc_max_recurse=10; # current depth of recursion $_calc_cur_recurse=0; $_calc_last_warning=''; # we only bitch once about each error $_calc_cur_warning=''; # we only bitch once about each error $_calc_row_offset=0; $_calc_last_group=0; @_calc_group_total=''; # calc_table ... activated during oncell processing to take a copy of # the data that is required by the calc function to implement # the spreadsheet-style calc stuff sub calc_table { # initialise if we are on the header roo if ($row == 0) { if ($col == 0) { @_calc_data=(); $_calc_rows=$last_row+1; # IGC to fix so +1 isn't needed $_calc_cols=$last_col; if ($_calc_debug) { print STDERR "NEWTABLE $_calc_rows,$_calc_cols\n"; } # grab any SDF vars that have been set that control # things on a global basis ... we do this at the start # of each table so we can change settings if needed if (defined $var{"CALC_PRECISION"}) { $ret=$var{"CALC_PRECISION"}; $calc_precision=$ret; } if (defined $var{"CALC_STRIP_ZEROS"}) { $var{"CALC_STRIP_ZEROES"}=$var{"CALC_STRIP_ZEROS"}; } if (defined $var{"CALC_STRIP_ZEROES"}) { $ret=$var{"CALC_STRIP_ZEROES"}; $calc_strip_zeros=$ret; $_calc_last_strip_zeros=$calc_strip_zeros; } if (defined $var{"CALC_UNITS"}) { $ret=$var{"CALC_UNITS"}; if ($ret eq "money") { $_calc_default_units="money"; $_calc_last_strip_zeros=$calc_strip_zeros; $calc_strip_zeros=0; } if ($ret eq "numbers" || $ret eq "digits") { $_calc_default_units="numbers"; $calc_strip_zeros=$_calc_last_strip_zeros; } } if (defined $var{"CALC_DEFAULT_FORMAT"}) { $_calc_default_format=$var{"CALC_DEFAULT_FORMAT"}; } } $_calc_row_offset=$body_start; # we are out by one ... if ($body_start>0) { $_calc_row_offset--; } # initialise things that need to be set on a per-table basis $_calc_cur_warning=''; $_calc_last_warning=''; $_calc_cur_recurse=0; $_calc_group_total{"$col"}=""; $_calc_last_group=0; #@_calc_group_total=(); return; } #print STDERR "[$row,$col] $row_type \"$cell\"\n"; if ( ($col == 0) && ($row_type eq "Group")) { #print STDERR "GROUP RANGE: " . &_calc_var_current_cell() . " " . &_calc_var_group_col_range() . "\n"; $_calc_last_group=$row; } # now hack things into submission that need to know about the # current row and col as this is the only chance we have of # getting that right # # we have to catch two forms [[=EXPR]] and [[&Calc("EXPR")]] which # is why we have the dogs breakfast below # $cell =~ s/\[\[([=+]|&Calc)([^\]]*)ROWPRODUCT([^\]]*)]]/"[[$1$2PRODUCT(" . &_calc_var_row_range() . ")$3]]"/ge; $cell =~ s/\[\[([=+]|&Calc)([^\]]*)COLPRODUCT([^\]]*)]]/"[[$1$2PRODUCT(" . &_calc_var_col_range() . ")$3]]"/ge; $cell =~ s/\[\[([=+]|&Calc)([^\]]*)ROWAVERAGE([^\]]*)]]/"[[$1$2AVERAGE(" . &_calc_var_row_range() . ")$3]]"/ge; $cell =~ s/\[\[([=+]|&Calc)([^\]]*)COLAVERAGE([^\]]*)]]/"[[$1$2AVERAGE(" . &_calc_var_col_range() . ")$3]]"/ge; $cell =~ s/\[\[([=+]|&Calc)([^\]]*)COLUMNAVERAGE([^\]]*)]]/"[[$1$2AVERAGE(" . &_calc_var_col_range() . ")$3]]"/ge; $cell =~ s/\[\[([=+]|&Calc)([^\]]*)COLUMNSUM([^\]]*)]]/"[[$1$2SUM(" . &_calc_var_col_range() . ")$3]]"/ge; $cell =~ s/\[\[([=+]|&Calc)([^\]]*)COLUMNPRODUCT([^\]]*)]]/"[[$1$2PRODUCT(" . &_calc_var_col_range() . ")$3]]"/ge; $cell =~ s/\[\[([=+]|&Calc)([^\]]*)ROWSUM([^\]]*)]]/"[[$1$2SUM(" . &_calc_var_row_range() . ")$3]]"/ge; $cell =~ s/\[\[([=+]|&Calc)([^\]]*)COLSUM([^\]]*)]]/"[[$1$2SUM(" . &_calc_var_col_range() . ")$3]]"/ge; $cell =~ s/\[\[([=+]|&Calc)([^\]]*)ROWPROD([^\]]*)]]/"[[$1$2PRODUCT(" . &_calc_var_row_range() . ")$3]]"/ge; $cell =~ s/\[\[([=+]|&Calc)([^\]]*)COLPROD([^\]]*)]]/"[[$1$2PRODUCT(" . &_calc_var_col_range() . ")$3]]"/ge; $cell =~ s/\[\[([=+]|&Calc)([^\]]*)ROWAVG([^\]]*)]]/"[[$1$2AVERAGE(" . &_calc_var_row_range() . ")$3]]"/ge; $cell =~ s/\[\[([=+]|&Calc)([^\]]*)COLAVG([^\]]*)]]/"[[$1$2AVERAGE(" . &_calc_var_col_range() . ")$3]]"/ge; # group things ... if ( $cell =~ m/\[\[([=+]|&Calc)([^\]]*)GROUPSUBTOTAL([^\]]*)]]/ ) { if ($_calc_group_total{"$col"}) { $_calc_group_total{"$col"} .= "+"; } $_calc_group_total{"$col"} .= &_calc_var_current_cell(); #print STDERR "GROUPTOTAL $col = " . $_calc_group_total{"$col"} . "\n"; $cell =~ s/\[\[([=+]|&Calc)([^\]]*)GROUPSUBTOTAL([^\]]*)]]/"[[$1$2SUM(" . &_calc_var_group_col_range() . ")$3]]"/ge; } $cell =~ s/\[\[([=+]|&Calc)([^\]]*)GROUPTOTAL([^\]]*)]]/"[[$1$2" . $_calc_group_total{"$col"} . "$3]]"/ge; # take reference to cell data which will remain valid # until the next table overwrites it $_calc_data{"$row","$col"}="$cell"; if ($_calc_debug) { print STDERR "DATA($row,$col)=" . $_calc_data{"$row","$col"} . " ($cell)\n"; } return; } sub _calc_min { local($args)=@_; local($ret,$x,@words); (@words)=split(/,/,$args); $ret=$words[0]; for($x=0;$x<=$#words;$x++) { $ret=$words[$x] if ($words[$x]<$ret); } return $ret; } sub _calc_max { local($args)=@_; local($ret,$x,@words); (@words)=split(/,/,$args); $ret=$words[0]; for($x=0;$x<=$#words;$x++) { $ret=$words[$x] if ($words[$x]>$ret); } return $ret; } sub _calc_format { local($fmt,$args)=@_; local($prec); # pull off the outer quotes which will have # come throught the single quoting we use to # survive the eval $fmt =~ s/^\"(.*)"$/$1/g; # we could have &_calc_safe_strings here for recursive things # that we have to eval too before going on as we have # got in the way of the normal eval by stealing its args #$args = eval &Calc("$args"); if ($_calc_eval_debug) { print STDERR "calc EVAL3: &Calc(\"$args\")\n"; } $args = eval &Calc("$args"); if ($_calc_debug) { print STDERR "_calc_format IN \"$fmt\",\"$args\"\n"; } # shortcut ... will round up to the nearest whole dollar if ( $fmt eq "dollars" ) { $fmt="money"; $prec="%.0f"; } else { $prec="%.2f"; } if ( ($fmt eq "\$") || ($fmt eq "money") || ($fmt eq "currency") ) { if ($_calc_debug) { print STDERR "_calc_format MONEY\n"; } # money is two decimal places always ... without zeros removed $args=sprintf($prec,"$args"); $ret = &_calc_format_money("$args"); $ret =~ s/\$/_DOLLAR_/g; $ret =~ s/,/_COMMA_/g; $ret =~ s/\./_DOT_/g; if ($_calc_debug) { print STDERR "_calc_format MONEY OUT \"$ret\"\n"; } } else { $ret=sprintf("$fmt",$args); } if ($_calc_debug) { print STDERR "_calc_format OUT \"$ret\"\n"; } return "$ret"; } # simple operator conversion ... with a few funny things that just # get ranges to become parameter lists to function calls %_calc_ops=( "SUM", "+", "PRODUCT", "*", "COUNT", "," ,"MIN", ",", "MAX", ",", "CALL", ","); sub _calc_expand_range { local($op,$start_range,$end_range)=@_; local($result); if ($_calc_debug) { print STDERR "calc_expand_range: \"OP=$op START=$start_range END=$end_range\"\n"; } $scell=substr($start_range,0,1); $srow=substr($start_range,1); $ecell=substr($end_range,0,1); $erow=substr($end_range,1); $result=''; for($x=ord($scell);$x<=ord($ecell);$x++) { for($y=$srow;$y<=$erow;$y++) { if ($result) { if ($_calc_ops{"$op"}) { $result .= $_calc_ops{"$op"} } else { &'AppMsg('error', "unknown operator '$op'"); #print STDERR "calc_expand_range:Unknown operator $op\n"; $result .= ","; } } $result .= &chr($x) . "$y"; } } if ($_calc_debug) { print STDERR "calc_expand_range: RESULT=$result\n"; } return $result; } # calc_var_row_range - range for entire row sub _calc_var_row_range { local($ret,$x,$y); $x = &chr(ord("A")+0); $y = &chr(ord("A")+$col-1); $ret = "$x" . "$row:" . "$y" . "$row"; return $ret; } # calc_var_group_row_range - range for entire group column sub _calc_var_group_col_range { local($ret,$x,$y,$z); $x = &chr(ord("A")+$col); $y = $row-1; $z = $_calc_last_group; $ret = "$x" . "$z:" . "$x" . "$y"; return $ret; } # calc_var_col_range - range for entire column sub _calc_var_col_range { local($ret,$x,$y); $x = &chr(ord("A")+$col); $y = $row-1; $ret = "$x" . "1:" . "$x" . "$y"; return $ret; } # calc_var_col_range - range for entire column sub _calc_var_current_cell { local($ret,$x,$y); $x = &chr(ord("A")+$col); $y = $row; $ret = "$x" . "$y"; return $ret; } sub _calc_safe_string { local($var,$val,$op)=@_; if ($_calc_debug) { print STDERR "SAFE_STRING IN $var,$val\n"; } # remove financial tokens ... $ and comma $val =~ s/\$([0-9,\.]+)/&_calc_unformat_money("$1")/ge; # return straight away if no op defined if ($op eq "" ) { if ($_calc_debug) { print STDERR "SAFE_STRING OUT1 $val\n"; } return "$val"; } # ignore things that are references to other bits # as we only want *plain* strings to be effected if ($val =~ m|^[&\[]| ) { if ($_calc_debug) { print STDERR "SAFE_STRING OUT2 $val\n"; } return "$val"; } # if it is a string then we handle it differently if we # are in the process of doing a multiply as we don't # want messy things just to skip string values in a # table if ( $val =~ m|[^0-9\. ]+| ) { if ($op eq "PRODUCT") { if ($_calc_debug) { print STDERR "STRING $var=>$val REWRITTEN to 1\n"; } $val = "1"; } else { if ($_calc_debug) { print STDERR "STRING $var=>$val\n"; } } } if ($_calc_debug) { print STDERR "SAFE_STRING OUT3 $val\n"; } return "$val"; } sub _calc_unformat_money { local($str)=@_; local($ret); $ret=$str; # remove commas $ret =~ s/,//g; if ($_calc_debug) { print STDERR "unformat_money($str)=$ret " . "formatted = " . &_calc_format_money($ret) . "\n"; } return $ret; } sub _calc_format_money { local($str)=@_; local($ret,$body); local($i,$len); $ret=$str; # drop off trailing decimal stuff until later $rest=''; # we do it this way as it works ... $len=length($ret); for($i=0;$i<=$len;$i++) { if (substr($ret,$len-$i,1) eq ".") { $rest=substr($ret,$len-$i); $ret=substr($ret,0,$len-$i); break; } } # now put in the commas in the right place ... there # is probably a nice routine somewhere that already does # this but I don't know it offhand $len=length($ret); $body=''; for($i=0;$i<=$len;$i++) { $body=substr($ret,$len-$i,1) . "$body"; if ($i != $len) { $body = "," . "$body" if ( (($i % 3) == 0) && ($i != 0)); } } $ret = "\$" . "$body$rest"; if ($_calc_debug) { print STDERR "format_money($str)=$ret body=$body rest=$rest\n"; } return "$ret"; } # calc_var_name - given a cell ID return the variable name that holds # the value for that cell sub _calc_var_name { local($cellid,$op)=@_; local($let,$num,$ret,$x,$y,$val); $let=substr($cellid,0,1); $num=substr($cellid,1); # offset numbers to skip headers ... $num += $_calc_row_offset; # we have to do things in two parts to keep perl happy $x = $num; $y = (ord("$let")-ord("A")); $ret = "&_calc_safe_string(\'DATA[$x,$y]\',\$_calc_data\{$x,$y\},$op)"; # short circuit out of bound lookups ... otherwise we # often end up recursing on ourself ... if ($y >= $_calc_rows) { return ""; } ## remove financial tokens ... $ and comma #$val =~ s/\$([0-9,.]*)/&_calc_unformat_money($1)/ge; if ($_calc_eval_debug) { print STDERR "calc EVAL4: $ret\n"; } $val=eval "$ret"; if ($_calc_debug) { print STDERR "calc_var_name($cellid\[$let,$num\])=$ret : x=$x y=$y val=$val\n"; } # match standard SDF expressions for string lookups if ( $val =~ m/\[\[([^=+&][^\]]*)\]\]/ ) { $val=$1; $ret=&Var("$val"); ##print STDERR "CALC SDF EXPR \"$val\"->\"$ret\"" . $var{"$val"} . "\n"; return &_calc_safe_string($val,$ret,$op); } # check to see if the variable points to a cell that contains a # formula ... if so then we need to evaluate that now ... which is # fine as long as some smart person doesn't setup a recursive # requirement between cells if (($val =~ m/\[\[[=+]([^\]]*)\]\]/) || ($val =~ m/\[\[&Calc([^\]]*)\]\]/)) { if ($_calc_debug) { print STDERR "CALC recursion required on $1\n"; } if ( $_calc_cur_recurse == 0) { $_calc_cur_warning = "$1"; } $_calc_cur_recurse++; if ($_calc_cur_recurse > $_calc_max_recurse) { if ("$_calc_last_warning" ne "$_calc_cur_warning") { &'AppMsg('warning', "CALC recursion limit reached '$_calc_cur_warning'"); $_calc_last_warning="$_calc_cur_warning"; } $ret="CALCERROR"; } else { if ($_calc_debug) { print STDERR "RECURSE START ON $1\n"; } $ret = &Calc($1); if ($_calc_debug) { print STDERR "RECURSE FINISH ON $1 => $ret\n"; } } $_calc_cur_recurse--; if ($_calc_debug) { print STDERR "calc_var_name($cellid\[$let,$num\])=$ret (recursion)\n"; } } return &_calc_safe_string($val,$ret,$op); } sub _head { local($arg)=@_; return "\"&_calc_format(\'$1\',\""; } sub _tail { local($arg)=@_; return "\")\""; } sub _calc_expr { local($op,$expr)=@_; local($_); local($have_format)=0; local($in_expr); if ($_calc_debug) { print STDERR "calc_expr: \"OP=$op EXPR=$expr\"\n"; } $in_expr="$expr"; # convert some of the operations into expressions involving # other operations ... which makes things easier to implement $expr =~ s/AVERAGE\((.*)\)/"(SUM($1)\/COUNT($1))"/g; $expr =~ s/MIN\((.*)\)/"&_calc_min(\"$1\")"/g; $expr =~ s/MAX\((.*)\)/"&_calc_max(\"$1\")"/g; print STDERR "calc_expr ALIVE1 expr=\"$expr\"\n" if ($_calc_debug); if ( $expr =~ m|FORMAT\((.*)\)| ) { #$expr =~ s/FORMAT\(([^,]*),(.*)\)/"\"&_calc_format(\'$1\',\"" . &Calc("$2") . "\")\""/ge; $expr =~ s/FORMAT\(([^,]*),(.*)\)/&_head($1) . &Calc("$2") . &_tail()/ge; $have_format=1; } if ( $expr =~ m|PRECISION\((.*)\)| ) { #$expr =~ s/PRECISION\(([^,]*),(.*)\)/"\"&_calc_format(\'\"%.$1f\"\',\"" . &Calc($2) . "\")\""/ge; $expr =~ s/PRECISION\(([^,]*),(.*)\)/&_head("%.$1f") . &Calc($2) . &_tail()/ge; $have_format=1; } print STDERR "calc_expr ALIVE2 expr=\"$expr\"\n" if ($_calc_debug); # if expression contains non-matching brackets we bail now # as it must be something that has slipped through that has # been expanded and then partially matched ... we really should # have a recursive decent parser here but I cannot be bothered # to do that as this does a good enough job as is $_ = "$expr"; if ( m|^[^\(\)]*\)| ) { if ($_calc_debug) { print STDERR "calc_expr: BAILING ON \"$expr\"\n"; } return "$expr"; } print STDERR "calc_expr ALIVE3 expr=\"$expr\"\n" if ($_calc_debug); # handle subroutine calls ... which we escape into # the form CALL &sub#" which is undone later $expr =~ s/(&[a-z_]*)\(([^\(\)]*)\)/"(" . &_calc_expr("CALL","$1#<$2>#") . ")"/ge; $expr =~ s/(&[a-z_]*)\((.*)\)/"(" . &_calc_expr("CALL","$1#<$2>#") . ")"/ge; print STDERR "calc_expr ALIVE4 expr=\"$expr\"\n" if ($_calc_debug); # handle any nested operations first ... #$expr =~ m/([A-Z]*)\(([^\(\)]*)\)/; #print STDERR "*****EXPR $in_expr => $expr inner = \"$1\",\"$2\"\n"; #$expr =~ s/([A-Z]*)\(([^\(\)]*)\)(\)|$)/"(" . &_calc_expr($1,$2) . ")"/ge; $expr =~ s/([A-Z]*)\(([^\(\)]*)\)/"(" . &_calc_expr($1,$2) . ")"/ge; # handle other ops now ... having gotten rid of series $expr =~ s/([A-Z]*)\((.*)\)/"(" . &_calc_expr($1,$2) . ")"/ge; # expand ranges into full variable requests with expanded ops $expr =~ s/([A-Z][0-9]+):([A-Z][0-9]+)/&_calc_expand_range($op,$1,$2)/ge; print STDERR "calc_expr ALIVE5 expr=\"$expr\"\n" if ($_calc_debug); # now handle individual expressions if ( $op eq "COUNT" ) { @words = split(/,/,$expr); $expr = $#words+1; } elsif ($_calc_ops{"$op"}) { if ($_calc_ops{"$op"} eq "*" ) { $expr =~ s/,/$_calc_ops{"$op"}/g; } else { $expr =~ s/,/$_calc_ops{"$op"}/g; } } else { } # now convert the cell references into perl variable names $expr =~ s/([A-Z][0-9]+)/&_calc_var_name($1,$op)/ge; # convert any escaped subroutine calls back to the real thing $expr =~ s/(\&[a-zA-Z_]*)#<([^>]*)>#/$1($2)/g; # undo any mucky things we have stuffed up and left double # brackets ... ikcy! $expr =~ s/\)\)([+*-\/])\(/)$1(/g; $pre_expr = "$expr"; # fix up quote things $expr =~ s/^"([^"]*)"$/$1/; $expr =~ s/^"([^"]*)$/$1/; $expr =~ s/([^"]*)"$/$1/; if ($_calc_eval_debug) { print STDERR "calc EVAL1: $pre_expr --> $expr\n"; } # and finally evaluate the expression using perl logic $ret = eval "$expr"; # second eval removes any rubbish outer brackets ... otherwise # we get tangled on them later :-( if ($_calc_eval_debug) { print STDERR "calc EVAL2: $ret\n"; } $ret = eval "$ret"; # then trim to two decimal places ... I don't care for more # than that by default in the result thought I'm sure that will # change in future if (!$have_format) { if ($_calc_restrict_precision) { if ($_calc_debug) { print STDERR "ret $ret => "; } if ($calc_precision) { $in=$ret; $ret =~ s/(\d*\.\d*)/sprintf("%.".$calc_precision."f",$1)/ge; $ret =~ s/(-\d*\.\d*)/sprintf("%.".$calc_precision."f",$1)/ge; $mid=$ret; # remove trailing zeros ... othewise things look really icky if ($calc_strip_zeros && !($ret =~ m|\$|) ) { $ret =~ s/(\.[1-9]*)(0+\s*)/$1/g; } if ($in!=$ret) { if ($_calc_debug) { print STDERR "PREC: $in->$mid->$ret\n"; } } } if ($_calc_debug) { print STDERR "$ret\n"; } } } # strip any brackets that are left as a side effect of having # done other calculations to get the result that added in # backets that eval doesn't seem to want to strip off $ret =~ s/^\((.*)\)$/$1/; return "$ret"; } sub Calc { local($in_expr)=@_; local($expr,$result); $expr=$in_expr; # handle all the control setting stuff ... $cell=$expr; if ( $cell =~ m/UNITS=(.*)/ ) { $cell = "MONEY" if ($1 eq "money"); $cell = "NUMBERS" if ($1 eq "numbers"); } if ( $cell eq "MONEY" ) { $_calc_default_units="money"; $_calc_last_strip_zeros=$calc_strip_zeros; $calc_strip_zeros=0; $cell = ""; } if ( $cell eq "NUMBERS" ) { $_calc_default_units="numbers"; $calc_strip_zeros=$_calc_last_strip_zeros; $cell = ""; } if ( $cell eq "DEBUG" ) { $_calc_debug=1; $cell = ""; } if ( $cell eq "NOSTRIPZEROS" || $cell eq "NOSTRIPZEROES" ) { $calc_strip_zeros=0; $cell = ""; } if ( $cell eq "STRIPZEROS" || $cell eq "STRIPZEROES" ) { $calc_strip_zeros=1; $cell = ""; } if ( $cell =~ m/PRECISION=(\d+)/ ) { $calc_precision=$1; $cell = ""; } # quick exit! if ($cell eq "") { return ""; } if ($_calc_debug) { print STDERR "calc: IN \"$expr\"\n"; } $result=&_calc_expr("","$expr"); # undo our escaping ... only at the top level $result =~ s/_DOLLAR_/\$/g; $result =~ s/_COMMA_/,/g; $result =~ s/_DOT_/./g; # handle overall formatting options if ($_calc_default_format) { $result=sprintf("$_calc_default_format","$result"); } # handle defaulting to money formatted output if ($_calc_default_units eq "money") { $result = &_calc_format_money("$result"); } if ($_calc_debug) { print STDERR "calc: \"$expr\" => $result\n"; } return $result; } # testing engine ... we really need some test case data here if ($_calc_test) { while() { chop; print &Calc("$_"); } } 1; } if ($_calc_debug) { print STDERR "SAFE_STRING OUT3 $val\n"; } return "$val"; } sub _calc_unformat_money { lsdf-2.001/perllib/sdf/totxt.pl010075500042570001753000000533250671163472200160650ustar00iancmtr00000400000236# $Id$ $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: Text Format Driver # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 01-May-97 ianc Applied patches from Tim MacKenzie # 14-May-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # This library provides an [[SDF_DRIVER]] which generates # plain text files. # # >>Description:: # # >>Limitations:: # All headings are output as plain. i.e. without numbering. # # A table of contents is not supported yet. # # Word wrapping is not applied to example paragraphs. # # Multi-line cells in tables (including nested tables) do not work. # >>Resources:: # # >>Implementation:: # ##### Constants ##### # Default right margin $_TXT_DEFAULT_MARGIN = 70; # Mapping of characters %_TXT_CHAR = ( 'bullet', '.', 'c', '(c)', 'cent', 'c', 'dagger', '^', 'doubledagger', '#', 'emdash', '-', 'endash', '-', 'emspace', ' ', 'enspace', ' ', 'lbrace', '{', 'lbracket', '[', 'nbdash', '-', 'nbspace', ' ', 'nl', "\n", 'pound', 'L', 'r', '(r)', 'rbrace', '}', 'rbracket', ']', 'tab', "\t", 'tm', '(tm) ', 'yen', 'y', # From Pod::Text.pm ... 'amp' => '&', # ampersand 'lt' => '<', # left chevron, less-than 'gt' => '>', # right chevron, greater-than 'quot' => '"', # double quote "Aacute" => "\xC1", # capital A, acute accent "aacute" => "\xE1", # small a, acute accent "Acirc" => "\xC2", # capital A, circumflex accent "acirc" => "\xE2", # small a, circumflex accent "AElig" => "\xC6", # capital AE diphthong (ligature) "aelig" => "\xE6", # small ae diphthong (ligature) "Agrave" => "\xC0", # capital A, grave accent "agrave" => "\xE0", # small a, grave accent "Aring" => "\xC5", # capital A, ring "aring" => "\xE5", # small a, ring "Atilde" => "\xC3", # capital A, tilde "atilde" => "\xE3", # small a, tilde "Auml" => "\xC4", # capital A, dieresis or umlaut mark "auml" => "\xE4", # small a, dieresis or umlaut mark "Ccedil" => "\xC7", # capital C, cedilla "ccedil" => "\xE7", # small c, cedilla "Eacute" => "\xC9", # capital E, acute accent "eacute" => "\xE9", # small e, acute accent "Ecirc" => "\xCA", # capital E, circumflex accent "ecirc" => "\xEA", # small e, circumflex accent "Egrave" => "\xC8", # capital E, grave accent "egrave" => "\xE8", # small e, grave accent "ETH" => "\xD0", # capital Eth, Icelandic "eth" => "\xF0", # small eth, Icelandic "Euml" => "\xCB", # capital E, dieresis or umlaut mark "euml" => "\xEB", # small e, dieresis or umlaut mark "Iacute" => "\xCD", # capital I, acute accent "iacute" => "\xED", # small i, acute accent "Icirc" => "\xCE", # capital I, circumflex accent "icirc" => "\xEE", # small i, circumflex accent "Igrave" => "\xCD", # capital I, grave accent "igrave" => "\xED", # small i, grave accent "Iuml" => "\xCF", # capital I, dieresis or umlaut mark "iuml" => "\xEF", # small i, dieresis or umlaut mark "Ntilde" => "\xD1", # capital N, tilde "ntilde" => "\xF1", # small n, tilde "Oacute" => "\xD3", # capital O, acute accent "oacute" => "\xF3", # small o, acute accent "Ocirc" => "\xD4", # capital O, circumflex accent "ocirc" => "\xF4", # small o, circumflex accent "Ograve" => "\xD2", # capital O, grave accent "ograve" => "\xF2", # small o, grave accent "Oslash" => "\xD8", # capital O, slash "oslash" => "\xF8", # small o, slash "Otilde" => "\xD5", # capital O, tilde "otilde" => "\xF5", # small o, tilde "Ouml" => "\xD6", # capital O, dieresis or umlaut mark "ouml" => "\xF6", # small o, dieresis or umlaut mark "szlig" => "\xDF", # small sharp s, German (sz ligature) "THORN" => "\xDE", # capital THORN, Icelandic "thorn" => "\xFE", # small thorn, Icelandic "Uacute" => "\xDA", # capital U, acute accent "uacute" => "\xFA", # small u, acute accent "Ucirc" => "\xDB", # capital U, circumflex accent "ucirc" => "\xFB", # small u, circumflex accent "Ugrave" => "\xD9", # capital U, grave accent "ugrave" => "\xF9", # small u, grave accent "Uuml" => "\xDC", # capital U, dieresis or umlaut mark "uuml" => "\xFC", # small u, dieresis or umlaut mark "Yacute" => "\xDD", # capital Y, acute accent "yacute" => "\xFD", # small y, acute accent "yuml" => "\xFF", # small y, dieresis or umlaut mark "lchevron" => "\xAB", # left chevron (double less than) "rchevron" => "\xBB", # right chevron (double greater than) ); # Directive mapping table %_TXT_HANDLER = ( 'tuning', '_TxtHandlerTuning', 'endtuning', '_TxtHandlerEndTuning', 'table', '_TxtHandlerTable', 'row', '_TxtHandlerRow', 'cell', '_TxtHandlerCell', 'endtable', '_TxtHandlerEndTable', 'import', '_TxtHandlerImport', 'inline', '_TxtHandlerInline', 'output', '_TxtHandlerOutput', 'object', '_TxtHandlerObject', 'stylesheet', '', ); # Phrase directive mapping table %_TXT_PHRASE_HANDLER = ( 'char', '_TxtPhraseHandlerChar', 'import', '_TxtPhraseHandlerImport', 'inline', '_TxtPhraseHandlerInline', 'variable', '_TxtPhraseHandlerVariable', ); # Table states $_TXT_INTABLE = 1; $_TXT_INROW = 2; $_TXT_INCELL = 3; ##### Variables ##### # Right margin position $_txt_margin = $SDF_USER'var{'TXT_MARGIN'} || $_TXT_DEFAULT_MARGIN; # Counters for ordered lists - index is the level @_txt_list_num = 0; # Table states and row types @_txt_tbl_state = (); @_txt_row_type = (); # Column number & starting positions for current table $_txt_col_num = 0; @_txt_col_posn = (); # Location of the first line of the current row $_txt_first_row = 0; # The current cell text $_txt_cell_current = ''; ##### Routines ##### # # >>Description:: # {{Y:TxtFormat}} is an SDF driver which outputs plain text files. # sub TxtFormat { local(*data) = @_; local(@result); local(@contents); # Initialise defaults $_txt_margin = $SDF_USER'var{'TXT_MARGIN'} || $_TXT_DEFAULT_MARGIN; # Format the paragraphs @contents = (); @result = &_TxtFormatSection(*data, *contents); # Turn into final form and return return &_TxtFinalise(*result, *contents); } # # >>_Description:: # {{Y:_TxtFormatSection}} formats a set of SDF paragraphs into text. # If a parameter is passed to contents, then that array is populated # with a generated Table of Contents. # sub _TxtFormatSection { local(*data, *contents) = @_; local(@result); local($prev_tag, $prev_indent); local($para_tag, $para_text, %para_attrs); local($directive); # Process the paragraphs @result = (); $prev_tag = ''; $prev_indent = ''; while (($para_text, $para_tag, %para_attrs) = &SdfNextPara(*data)) { # handle directives if ($para_tag =~ /^__(\w+)$/) { $directive = $_TXT_HANDLER{$1}; if (defined &$directive) { &$directive(*result, $para_text, %para_attrs); } else { &AppTrace("txt", 5, "ignoring internal directive '$1'"); } next; } # Add the paragraph &_TxtParaAdd(*result, $para_tag, $para_text, *para_attrs, $prev_tag, $prev_indent, *contents); } # Do this stuff before starting next loop iteration continue { unless ($para_tag eq 'PB') { $prev_tag = $para_tag; $prev_indent = $para_attrs{'in'}; } } # Return result return @result; } # # >>_Description:: # {{Y:_TxtParaAdd}} adds a paragraph. # sub _TxtParaAdd { local(*result, $para_tag, $para_text, *para_attrs, $prev_tag, $prev_indent, *contents) = @_; # local(); local($in_example); local($para_fmt); local($para_override); local($para); local($hdg_level); local($toc_jump); local($label); # Set the example flag $in_example = $SDF_USER'parastyles_category{$para_tag} eq 'example'; # Enumerated lists are the same as list paragraphs at the previous level if ($para_tag =~ /^LI(\d)$/) { $para_tag = $1 > 1 ? "L" . ($1 - 1) : 'N'; } # Get the target format name $para_fmt = $SDF_USER'parastyles_to{$para_tag}; $para_fmt = $para_tag if $para_fmt eq ''; # Map the attributes &SdfAttrMap(*para_attrs, 'txt', *SDF_USER'paraattrs_to, *SDF_USER'paraattrs_map, *SDF_USER'paraattrs_attrs, $SDF_USER'parastyles_attrs{$para_tag}); # Build the Table of Contents as we go $toc_jump = ''; if ($para_tag =~ /^([HAP])(\d)$/) { $hdg_level = $2; $para_text = &SdfHeadingPrefix($1, $2) . $para_text; if ($hdg_level <= $SDF_USER'var{'DOC_TOC'} && !$para_attrs{'notoc'}) { # Build a plain list in SDF $toc_jump = $para_attrs{'id'}; $toc_jump = "HDR" . ($#contents + 1) if $toc_jump eq ''; push(@contents, "L${hdg_level}[jump='#$toc_jump']$para_text"); } } # Handle lists (is this needed for text format?) elsif ($para_tag =~ /^(L[FUN]?)(\d)$/) { $para_attrs{'in'} = $2; } # Prepend the label, if any (replacing tabs with spaces) $label = $para_attrs{'label'}; $label = 'Note: ' if ($para_tag eq 'Note' || $para_tag eq 'NB') && $label eq ''; $label =~ s/\\t/ /g; $para_text = "{{2:$label}}$para_text" if $label ne ''; # Indent examples, if necessary if ($in_example && $para_attrs{'in'}) { $para_text = " " x ($para_attrs{'in'} * 5) . $para_text; delete $para_attrs{'in'}; } # Format the paragraph body if ($para_attrs{'verbatim'}) { $para = $para_text; delete $para_attrs{'verbatim'}; } else { $para = &_TxtParaText($para_text); } # If we're in a table, prepend the paragraph onto the current cell if (@_txt_tbl_state) { if ($para_fmt eq "Line") { $_txt_cell_current .= "-" x $_txt_cell_width; return; } $_txt_cell_current .= $para; return; } # Build result if ($para_tag eq 'PB') { $para = &_TxtElement($para_fmt, $para, %para_attrs); &_TxtParaAppend(*result, $para); } elsif ($in_example && $para_tag eq $prev_tag) { &_TxtParaAppend(*result, $para); } else { $para = &_TxtElement($para_fmt, $para, %para_attrs); push(@result, $para); } } # # >>_Description:: # {{Y:_TxtParaText}} converts SDF paragraph text into TXT. # sub _TxtParaText { local($para_text) = @_; local($para); local($state); local($sect_type, $char_tag, $text, %sect_attrs); local($added_anchors); local(@char_fonts); local($char_font); local($directive); # Process the text $para = ''; $state = 0; while (($sect_type, $text, $char_tag, %sect_attrs) = &SdfNextSection(*para_text, *state)) { #print "char_tag:$char_tag.\n"; # Build the paragraph if ($sect_type eq 'special') { $directive = $_TXT_PHRASE_HANDLER{$char_tag}; if (defined &$directive) { &$directive(*para, $text, %sect_attrs); } else { &AppMsg("warning", "ignoring special phrase '$1' in TXT driver"); } } elsif ($sect_type eq 'string') { $para .= $text; } elsif ($sect_type eq 'phrase') { ($text) = &SDF_USER'ExpandLink($text) if $char_tag eq 'L'; $para .= $text; } elsif ($sect_type eq 'phrase_end') { # do nothing } else { &AppMsg("warning", "unknown section type '$sect_type' in TXT driver"); } } # Return result return $para; } # # >>_Description:: # {{Y:_TxtFinalise}} generates the final TXT file. # sub _TxtFinalise { local(*body, *contents) = @_; # local(@result); # Return result return @body; } # # >>_Description:: # {{Y:_TxtElement}} formats a TXT element from a # tag, text and set of attributes. # sub _TxtElement { local($tag, $text, %attr) = @_; local($txt); local($prefix, $label); local($cnt); # Handle page breaks if ($tag eq 'PB') { return "\f"; } # For examples, don't word wrap the lines if ($tag eq 'E') { $txt = "$text\n"; } # For lines, output a 'line' elsif ($tag eq 'Line') { $txt = ("_" x $_txt_margin) . "\n"; } # For headings, underline the text unless requested not to elsif ($tag =~ /^[HAP](\d)/) { $txt = "$text\n"; unless ($SDF_USER'var{'TXT_HDG_UL_OFF'}){ $char = $1 == 1 ? "=" : "-"; $txt .= ($char x length($text)) . "\n"; } } # For list items, add the necessary "label" elsif ($tag =~ /^(L[FUN]?)(\d)$/) { $prefix = " " x ($2 * 5); $label = " " x (($2 - 1) * 5); if ($1 eq 'LU') { $label .= "o "; } elsif ($1 eq 'L') { $label .= " "; } elsif ($1 eq 'LF') { $label .= "1. "; $_txt_list_num[$2] = 1; } else { $cnt = ++$_txt_list_num[$2]; $label .= substr("$cnt. ", 0, 5); } $txt = &MiscTextWrap($label . $text, $_txt_margin, $prefix, '', 1) . "\n"; } # Otherwise, format as a plain paragraph else { $txt = &MiscTextWrap($text, $_txt_margin, '', '', 1) . "\n"; } # Handle the top attribute return $para{'top'} ? "\f\n$txt" : $txt; } # # >>_Description:: # {{Y:_TxtParaAppend}} merges {{para}} into the last paragraph # in {{@result}}. Both paragraphs are assumed to be examples. # sub _TxtParaAppend { local(*result, $para) = @_; # local(); $result[$#result] .= "$para\n"; } # # >>_Description:: # {{Y:_TxtHandlerTuning}} handles the 'tuning' directive. # sub _TxtHandlerTuning { local(*outbuffer, $style, %attr) = @_; # local(); # do nothing } # # >>_Description:: # {{Y:_TxtHandlerEndTuning}} handles the 'endtuning' directive. # sub _TxtHandlerEndTuning { local(*outbuffer, $style, %attr) = @_; # local(); # do nothing } # # >>_Description:: # {{Y:_TxtHandlerTable}} handles the 'table' directive. # sub _TxtHandlerTable { local(*outbuffer, $columns, %attr) = @_; # local(); local($tbl_title); # Update the state push(@_txt_tbl_state, $_TXT_INTABLE); push(@_txt_row_type, ''); # Calculate the column positions (rounded) @_txt_col_posn = &SdfColPositions($columns, $attr{'format'}, $_txt_margin); # Add the title, if any $tbl_title = $attr{'title'}; if ($tbl_title ne '') { push(@outbuffer, "$tbl_title\n"); } } # # >>_Description:: # {{Y:_TxtHandlerRow}} handles the 'row' directive. # sub _TxtHandlerRow { local(*outbuffer, $text, %attr) = @_; # local(); local($current_state); # Finalise the previous row, if any $current_state = $_txt_tbl_state[$#_txt_tbl_state]; unless ($current_state == $_TXT_INTABLE) { &_TxtFinalisePrevRow(*outbuffer, $_txt_row_type[$#_txt_row_type]); } # Start the new row push(@outbuffer, ""); $_txt_col_num = 0; $_txt_first_row = $#outbuffer; # Update the state $_txt_tbl_state[$#_txt_tbl_state] = $_TXT_INROW; $_txt_row_type[$#_txt_row_type] = $text; } # # >>_Description:: # {{Y:_TxtHandlerCell}} handles the 'cell' directive. # sub _TxtHandlerCell { local(*outbuffer, $text, %attr) = @_; # local(); local($state); local($padding); local($tmp); # Finalise the old cell, if any $state = $_txt_tbl_state[$#_txt_tbl_state]; if ($state eq $_TXT_INCELL) { &_TxtFinishCell(*outbuffer); if ($_txt_col_num > 0) { foreach $tmp ($_txt_first_row .. $#outbuffer) { $padding = $_txt_col_posn[$_txt_col_num - 1] - length($outbuffer[$tmp]); $padding = 1 if ($padding <= 0); $outbuffer[$tmp] .= " " x $padding; } } } # Update the state $_txt_tbl_state[$#_txt_tbl_state] = $_TXT_INCELL; $_txt_cell_margin = ($_txt_col_num>0?$_txt_col_posn[$_txt_col_num-1]:0); $_txt_col_num+=$attr{cols}; if ($_txt_col_num > $#_txt_col_posn + 1) { $_txt_cell_width = $_txt_margin - $_txt_cell_margin - 1; } else { $_txt_cell_width = $_txt_col_posn[$_txt_col_num-1] - $_txt_cell_margin - 1; } %_txt_cell_attrs = %attr; $_txt_cell_current = ""; } # # >>_Description:: # {{Y:_TxtFinishCell}} adds the cell text to the output # sub _TxtFinishCell { local(*outbuffer) = @_; $_txt_cell_current =~ s/(\S)\s+/$1 /g; local @lines = split(/\n/, &MiscTextWrap($_txt_cell_current, $_txt_cell_width,"",'',1)); local $tmp; foreach $tmp ($#outbuffer+1..$_txt_first_row+$#lines) { push(@outbuffer, " " x $_txt_cell_margin); } foreach $tmp (0..$#lines) { if ($_txt_cell_attrs{'align'} eq "Center") { $outbuffer[$_txt_first_row+$tmp] .= " " x (($_txt_cell_width - length($lines[$tmp]))/2); } elsif ($_txt_cell_attrs{'align'} eq "Right") { $outbuffer[$_txt_first_row+$tmp] .= " " x ($_txt_cell_width - length($lines[$tmp])); } $outbuffer[$_txt_first_row+$tmp] .= $lines[$tmp]; } $_txt_cell_current = ""; } # # >>_Description:: # {{Y:_TxtHandlerEndTable}} handles the 'endtable' directive. # sub _TxtHandlerEndTable { local(*outbuffer, $text, %attr) = @_; # local(); local($state); local($row_type); # Finalise the table $state = pop(@_txt_tbl_state); $row_type = pop(@_txt_row_type); if ($state eq $_TXT_INCELL) { &_TxtFinalisePrevRow(*outbuffer, $row_type); $outbuffer[$#outbuffer] .= "\n"; } elsif ($state eq $_TXT_INROW) { &_TxtFinalisePrevRow(*outbuffer, $row_type); $outbuffer[$#outbuffer] .= "\n"; } } # # >>_Description:: # {{Y:_TxtFinalisePrevRow}} finalises the previous row, if any. # sub _TxtFinalisePrevRow { local(*outbuffer, $row_type) = @_; # local(); local($line_row); local($prefix); local($tmp); local($_); &_TxtFinishCell(*outbuffer); foreach $tmp ($_txt_first_row..$#outbuffer) { $outbuffer[$tmp] =~ s/ *(\n*)$/$1/; } # If the last row was a heading, underline it if ($row_type eq 'Heading') { $line_row = ""; $tmp = 0; foreach (@_txt_col_posn) { $line_row .= ("."x($_-$tmp-1))." "; $tmp = $_; } push(@outbuffer, $line_row); } } # # >>_Description:: # {{Y:_TxtHandlerImport}} handles the import directive. # sub _TxtHandlerImport { local(*outbuffer, $filepath, %attr) = @_; # local(); local($para); # Build the result &_TxtPhraseHandlerImport(*para, $filepath, %attr); push(@outbuffer, "$para\n"); } # # >>_Description:: # {{Y:_TxtHandlerInline}} handles the inline directive. # sub _TxtHandlerInline { local(*outbuffer, $text, %attr) = @_; # local(); # Check we can handle this format my $target = $attr{'target'}; return unless $target eq 'txt' || $target eq 'text'; # Build the result push(@outbuffer, $text); } # # >>_Description:: # {{Y:_TxtHandlerOutput}} handles the 'output' directive. # sub _TxtHandlerOutput { local(*outbuffer, $text, %attrs) = @_; # local(); # do nothing } # # >>_Description:: # {{Y:_TxtHandlerObject}} handles the 'object' directive. # sub _TxtHandlerObject { local(*outbuffer, $text, %attrs) = @_; # local(); # Save the margin, if necessary if ($text eq 'Variable' && $attrs{'Name'} eq 'TXT_MARGIN') { $_txt_margin = $attrs{'value'}; } } # # >>_Description:: # {{Y:_TxtPhraseHandlerChar}} handles the 'char' phrase directive. # sub _TxtPhraseHandlerChar { local(*para, $text, %attr) = @_; # local(); # Map those we know about it if (defined($_TXT_CHAR{$text})) { $para .= $_TXT_CHAR{$text}; } else { $para .= $text; } } # # >>_Description:: # {{Y:_TxtPhraseHandlerImport}} handles the 'import' phrase directive. # sub _TxtPhraseHandlerImport { local(*para, $filepath, %attr) = @_; # local(); local($name, $value); $para .= "** Unable to import figure $filepath **"; } # # >>_Description:: # {{Y:_TxtPhraseHandlerInline}} handles the 'inline' phrase directive. # sub _TxtPhraseHandlerInline { local(*para, $text, %attr) = @_; # local(); # Build the result $para .= $text; } # # >>_Description:: # {{Y:_TxtPhraseHandlerVariable}} handles the 'variable' phrase directive. # sub _TxtPhraseHandlerVariable { local(*para, $text, %attr) = @_; # local(); # do nothing } # package return value 1; ; local($added_anchors); local(@char_fonts); local($char_font); local($directive); # Process the text $para = ''; $state = 0; while (($sect_type, $text, $char_tag, %sect_attrs) = &SdfNextSection(*para_text, *state)) { #print "char_tag:$char_tag.\n"; #sdf-2.001/perllib/sdf/misc.pl010064400042570001753000000167570661420514000156310ustar00iancmtr00000400000236# $Id$ $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: Miscellaneous Library # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 31-Dec-96 ianc Added TJH's MiscFindImageFile # 29-Feb-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # This library provides miscellaneous routines. # # >>Description:: # # >>Limitations:: # # >>Resources:: # # >>Implementation:: # ##### Constants ##### # Default rules indexed on type %_MISC_DEFAULT_RULE = ( 'boolean', '<[01]>', 'integer', '<\d+>', ); ##### Variables ##### # # >>Description:: # {{Y:misc_date_strings}} contains the string lists used by # {{Y:MiscDateFormat}} indexed by the symbols (e.g. 'month') used # by that routine. # %misc_date_strings = ( "month" => ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"], "smonth" => ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"], "weekday" => ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"], "sweekday" => ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"], "ampm" => ["am", "pm"], "AMPM" => ["AM", "PM"] ); ##### Routines ##### # # >>Description:: # {{Y:MiscCheckRule}} checks a {{rule}} for a value {{$_}}. # If an execution error is detected, an appropriate error is output. # The result of the code executed is returned as {{result}}. # If {{rule}} is an empty string, {{type}} is used to lookup a # default rule for that type, if any. # If {{rule}} is still an empty string, 1 is returned. # sub MiscCheckRule { local($_, $rule, $type) = @_; local($result); # Get the default rule, if necessary $rule = $_MISC_DEFAULT_RULE{$type} if $rule eq ''; # For performance, handle common cases directly return 1 if $rule eq ''; return /^\d+$/ if $rule eq '<\d+>'; return /^[01]$/ if $rule eq '<[01]>'; # convert rule to Perl code, if necessary #$rule =~ s#^\s*\<(.*)\>\s*$#/^($1)\$/#; $rule =~ s#^\<(.*)\>$#/^($1)\$/#; # Return result &MiscDoAction($rule, "rule"); } # # >>Description:: # {{Y:MiscDoAction}} executes a block of Perl code ({{action}}). # If an execution error is detected, an appropriate error is output # using {{what}} to name the block of code that failed. The result # of the code executed is returned as {{result}}. {{action}} is only # executed if it exists. If it does not, 1 is returned. # sub MiscDoAction { local($action, $what) = @_; local($result) = 1; # Do the action, if any if ($action) { $result = eval $action; &AppMsg("error", "error executing $what: $@\nCODE IS:\n$action") if $@; } # Return result $result; } # # >>Description:: # {{Y:MiscTextWrap}} wraps a text string at a margin given by {{wrap}}. # {{prefix}} is the string to begin each wrapped line. # {{suffix}} is the string to terminate each wrapped line. # NB: # * {{prefix}} is not added to the first line # * {{suffix}} is not added to the last line # * {{wrap}} includes {{prefix}} but excludes {{suffix}} # NE: # sub MiscTextWrap { local($text, $wrap, $prefix, $suffix, $keep_spaces) = @_; local($newtext); local($word, @words); local($prefix_len, $length); # Prepare for looping through the words if ($keep_spaces) { @words = split(/ /, $text); } else { @words = split(/\s+/, $text); } $newtext = shift(@words); $length = length($newtext); $prefix_len = length($prefix); # Wrap the text while (defined($word = shift(@words))) { if ($length + length($word) < $wrap) { $newtext .= " $word"; $length += length($word) + 1; } elsif (length($word) + length($prefix) > $wrap && $length <= length($prefix)) { $newtext .= " $word"; $length += length($word) + 1; } else { $newtext .= "$suffix\n$prefix$word"; $length = length($word) + $prefix_len; } } # Return result return $newtext; } # # >>Description:: # {{Y:MiscDateFormat}} formats a date-time value. # {{fmt}} is a string containing the symbols below. # # !block table; format=352 # Symbol:Description:Example # $day:day number in month:6 or 22 # $day0:day number in month zero-padded:06 or 22 # $month:month name:January # $smonth:abbreviated month name:Jan # $monthnum:month number (1..12):6 or 12 # $monthnum0:month number zero-padded (01..12):06 or 12 # $year:year:1995 # $syear:abbreviated year:95 # $weekday:weekday name:Monday # $sweekday:abbreviated weekday name:Mon # $hour:hour (1..24):6 or 14 # $hour0:hour zero-padded (01..24):06 or 14 # $shour:hour (1..12):6 or 12 # $shour0:hour zero-padded (01..12):06 or 12 # $ampm:am or pm:am # $AMPM:AM or PM:PM # $minute:minute (0..59):0 or 42 # $minute0:minute zero-padded (00..59):00 or 42 # $second:second (0..59):0 or 42 # $second0:second zero-padded (00..59):00 or 42 # !endblock # # {{time}} is a number of seconds since January 1, 1970. # {{msg_type}} is the type of message, if any, to output # when a bad format is found. # sub MiscDateFormat { local($fmt, $time, $msg_type) = @_; local($result); package USER_MISC; local($day, $day0); local($month, $smonth, $monthnum, $monthnum0, $_month); local($year, $syear); local($weekday, $sweekday, $_wday); local($hour, $hour0, $shour, $shour0); local($minute, $minute0); local($second, $second0); # Get the quantities ($second, $minute, $hour, $day, $_month, $syear, $_wday) = localtime($main'time); $day0 = sprintf("%02d", $day); $month = $main::misc_date_strings{"month"}[$_month]; $smonth = $main::misc_date_strings{"smonth"}[$_month]; $monthnum = $_month + 1; $monthnum0 = sprintf("%02d", $monthnum); $year = $syear + 1900; $syear = sprintf("%02d", $syear % 100) if $syear > 99; $weekday = $main::misc_date_strings{'weekday'}[$_wday]; $sweekday = $main::misc_date_strings{'sweekday'}[$_wday]; $hour0 = sprintf("%02d", $hour); $shour = $hour - 12 if $hour > 12; $shour = 12 if $shour == 0; $ampm = $main::misc_date_strings{'ampm'}[$hour >= 12]; $AMPM = $main::misc_date_strings{'AMPM'}[$hour >= 12]; $shour0 = sprintf("%02d", $shour); $minute0 = sprintf("%02d", $minute); $second0 = sprintf("%02d", $second); # format the date-time $main'result = eval '"' . $main'fmt . '"'; package main; if ($msg_type && $@) { &AppMsg($msg_type, "bad datetime format '$fmt'"); } # result result return $result; } # # >>Description:: # {{Y:MiscUpperToMixed}} converts a name in an uppercase form (e.g. MY_STRING) # to a mixed-case form (e.g. MyString). # sub MiscUpperToMixed { local($upper) = @_; local($mixed); $mixed = $upper; substr($mixed, 1) =~ tr/A-Z/a-z/; $mixed =~ s/_([a-z0-9])/\u$1/g; return $mixed; } # # >>Description:: # {{Y:MiscMixedToUpper}} converts a name in a mixed-case form (e.g. MyString) # to an uppercase form (e.g. MY_STRING). # sub MiscMixedToUpper { local($mixed) = @_; local($upper); $upper = $mixed; substr($upper, 1) =~ s/([A-Z])/_$1/g; $upper =~ tr/a-z/A-Z/; return $upper; } # package return value 1; sdf-2.001/perllib/sdf/specials.pl010064400042570001753000000050720661420514000164650ustar00iancmtr00000400000236# $Id$ $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: SDF Special Phrases Library # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 29-Feb-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # This library provides the built-in special phrases # (implemented in [[Perl]]) for [[SDF]] files. # # >>Description:: # # Switch to the user package package SDF_USER; ##### General Special Tags ##### # CHAR - insert a character sub CHAR_Special { local(*style, *text, *attr) = @_; # local(); # Set the style name $style = '__char'; } # INLINE - inline text sub INLINE_Special { local(*style, *text, *attr) = @_; # local(); # Set the style name $style = '__inline'; } # IMPORT - insert a figure sub IMPORT_Special { local(*style, *text, *attr) = @_; # local(); # Process the filename and attributes &ProcessImageAttrs(*text, *attr); # Set the style name $style = '__import'; } # PAGENUM - insert the current page number (into a header/footer) sub PAGENUM_Special { local(*style, *text, *attr) = @_; # local(); # Set the style name $style = '__pagenum'; } # PAGECOUNT - insert the highest page number (into a header/footer) sub PAGECOUNT_Special { local(*style, *text, *attr) = @_; # local(); # Set the style name $style = '__pagecount'; } # PARATEXT - insert paragraph text (into a header/footer) sub PARATEXT_Special { local(*style, *text, *attr) = @_; # local(); # Set the style name $style = '__paratext'; } # PARANUM - insert paragraph number (into a header/footer) sub PARANUM_Special { local(*style, *text, *attr) = @_; # local(); # Set the style name $style = '__paranum'; } # PARANUMONLY - insert paragraph number only (into a header/footer) sub PARANUMONLY_Special { local(*style, *text, *attr) = @_; # local(); # Set the style name $style = '__paranumonly'; } # PARASHORT - insert paragraph short text (into a header/footer) sub PARASHORT_Special { local(*style, *text, *attr) = @_; # local(); # Set the style name $style = '__parashort'; } # PARALAST - insert paragraph text last found on page (into a header/footer) sub PARALAST_Special { local(*style, *text, *attr) = @_; # local(); # Set the style name $style = '__paralast'; } # package return value 1; sdf-2.001/perllib/sdf/toraw.pl010064400042570001753000000061030661420513700160200ustar00iancmtr00000400000236# $Id$ $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: RAW-SDF Format Driver # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 29-Feb-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # This library provides an [[SDF_DRIVER]] which generates # RAW (i.e. fully-expanded) [[SDF]]. # # >>Description:: # # >>Limitations:: # # >>Resources:: # # >>Implementation:: # ##### Constants ##### # # >>Description:: # {{Y:RawFormat}} is a format driver which outputs fully-expanded [[SDF]]. # sub RawFormat { local(*data) = @_; local(@result); local($para_tag, $para_text, %para_attrs); local($attrtext); # Process the paragraphs while (($para_text, $para_tag, %para_attrs) = &SdfNextPara(*data)) { # Convert the attributes to text $attrtext = &SdfAttrJoinSorted(*para_attrs); # Format the text $para_text = &_RawFormatText($para_text) unless $para_attrs{'verbatim'}; # Build result push(@result, "${para_tag}[$attrtext]$para_text"); } # Return result return @result; } # # >>_Description:: # {{Y:_RawFormatText}} formats the text of an SDF paragraph. # sub _RawFormatText { local($data) = @_; local($para); local($state); local($sect_type, $text, $char_tag, %sect_attrs); local($attrtext); local($spec_obj); # Build the paragraph body while (($sect_type, $text, $char_tag, %sect_attrs) = &SdfNextSection(*data, *state)) { if ($sect_type eq 'string') { $text = &_RawEscapeSpecialSymbols($text); $para .= $text; } elsif ($sect_type eq 'phrase') { # convert the attributes to text $attrtext = &SdfAttrJoinSorted(*sect_attrs); # Build the phrase $text = &_RawEscapeSpecialSymbols($text); $para .= "{{${char_tag}[$attrtext]$text"; } elsif ($sect_type eq 'phrase_end') { $para .= "}}"; } elsif ($sect_type eq 'special') { # convert the attributes to text $attrtext = &SdfAttrJoinSorted(*sect_attrs); # Build the phrase $para .= "{{__${char_tag}[$attrtext]$text}}"; } else { &AppMsg("warning", "unknown section type '$sect_type'"); } } # Return result return $para; } # # >>_Description:: # {{Y:_RawEscapeSpecialSymbols}} escapes special symbols in [[SDF]]. # sub _RawEscapeSpecialSymbols { local($text) = @_; local($result); # escape special symbols $text =~ s/\{(\\*)\{/'{\\' . ('\\' x length($1)) . '{'/eg; $text =~ s/\}(\\*)\}/'}\\' . ('\\' x length($1)) . '}'/eg; $text =~ s/\[(\\*)\[/'[\\' . ('\\' x length($1)) . '['/eg; $text =~ s/\](\\*)\]/']\\' . ('\\' x length($1)) . ']'/eg; # Return result return $text; } # package return value 1; sdf-2.001/perllib/sdf/parse.pl010075500042570001753000001654260672241661500160240ustar00iancmtr00000400000236# $Id$ $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: Simple Document Format Library # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 29-Feb-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # This library provides support for handling # [[SDF]] files. # # >>Description:: # The following symbols are occasionally accessed from other modules # but aren't really for public consumption: # # {{Y:SDF_IMAGE_EXTS}}, # {{Y:sdf_if_start}}, # {{Y:sdf_if_now}}, # {{Y:sdf_if_yet}}, # {{Y:sdf_if_else}}, # {{Y:sdf_block_start}}, # {{Y:sdf_block_type}}, # {{Y:sdf_block_text}}, # {{Y:sdf_block_param}}, # {{Y:sdf_tbl_start}}, # {{Y:sdf_tbl_state}}, # {{Y:sdf_end}}, # {{Y:sdf_cutting}}, # {{Y:sdf_sections}}, # {{Y:sdf_book_files}}, # {{Y:sdf_report_names}}, # {{Y:SdfSystem}}, # {{Y:SdfBatch}}, # {{Y:SdfDelete}}, # {{Y:SdfBookClean}}, # {{Y:SdfRenamePS}}. # # >>Limitations:: # Append/Prepend is not implemented for macros - is # it needed for them? # # {{Y:SdfBookConvert}} currently generates (Unix) shell scripts. # It should be generalised to support other operating systems? # # >>Resources:: # # >>Implementation:: # require "sdf/macros.pl"; require "sdf/podmacs.pl"; require "sdf/filters.pl"; require "sdf/specials.pl"; require "sdf/values.pl"; require "sdf/subs.pl"; require "sdf/calc.pl"; require Config; ##### Constants ##### # This should arguably be distributed into each driver. # (At the moment, FindFile() defaults to ps if a target isn't found.) %SDF_IMAGE_EXTS = ( 'ps' => ['epsi', 'eps', 'wmf', 'mif', 'gif'], 'html' => ['jpeg', 'jpg', 'png', 'gif'], 'hlp ' => ['bmp'], ); # Verbose phrase tag $_SDF_VERBOSE_TAG = 'V'; # Enums for phrase section types $_SDF_PHRASE_BEGIN = "\001"; $_SDF_PHRASE_END = "\002"; $_SDF_PHRASE_SPECIAL = "\003"; # Lookup table of syntax escapes %_SDF_SYNTAX_ESCAPE = ( 'lt', '<', 'gt', '>', '2{', '{{', '2}', '}}', '2[', '[[', '2]', ']]', ); # Lookup table of phrase prefixes for list tag characters %_SDF_LIST_ALIAS = ( '*', 'LU', '-', 'LU', '.', 'L', '^', 'LF', '+', 'LN', '&', 'LI', ); # Table of macros to execute inside an excluded section of conditional text %_SDF_MACRO_COND = ( 'if', 1, 'elsif', 1, 'elseif', 1, 'else', 1, 'endif', 1, '_eof_', 1, ); # Driver validation rules @_SDF_DRIVER_RULES = &TableParse( 'Field Category', 'Name key', 'Library mandatory', 'Subroutine mandatory', 'Paged optional', ); # Page size validation rules @_SDF_PAGESIZE_RULES = &TableParse( 'Field Category', 'Name key', 'Width mandatory', 'Height mandatory', 'Comment optional', ); ##### Variables ##### # # >>Description:: # {{Y:sdf_driver}} is a lookup table of valid format drivers. # This table is build by {{Y:SdfLoadDrivers}}. # %sdf_driver = (); # # >>Description:: # {{Y:sdf_report}} is a lookup table of valid reports. # This table is build by {{Y:SdfLoadReports}}. # %sdf_report = (); # # >>Description:: # {{Y:sdf_pagesize}} is a lookup table of valid page sizes. # This table is build by {{Y:SdfLoadPageSizes}}. # %sdf_pagesize = (); # driver lookup tables %_sdf_driver_library = (); %_sdf_driver_subroutine = (); #%_sdf_driver_paged = (); # List of sections for the current paragraph @_sdf_section_list = (); # # >>Description:: # {{Y:sdf_subtopic_cnt}} is the counter of subtopics left during # topics mode processing. # $sdf_subtopic_cnt = 0; # # >>Description:: # {{Y:sdf_fmext}} is the extension of FrameMaker template files. # Typically values are 'fm5' and 'fm4'. # $sdf_fmext = 'fm5'; # # >>Description:: # {{Y:sdf_include_path}} contains the list of directories searched # for to find files specified in {{include}} macros. # {{Y:sdf_library_path}} contains the list of directories searched # for to find libraries and modules. # In both cases, the current directory and the document's directory # are searched before these directories and # {{Y:sdf_lib}} is searched last of all. # @sdf_include_path = (); @sdf_library_path = (); $sdf_lib = ''; # Stacks containing state of if macros: # * start - starting line number for error messages # * now - is the current text section to be included? # * yet - has a section been included yet? # * else - has the else macro been found yet? @sdf_if_start = (); @sdf_if_now = (); @sdf_if_yet = (); @sdf_if_else = (); # State of current block, if any $sdf_block_start = ''; $sdf_block_type = ''; @sdf_block_text = (); %sdf_block_param = (); $_sdf_block_cnt = 0; $_sdf_block_char = ''; # Stacks of starts/states for table macros @sdf_tbl_start = (); @sdf_tbl_state = (); # Buffer containing finalisation code (build via the 'end' filter) @sdf_end = (); # Ignoring text flag (ala POD) $sdf_cutting = 0; # Section counter $sdf_sections = 0; # Next $app_lineno buffer $_sdf_next_lineno = 0; # Buffer holding the init line from the main topic $_sdf_init_line = ''; # Stack of strings to append to phrases @_sdf_append_stack = (); # Set of component files in a book @sdf_book_files = (); # Stack of running reports @sdf_report_names = (); # Counters for generating heading prefixes @_sdf_heading_counters = (); @_sdf_appendix_counters = (); # Package SDF_USER contains data exported to the user world %SDF_USER'var = (); $SDF_USER'style = ''; $SDF_USER'text = ''; $SDF_USER'append = ''; %SDF_USER'attr = (); $SDF_USER'level = 0; $SDF_USER'prev_style = ''; $SDF_USER'prev_text = ''; %SDF_USER'prev_attr = (); %SDF_USER'previous_text_for_style = (); ##### Routines ##### # # >>Description:: # {{Y:SdfLoadDrivers}} loads a configuration table of drivers. # The columns are: # # * {{Name}} - the driver name # * {{Library}} - the library containing the subroutine # * {{Subroutine}} - the subroutine name. ## * {{Paged}} - a non-blank value if paged-based output is produced by default. # # Call this routine before calling {{Y:SdfConvert}}. # sub SdfLoadDrivers { local(@table) = @_; # local(); local(@flds, $rec, %values); local($fmt); # Validate the table &TableValidate(*table, *_SDF_DRIVER_RULES) if $'verbose; # Load the drivers @flds = &TableFields(shift(@table)); for $rec (@table) { %values = &TableRecSplit(*flds, $rec); $fmt = $values{'Name'}; $sdf_driver{$fmt} = 1; $_sdf_driver_library{$fmt} = $values{'Library'}; $_sdf_driver_subroutine{$fmt} = $values{'Subroutine'}; #$_sdf_driver_paged{$fmt} = $values{'Paged'}; } } # # >>Description:: # {{Y:SdfLoadPageSizes}} loads a configuration table of page sizes. # sub SdfLoadPageSizes { local(@table) = @_; # local(); local(@flds, $rec, %values); local($size); # Validate the table &TableValidate(*table, *_SDF_PAGESIZE_RULES) if $'verbose; # Load the page sizes @flds = &TableFields(shift(@table)); for $rec (@table) { %values = &TableRecSplit(*flds, $rec); $size = $values{'Name'}; $sdf_pagesize{$size} = join("\000", @values{'Width', 'Height'}); # Add rotated page layouts $sdf_pagesize{$size . "R"} = join("\000", @values{'Height', 'Width'}); } } # # >>Description:: # {{Y:SdfFetch}} inputs an [[SDF]] file, # ready for {{Y:SdfConvert}} (i.e. ready conversion to another format). # It returns 1 if the file is opened successfully. # sub SdfFetch { local($file) = @_; local($success, @records); # Open the file open(SDF_FETCH, $file) || return (0, ()); # Mark the start of a new file @records = ("!_bof_ '$file'"); # Input the records while () { s/[ \t\n\r]+$//; push(@records, $_); } # Check structured macros have all been terminated correctly push(@records, "!_eof_"); # Close the stream (must occur after reference to $. above) close(SDF_FETCH); # Return result return (1, @records); } # # >>Description:: # {{Y:SdfParse}} prepares an array of SDF strings # for {{Y:SdfConvert}} (i.e. for conversion to another format). # sub SdfParse { local(@sdf_strs) = @_; local(@records); # Return result return ("!_bof_", @sdf_strs, "!_eof_"); } # # >>Description:: # {{Y:SdfConvert}} converts a list of sdf records to a list of # target format paragraphs. The input records to this routine # are usually read in by {{Y:SdfFetch}}. The output records # are typically output to a file, separated by newlines. # {{%convert_var}} is the initial set of variables. # sub SdfConvert { local(*p_sdf, $target, *uses, %convert_var) = @_; local(@result); local($orig_argv, $orig_context, $orig_lineno); local(@sdf); local($init_level, $i); local($first_line); local($library, $fn); # Init variables used in error messages. # $app_lineno is used as the line number as we cannot set $. - the # method assumes that $. is 0 (forcing AppMsg to use app_lineno instead) $orig_argv = $ARGV; $orig_context = $app_context; $orig_lineno = $app_lineno; # Init the global data $convert_var{'DOC_START'} = time; &SdfInit(*convert_var); # Load the standard stuff. # Notes: # * We 'use' rather than 'inherit' stdlib as the stdlib directory # is explicitly placed last on the search list - inherit would # put it first (or towards the front, at least). @sdf = ("!use 'stdlib/stdlib'"); push(@sdf, "!_load_look_"); push(@sdf, "!readonly 'OPT'"); push(@sdf, "!_load_tuning_"); push(@sdf, "!_load_config_"); # Load the required modules for $module (@uses) { push(@sdf, "!use '$module'"); } # Adjust the initial heading level, if requested $init_level = $convert_var{'OPT_HEAD_LEVEL'}; if ($init_level > 1) { for ($i = 1; $i < $init_level; $i++) { push(@sdf, "!slide_down"); } } elsif ($init_level eq '0') { push(@sdf, "!slide_up"); } # Adjust the heading look, if requested if ($convert_var{'OPT_HEAD_LOOK'} ne '') { my $ohl_macro = "!on paragraph '[HAP]\\d';; " . '$style = $var{"OPT_HEAD_LOOK"} . substr($style, 1)'; push(@sdf, $ohl_macro); } # Do the init macro, if any, for the file first $first_line = $p_sdf[1]; if ($first_line =~ /^\!\s*init\s*/) { unshift(@sdf, $first_line); $p_sdf[1] = ''; } # Call the line macro first to init DOC_PATH, etc. unshift(@sdf, "!line 0; '$ARGV'"); # Enable report processing, if necessary $report = $convert_var{'OPT_REPORT'}; if ($report) { push(@sdf, "!_bor_ $report"); push(@p_sdf, "!_eor_"); } # Prepend the user document to the config stuff push(@sdf, @p_sdf); # Call the format driver $library = $_sdf_driver_library{$target}; require $library; $fn = $_sdf_driver_subroutine{$target}; @result = eval {&$fn(*sdf)}; &AppMsg('failed', $@) if $@; # Restore program state $ARGV = $orig_argv; $app_context = $orig_context; $app_lineno = $orig_lineno; # Return result return @result; } # # >>Description:: # {{Y:SdfInit}} initialises global data used during the conversion process. # sub SdfInit { local(*var) = @_; # local(); # Initialise the user package package SDF_USER; #reset 'a-z'; # NOTE: THIS CLEARS THE MACRO/FILTER ARG/PARAM TABLES! &InitMacros; &InitPodMacros; &InitFilters; &InitSubs; # Initialise the user variables %var = %'var; @include_path = @'sdf_include_path; @library_path = @'sdf_library_path; @module_path = @'sdf_library_path; # Initialise global variables within this package package main; $sdf_block_start = ''; $sdf_block_type = ''; @sdf_block_text = (); %sdf_block_param = (); $_sdf_block_cnt = 0; $_sdf_block_char = ''; @_sdf_section_list = (); @sdf_if_start = (); @sdf_if_now = (); @sdf_if_yet = (); @sdf_if_else = (); @sdf_tbl_start = (); @sdf_tbl_state = (); @sdf_end = (); $sdf_cutting = 0; $sdf_sections = 0; $_sdf_next_lineno = 0; @_sdf_append_stack = (); @sdf_report_names = (); @_sdf_heading_counters = (); @_sdf_appendix_counters = (); %SDF_USER'previous_text_for_style = (); } # # >>Description:: # {{Y:SdfNextPara}} gets the next paragraph from an SDF buffer. # Format drivers use this routine to process buffers. # {{@sdf}} is the buffer which is updated ready for # another call to this routine. # sub SdfNextPara { local(*sdf) = @_; local($text, $style, %attr); local($_); local($lines, $macro, $parameters); local(@eaten); local($exclude_text); local($ok); local($macro_char); # Get the starting line number $app_lineno = $_sdf_next_lineno; # Process lines until we get the next paragraph record: while (defined($_ = shift(@sdf))) { $igc_cnt++; #print "sdf: $_<\n"; # Handle the beginning/end of section macros directly and asap # for performance. (These shouldn't appears inside a block.) if (/^\!_([be])os_ /) { package SDF_USER; # Need this for Perl 4 and 5 to work the same &_bos__Macro($') if $1 eq 'b'; &_eos__Macro($') if $1 eq 'e'; next record; } # Update the line number $app_lineno++ unless $sdf_sections; # If we're "cutting" text as POD does, ignore lines until a # =-style macro or !_eof_ is found if ($sdf_cutting) { next record unless /^=/ || /^!_eof_/; $sdf_cutting = 0; } # For block sections, save the lines in a scratch buffer if ($sdf_block_type ne '') { # We handle the non-macro case first for performance push(@sdf_block_text, $_),next unless /^\!_eof_/ || /^\s*$_sdf_block_char(end)?$sdf_block_type/; # Fetch the macro ($lines, $macro, $parameters) = &_SdfFetchMacro($_, *sdf, *eaten); $app_lineno += $lines; # Detect block ends if ($macro eq "end$sdf_block_type" && --$_sdf_block_cnt == 0) { unshift(@sdf, &SDF_USER'ExecMacro($macro, $parameters, 'error')); if (@sdf_end) { push(@sdf, @sdf_end); @sdf_end = (); } next record; } # Make sure end-of-file processing is not missed elsif ($macro eq '_eof_') { unshift(@sdf, &SDF_USER'ExecMacro($macro, $parameters, 'error')); next record; } # Detect nested blocks $_sdf_block_cnt++ if $macro eq $sdf_block_type; # Save the text into a scratch buffer push(@sdf_block_text, @eaten); next record; } # Determine the exclude_text flag $exclude_text = @sdf_if_now && !$sdf_if_now[$#sdf_if_now]; # Handle macros if (/^\s*([=!])/) { $macro_char = $1; ($lines, $macro, $parameters) = &_SdfFetchMacro($_, *sdf, *eaten); $app_lineno += $lines; # If we are inside an excluded section of an if macro, # ignore everything except conditional macros (and eof checking) next record if $exclude_text && !$_SDF_MACRO_COND{$macro}; # Process the macro - if this macro starts a block, set the # nested count and starting character accordingly unshift(@sdf, &SDF_USER'ExecMacro($macro, $parameters, 'warning')); if (@sdf_end) { push(@sdf, @sdf_end); @sdf_end = (); } if ($sdf_block_type ne '') { $_sdf_block_cnt = 1; $_sdf_block_char = "\\" . $macro_char; } next record; } # Ignore paragraphs inside an excluded section of an if macro next record if $exclude_text; # remove leading and trailing whitespace s/^\s+//; s/\s+$//; # skip comments and blank lines next record if /^#/ || /^\s*$/; # If we reach here, we have the start of the next paragraph $app_context = 'para. on ' unless $sdf_sections; ($lines, $ok, $style, $text, %attr) = &_SdfFetchPara($_, *sdf); # Convert level 0 headings to the build_title macro if ($style =~ /^[HAP]0$/) { $SDF_USER'var{'DOC_NAME'} = $text; unshift(@sdf, "!build_title"); $_sdf_next_lineno--; next; } # Prepended text causes a failure, triggering re-processing. # Likewise, we return nothing if a report is running. $_sdf_next_lineno = $app_lineno + $lines; next unless $ok; next if @sdf_report_names; return ($text, $style, %attr); } print "lines: $igc_cnt\n" if $SDF_USER'var{'igc'}; # If we reach here, the buffer is empty return (); } # # >>_Description:: # {{Y:_SdfFetchMacro}} fetches the macro starting on the current line, if any. # {{$_}} is the current line and # {{@rest}} is the rest of the input buffer. # {{$lines}} is the number of lines read from {{@rest}}. # {{@eaten}} is the set of lines consumed. # sub _SdfFetchMacro { local($_, *rest, *eaten) = @_; local($lines, $macro, $parameters); local($line); # At a minimum, we consume the current line. @eaten = ($_); # Handle !-style - lines ending in \ are continued onto the next line, # unless there are exactly 2 backslashes at the end of the line if (s/^\s*\!\s*//) { s/\s+$//; return (0, split(/\s+/, $_, 2)) unless /\\$/; # Handle \\ case if (/[^\\]\\\\$/) { s/\\$//; return (0, split(/\s+/, $_, 2)); } # Handle other cases (1, 3, 4 ..) s/\\$/ /; $line = $_; while (defined($_ = shift(@rest))) { push(@eaten, $_); $lines++ unless $sdf_sections; s/^\s+//; s/\s+$//; $line .= $_; last unless $line =~ s/\\$/ /; } return ($lines, split(/\s+/, $line, 2)); } # Handle =-style - an empty line terminates the macro call if (s/^\s*\=\s*//) { s/\s+$//; $line = $_; while (defined($_ = shift(@rest))) { push(@eaten, $_); $lines++ unless $sdf_sections; s/^\s+//; s/\s+$//; last if $_ eq ''; $line .= " $_"; } return ($lines, split(/\s+/, $line, 2)); } } # # >>_Description:: # {{Y:_SdfFetchPara}} fetches the next paragraph. # {{$_}} is the current line and # {{@rest}} is the rest of the input buffer. # {{$lines}} is the number of lines read from {{@rest}}. # sub _SdfFetchPara { local($_, *rest) = @_; local($lines, $ok, $style, $text, %attr); local($para); local($name); # Handle normal paragraphs $para = $_; if ($para !~ /^__/) { while (defined($_ = $rest[0])) { # Remove leading and trailing whitespace s/^\s+//; s/\s+$//; # Paragraphs are terminated by macros, comments, blank lines and new # paragraphs - the tests are ordered to match the most likely first. last if /^\!/; last if /^\#/; last if /^$/; last if /^[-*^+\.&]+/; last if /^\>/; last if /^\=/; last if /^([A-Z_0-9]\w*|)\:/; last if /^([A-Z_0-9]\w*|)\[[^\[]/; # A leading \ simply escapes special characters so strip it s/^\\//; # Append this line $para .= " $_"; shift(@rest); # Update the line number $lines++ unless $sdf_sections; } } # Parse the paragraph #print STDERR "fetch:$para<\n"; ($style, $text, %attr) = &_SdfParsePara($para); # For directives, skip the rest return ($lines, 1, $style, $text, %attr) if $style =~ /^__/; # Activate event processing if ($attr{'noevents'}) { delete $attr{'noevents'}; } else { package SDF_USER; local($style, $text, %attr, @_prepend, @_append); $'attr{'orig_style'} = $'style; $style = $'style; $text = $'text; %attr = %'attr; @_prepend = (); @_append = (); &ReportEvents('paragraph') if @'sdf_report_names; &ExecEventsStyleMask(*evcode_paragraph, *evmask_paragraph); &ReportEvents('paragraph', 'Post') if @'sdf_report_names; $'style = $style; $'text = $text; %'attr = %attr; $level = $1 if $style =~ /^[HAP](\d)$/; $prev_style = $style; $prev_text = $text; %prev_attr = %attr; $previous_text_for_style{$style} = $text unless $attr{'continued'}; unshift(@'rest, "!_bos_ $'app_lineno;text appended to ", @_append, "!_eos_ $'app_lineno;$'app_context") if @_append; if (@_prepend) { #printf STDERR "prepending \n\t%s<\n", join("<\n\t", @_prepend); $attr{'noevents'} = 1; unshift(@'rest, "!_bos_ $'app_lineno;text prepended to ", @_prepend, &'SdfJoin($style, $text, %attr), "!_eos_ $'app_lineno;$'app_context"); return (); } } # I'm not yet sure why, but occasionally we reach here with noevents # defined. If this happens, delete it. delete $attr{'noevents'}; # Remove target-specific attributes for other targets &SdfAttrClean(*attr) if %attr; # Check the style is legal unless (defined($SDF_USER'parastyles_name{$style})) { &AppMsg("warning", "unknown paragraph style '$style'"); } # Check the attributes are legal for $name (keys %attr) { &_SdfAttrCheck($name, $attr{$name}, "paragraph"); } # Add units to size, if necessary # (might be better to do this as a measure type oneday?) if ($attr{'size'} =~ /^[\d\.]+$/) { $attr{'size'} .= 'pt'; } # Return result #printf STDERR "style:$style, text:$text.\n"; return ($lines, 1, $style, $text, %attr); } # # >>_Description:: # {{Y:_SdfParsePara}} parses an SDF paragraph into its components. # sub _SdfParsePara { local($para) = @_; local($style, $text, %attr); local($attrs); local($tab_size); local($level); local($special); #print STDERR "para:$para.\n"; # Handle paragraphs with normal styles if ($para =~ /^([A-Z_0-9]\w*|):/ || $para =~ /^([A-Z_0-9]\w*|)\[\s*\]/) { $style = $1; $attrs = ''; $text = $'; } elsif ($para =~ /^([A-Z_0-9]\w*|)\[([^\[][^\]]*)\]/) { $style = $1; $attrs = $2; $text = $'; # If the ] was escaped, we need to find the real one # in a non-greedy way if ($attrs =~ s/\\$/]/) { if ($text =~ /(.*?[^\\])\]/) { $attrs .= $1; $text = $'; #print "attrs: $attrs.\n"; #print "text : $text.\n"; } else { $attrs .= $text; $text = ''; &AppMsg("warning", "] at end of attributes not found"); } } } # Handle paragraphs with shorthand styles elsif ($para =~ /^(>)/) { $style = 'V'; $attrs = ''; $text = $'; } elsif ($para =~ /^([-*^+\.&]{1,6})(\[\s*\])?/) { $special = $1; $attrs = ''; $text = $'; } elsif ($para =~ /^([-*^+\.&]{1,6})(\[([^\]][^\]]*)\])?/) { $special = $1; $level = length($1); $level++ if substr($1, 0, 1) eq '-' && $level < 6; $style = "$_SDF_LIST_ALIAS{$1}$level"; $attrs = $3; $text = $'; } # Handle normal paragraphs else { $style = ''; $attrs = ''; $text = $para; # A leading \ simply escapes special characters so strip it $text =~ s/^\\//; } # Parse the attributes %attr = &SdfAttrSplit($attrs) if $attrs ne ''; # Convert the special tag to a style, if necessary if ($special) { $level = length($special); $special = substr($special, 0, 1); $level++ if $special eq '-' && $level < 6; $style = "$_SDF_LIST_ALIAS{$special}$level"; } # If the style is not set, use the default style $style = 'N' if $style eq ''; # Map aliases if ($style eq 'V') { $style = 'E'; $attr{'verbatim'} = 1; } # Trim leading space except for examples and internal directives # For examples, convert tabs to spaces if ($SDF_USER'parastyles_category{$style} eq 'example') { $tab_size = $SDF_USER'var{'DEFAULT_TAB_SIZE'}; 1 while $text =~ s/\t+/' ' x (length($&) * $tab_size - length($`) % $tab_size)/e; } elsif ($style !~ /^__/) { $text =~ s/^\s+//; } # Return result return ($style, $text, %attr); } # # >>Description:: # {{Y:SdfParseCell}} parses an SDF cell into its components. # sub SdfParseCell { local($cell) = @_; local($text, %attr); local($attrs); # Simple for now if ($cell =~ /^\s*\[\s*\]/) { $attrs = ''; $text = $'; } if ($cell =~ /^\s*\[\s*([a-z][^\]]*)\s*\]/) { $attrs = $1; $text = $'; } else { $attrs = ''; $text = $cell; } # Parse the attributes %attr = &SdfAttrSplit($attrs) if $attrs ne ''; # Return result return ($text, %attr); } # # >>_Description:: # {{Y:_SdfParaExpand}} expands embedded expressions # within a paragraph. # sub _SdfParaExpand { local($text) = @_; local($expanded); local($pre, $mid, $begin, $end); # Handle embedded expressions $expanded = ''; section: while ($text ne '') { # Get the next set of delimiters $begin = index($text, '[['); last section unless $begin >= 0; $end = index($text, ']]', $begin + 2); last section unless $end >= 0; # Get the sub-strings $pre = substr($text, 0, $begin); $mid = substr($text, $begin + 2, $end - $begin - 2); $mid = &_SdfEvaluate($mid, "warning"); $text = substr($text, $end + 2); # handle nested expansion if (index($mid, '[[') >= 0) { $mid = &_SdfParaExpand($mid); } # Build the result $expanded .= $pre . $mid; } if ($text ne '') { # Build the result $expanded .= $text; } # return result return $expanded; } # # >>_Description:: # {{Y:_SdfVerbosePhrases}} expands E<2{> style phrases within a paragraph. # sub _SdfVerbosePhrases { local($text) = @_; local($expanded); local($nested); my($begin_index, $end_index); # Convert the other escapes $nested = 0; while ($text ne '') { # A nested }} without a proceeding {{ is a phrase end $begin_index = ($text =~ /\{\{/) ? length($`) : length($text); $end_index = ($text =~ /\}\}/) ? length($`) : length($text); if ($nested && ($end_index < $begin_index)) { $nested--; $text = $'; $expanded .= &_SdfVerboseEscape($`) . '>'; } # A phrase which may have something nested elsif ($text =~ /\{\{/) { $expanded .= "$`$_SDF_VERBOSE_TAG<"; $text = $'; $nested++; } # No sequences left else { $expanded .= $text; $text = ''; } } # return result return $expanded; } # # >>_Description:: # {{Y:_SdfVerboseEscape}} escapes chatacters within a E<2{> style phrase. # sub _SdfVerboseEscape { local($text) = @_; local($result); # If a [A-Z]< style phrase is found, do nothing return $text if $text =~ /[A-Z]\ characters $result = $text; $result =~ s/\>/E/g; return $result; } # # >>_Description:: # {{Y:_SdfTextToSections}} converts paragraph text to a list of sections. # sub _SdfTextToSections { local($text) = @_; local(@section); local(@nested); local($append); # The ones above are explicitly local so that *xxx works for # calls to SdfAddPhrase my($begin_index, $end_index); # Do expression and long phrase substitution on the text #print "text 1:$text<\n"; $text = &_SdfParaExpand($text); #print "text 2:$text<\n"; $text = &_SdfVerbosePhrases($text); #print "text 3:$text<\n"; # Parse the string into bits $append = 0; while ($text ne '') { # A > without a proceeding [A-Z]< is a sequence end marker $begin_index = ($text =~ /[A-Z]\/) ? length($`) : length($text); if (@nested && ($end_index < $begin_index)) { $text = $'; &_SdfAddPhrase($`, *text, *section, *nested, *append); } # A sequence which starts immediately elsif ($text =~ /^([A-Z])\>Description:: # {{Y:SdfNextSection}} gets the next section of a paragraph. # Format drivers use this routine to process paragraphs. # {{$para}} is the paragraph text which is updated ready for # another call to this routine. {{$state}} is a state variable # which this routines uses to help it keep state. # {{sect_type}} is one of: # # * {{string}} - a string normal paragraph text # * {{phrase}} - a phrase # * {{phrase_end}} - end of a phrase # * {{special}} - a special phrase (e.g. CHAR, IMPORT, etc.) # * an empty string - end of paragraph # # For a string, {{text}} is the string, {{style}} and {{attr}} are empty. # At the end of a phrase, {{text}}, {{style}} and {{attr}} are empty. # sub SdfNextSection { local(*para, *state) = @_; local($sect_type, $text, $style, %attr); local($section); # Init things, if necessary if ($state == 0) { @_sdf_section_list = &_SdfTextToSections($para); } #print "$para<\n", "state:$state,", $#_sdf_section_list, "\n"; # Check for end of paragraph return () if $state > $#_sdf_section_list; # Get the next section $section = $_sdf_section_list[$state++]; # Handle end of phrase if ($section eq $_SDF_PHRASE_END) { return ("phrase_end"); } # Handle phrases elsif ($section eq $_SDF_PHRASE_BEGIN) { return ("phrase", @{$_sdf_section_list[$state++]}); } # Handle special phrases elsif ($section eq $_SDF_PHRASE_SPECIAL) { return ("special", @{$_sdf_section_list[$state++]}); } # Must be a normal paragraph else { return ("string", $section); } } # # >>_Description:: # {{Y:_SdfPhraseProcess}} processes a phrase. # It returns the style, text and attributes. # sub _SdfPhraseProcess { local($tag, $sdf) = @_; local($style, $text, $append, %attr); local($attrs); local($name); local($fn); #print "phrase:$tag,$sdf<\n"; # Get the components if ($tag ne $_SDF_VERBOSE_TAG) { $style = $tag eq 'E' ? 'CHAR' : $tag; $attrs = ''; $text = $sdf; } elsif ($sdf =~ /^([A-Z_0-9]\w*|):/ || $sdf =~ /^([A-Z_0-9]\w*|)\[\s*\]/) { $style = $1; $attrs = ''; $text = $'; } elsif ($sdf =~ /^([A-Z_0-9]\w*|)(\[([^\[][^\]]*)\])/) { $style = $1; $attrs = $3; $text = $'; # If the ] was escaped, we need to find the real one # in a non-greedy way if ($attrs =~ s/\\$/]/) { if ($text =~ /(.*?[^\\])\]/) { $attrs .= $1; $text = $'; #print "attrs: $attrs.\n"; #print "text : $text.\n"; } else { $attrs .= $text; $text = ''; &AppMsg("warning", "] at end of attributes not found"); } } } else { $style = ''; $attrs = ''; $text = $sdf; } # If not set, use the default style $style = 1 if $style eq ''; # Trim leading space except for examples if ($SDF_USER'phrasestyles_category{$style} ne 'example') { $text =~ s/^\s+//; } # Parse the attributes %attr = &SdfAttrSplit($attrs); # Handle special styles if ($SDF_USER'phrasestyles_category{$style} eq 'special') { $fn = "SDF_USER'${style}_Special"; if (defined &$fn) { &$fn(*style, *text, *attr); } else { &AppMsg("warning", "unable to find handler for special style '$style'"); } return ($style, $text, '', %attr); } # Activate event processing package SDF_USER; $style = $'style; $text = $'text; $append = ''; %attr = %'attr; &ReportEvents('phrase') if @'sdf_report_names; &ExecEventsStyleMask(*evcode_phrase, *evmask_phrase); &ReportEvents('phrase', 'Post') if @'sdf_report_names; $'style = $style; $'text = $text; $'append = $append; %'attr = %attr; undef $style; undef $text; undef %attr; package main; # Check for hypertext #$style = 'JUMP' if $attr{'jump'} ne ''; # Default index text, if necessary if ($attr{'index'} eq '1' || $attr{'index_type'} ne '' && $attr{'index'} eq '') { $attr{'index'} = $text; } # Add units to size, if necessary # (might be better to do this as a measure type oneday?) if ($attr{'size'} =~ /^[\d\.]+$/) { $attr{'size'} .= 'pt'; } # Check the style is legal if ($style !~ /^__/) { unless (defined($SDF_USER'phrasestyles_name{$style})) { &AppMsg("warning", "unknown phrase style '$style'"); } } # Remove target-specific attributes for other targets &SdfAttrClean(*attr); # check the attributes are legal for $name (keys %attr) { &_SdfAttrCheck($name, $attr{$name}, "phrase"); } # Return result return ($style, $text, $append, %attr); } # # >>Description:: # {{Y:SdfPoints}} converts a measurement to points. # This is required for calculations involving measurements. # sub SdfPoints { local($measure) = @_; # local($pts); return 0 unless $measure =~ /^([\d\.]+)/; if ($' eq 'pt' || $' eq '') { # We put this first for performance reasons return $1; } elsif ($' eq 'in' || $' eq '"') { return $1 * 72; } elsif ($' eq 'mm') { return $1 * 2.835; } elsif ($' eq 'cm') { return $1 * 28.35; } else { return 0; } } # # >>Description:: # {{Y:SdfVarPoints}} converts an variable to points. # sub SdfVarPoints { local($name) = @_; # local($pts); return &SdfPoints($SDF_USER'var{$name}); } # # >>Description:: # {{Y:SdfPageInfo}} returns information about a page. # sub SdfPageInfo { local($page, $attr, $category) = @_; local($info); local($part, $newpage); if ($category eq 'macro') { if (defined $SDF_USER'macro{"PAGE_${page}_$attr"}) { $info = $SDF_USER'macro{"PAGE_${page}_$attr"}; } elsif ($page =~ /_/) { ($part, $newpage) = ($`, $'); $newpage = 'RIGHT' if $newpage eq 'FIRST' && $part ne 'FRONT'; #printf STDERR "$page -> $newpage ($attr)\n"; $info = $SDF_USER'macro{"PAGE_${newpage}_$attr"}; } } else { if (defined $SDF_USER'var{"PAGE_${page}_$attr"}) { $info = $SDF_USER'var{"PAGE_${page}_$attr"}; } elsif ($page =~ /_/) { ($part, $newpage) = ($`, $'); $newpage = 'RIGHT' if $newpage eq 'FIRST' && $part ne 'FRONT'; #printf STDERR "$page -> $newpage ($attr)\n"; $info = $SDF_USER'var{"PAGE_${newpage}_$attr"}; } if ($category eq 'pt') { $info = &SdfPoints($info); } } # Return result return $info; } # # >>_Description:: # {{Y:_SdfEvaluate}} evaluates and returns an SDF expression. # If only a word is found which looks like an enumerated value (i.e. # first character is uppercase & remaining characters are lowercase) # and {{enum}} is true, then that word is returned as a string. # If only a name is found, the result is the value of that variable. # If only a '!' character followed by a name is found, # the result is the negation of that variable. # If the first character is + or =, then the rest is assumed to # be an argument to the {{Calc}} subroutine. # Otherwise, the expression is evaluated as Perl. If Perl cannot # evaulate the expression, an error is output. If the expression # looks like a name and it is not defined and {{msg_type}} is # specified, then a message of that type is output explaining # that the variable is unknown. In either case, we return an empty # string if the variable is not found or the evaluation fails. # sub _SdfEvaluate { local($expr, $msg_type, $enum) = @_; local($result); local($format); local($action, $SDF_USER'_); # Get the format, if any $format = $1 if $expr =~ s/^(\w+)://; # Handle simple numbers and strings directly (i.e. skip the eval) if ($expr =~ /^"([^"\\\$]*)"$/ || $expr =~ /^'([^'\\]*)'$/) { $result = $1; } elsif ($expr =~ /^\d+$/) { $result = $expr; } # Enumerated values elsif ($enum && $expr =~ /^[A-Z][a-z]+$/) { $result = $expr; } # Variables elsif ($expr =~ /^\w+$/) { if (!defined($SDF_USER'var{$expr})) { if ($msg_type) { &AppMsg($msg_type, "variable '$expr' not defined"); } $result = ''; } else { $result = $SDF_USER'var{$expr}; } } elsif ($expr =~ /^\!\s*(\w+)$/) { $result = $SDF_USER'var{$1} ? 0 : 1; } elsif ($expr =~ /^$/) { $result = ''; } # Handle implicit calls to Calc elsif ($expr =~ /^[=+]\s*(.+)$/) { $result = &SDF_USER'Calc($1); } else { # evaluate the expression in "user-land" package SDF_USER; $main'result = eval $main'expr; package main; if ($@) { &AppMsg("warning", "evaluation of '$expr' failed: $@"); $result = ''; } } # Apply the format, if any if ($format ne '') { $action = $SDF_USER'var{"FORMAT_$format"}; if ($action eq '') { &AppMsg("warning", "unknown format '$format'"); } else { package SDF_USER; $_ = $main'result; $main'result = eval $main'action; package main; if ($@) { &AppMsg("warning", "format '$format' failed: $@"); } } } # Return result return $result; } # # >>Description:: # {{Y:SdfJoin}} formats a style, text and attributes into a paragraph. # sub SdfJoin { local($style, $text, %attr) = @_; local($sdf); # Return result return join('', $style, '[', &SdfAttrJoin(*attr), ']', $text); } # # >>Description:: # {{Y:SdfAttrSplit}} parses a string of attributes into a set of # name-value pairs. # sub SdfAttrSplit { local($attrs) = @_; local(%attrs); local(@attrs, $append); local($attr, $name, $value); # build the list of attributes, remembering that ';;' means ';', but # ignoring a leading ';'. $attrs =~ s/^\s*;\s*//; @attrs = (); $append = 0; for $attr (split(/;/, $attrs)) { if ($attr eq '') { $attrs[$#attrs] .= ';'; $append = 1; } elsif ($append) { $attrs[$#attrs] .= $attr; $append = 0; } else { $attr =~ s/^\s+//; $attr =~ s/\s+$//; push(@attrs, $attr) if $attr ne ''; } } # parse the attributes for $attr (@attrs) { if ($attr =~ /^([^=]+)\=/) { $name = $1; $value = &_SdfEvaluate($', '', 1); } else { $name = $attr; $value = 1; } $attrs{$name} = $value; } # return result return %attrs; } # # >>Description:: # {{Y:SdfAttrJoin}} formats a set of name-value pairs (%attr) into a string. # {{sep}} is the separator to use between attributes. The default # separator is semi-colon. # sub SdfAttrJoin { local(*attr, $sep) = @_; local($attrtext); local($key, $value, @attrtext); # default the separator $sep = ";" if $sep eq ''; # convert the attributes to text @attrtext = (); for $key (keys %attr) { $value = $attr{$key}; #$value =~ s/\\/\\\\/g; #$value =~ s/'/\\'/g; #$value =~ s/([\]])/\\]/g; $value =~ s/(['\]\\])/\\$1/g; if ($sep eq ";") { $value =~ s/\;+/$&;/g; } if ($value !~ /^\d+$/) { $value = "'" . $value . "'"; } push(@attrtext, "$key=$value"); } $attrtext = join($sep, @attrtext); # Return result #print "attrs: $attrtext.\n"; return $attrtext; } # # >>Description:: # {{Y:SdfAttrJoinSorted}} formats a set of name-value pairs (%attr) into # a string where the attributes are sorted by name. # {{sep}} is the separator to use between attributes. The default # separator is semi-colon. # sub SdfAttrJoinSorted { local(*attr, $sep) = @_; local($attrtext); local($key, $value, @attrtext); # default the separator $sep = ";" if $sep eq ''; # convert the attributes to text @attrtext = (); for $key (sort keys %attr) { $value = $attr{$key}; #$value =~ s/\\/\\\\/g; #$value =~ s/'/\\'/g; #$value =~ s/([\]])/\\]/g; $value =~ s/(['\]\\])/\\$1/g; if ($sep eq ";") { $value =~ s/\;+/$&;/g; } if ($value !~ /^\d+$/) { $value = "'" . $value . "'"; } push(@attrtext, "$key=$value"); } $attrtext = join($sep, @attrtext); # Return result return $attrtext; } # # >>Description:: # {{Y:SdfAttrClean}} removes target-specific attributes (for other targets) # from a set of attributes. However, if the driver is 'raw', all attributes # are kept. # sub SdfAttrClean { local(*attr) = @_; # local(); local($driver, $target); local($name); # Keep all attributes for raw format $driver = $SDF_USER'var{'OPT_DRIVER'}; return if $driver eq 'raw'; # Delete attributes in 'families' other than the current driver or target $target = $SDF_USER'var{'OPT_TARGET'}; for $name (keys %attr) { delete $attr{$name} if $name =~ /^(\w+)\./ && $1 ne $driver && $1 ne $target; } } # # >>Description:: # {{Y:SdfAttrMap}} maps a set of attributes using the configuration tables # {{%map_to}}, {{%map_map}} and {{%map_attrs}}. # {{$defaults}} is a string of default attributes. # This routine is used by format drivers to merge user-supplied # attributes with those in 'attribute' and 'style' configuration tables. # sub SdfAttrMap { local(*attr, $target, *map_to, *map_map, *map_attrs, $defaults) = @_; # local(); local($name, $value, $to, $map, %new, $new); # Map the user-supplied attributes for $name (keys %attr) { $value = $attr{$name}; # Get the configuration details $to = $map_to{$name}; $map = $map_map{$name}; %new = &SdfAttrSplit($map_attrs{$name}); # If 'To' is set, change the name #$name = "$target.$to" if $to ne ''; if ($to ne '') { delete $attr{$name}; # delete the existing name $name = "$target.$to"; } # If 'Map' is set, change the value &_SdfAttrValueMap(*value, $map) if $map; # Update the changes, if any if ($to || $map) { $attr{$name} = $value; #print "new $name=$value<\n"; } # Add implicit attributes, if any for $new (keys %new) { $attr{"$target.$new"} = $new{$new}; } } # Merge in the defaults %new = &SdfAttrSplit($defaults); for $new (keys %new) { $name = "$target.$new"; $attr{$name} = $new{$new} unless defined $attr{$name}; } } # # >>_Description:: # {{Y:_SdfAttrValueMap}} maps a value using either a lookup table or # a subroutine. # sub _SdfAttrValueMap { local(*value, $map) = @_; # local(); local($name, $action); local($newvalue); # Build the action $name = substr($map, 1); $action = ($map =~ /^\%/) ? "\$$name\{\$'value\}" : "&$name(\$'value)"; # Get the new value package SDF_USER; $'newvalue = eval $'action; package main; &AppMsg("warning", "attribute mapping via '$map' failed: $@ (action: $action)") if $@; $value = $newvalue if defined $newvalue; } # # >>_Description:: # {{Y:_SdfAttrCheck}} checks an attribute. # {{kind}} should be either "phrase" or "paragraph". # sub _SdfAttrCheck { local($name, $value, $kind) = @_; # local(); local($type, $rule); # check the attribute is known & get the type and rule, if any if ($kind eq 'paragraph') { unless ($SDF_USER'paraattrs_name{$name}) { &AppMsg("warning", "unknown paragraph attribute '$name'"); } $type = $SDF_USER'paraattrs_type{$name}; $rule = $SDF_USER'paraattrs_rule{$name}; } else { unless ($SDF_USER'phraseattrs_name{$name}) { &AppMsg("warning", "unknown phrase attribute '$name'"); } $type = $SDF_USER'phraseattrs_type{$name}; $rule = $SDF_USER'phraseattrs_rule{$name}; } # validate the rule, if any unless (&MiscCheckRule($value, $rule, $type)) { &AppMsg("warning", "bad value '$value' for $kind attribute '$name'"); } } # # >>Description:: # {{Y:SdfSizeGraphic}} returns the {{width}} and {{height}} of a graphic # stored in {{file}}. Zero is returned for both values if the size could not # be extracted. File types currently supported are EPSI, PICT, GIF and PCX. # sub SdfSizeGraphic { local($file) = @_; local($width, $height); local($ext); local($line); local($junk, $tlbr, $top, $left, $bottom, $right, $xy); local($xmin1, $xmin2, $ymin1, $ymin2, $xmax1, $xmax2, $ymax1, $ymax2); local($wh, $w1, $w2, $h1, $h2); local($upi1, $upi2, $scale); # Get the file extension $ext = (&'NameSplit($file))[2]; # Open the file open(SDF_GRAPHIC, $file) || return (0,0); # EPSI files: look for BoundingBox statement if ($ext eq 'eps' || $ext eq 'epsi' || $ext eq 'ai') { while (($line = ) ne '') { if ($line =~ /^%%BoundingBox:\s+([\d\.]+)\s+([\d\.]+)\s+([\d\.]+)\s+([\d\.]+)/) { $width = sprintf("%dpt", $3 - $1 + 1); $height = sprintf("%dpt", $4 - $2 + 1); last; } } } # PICT files: bytes 514+8 are Top,Left and Bottom,Right elsif ($ext eq 'pct' || $ext eq 'pict') { if (read(SDF_GRAPHIC, $junk, 514) && read(SDF_GRAPHIC, $tlbr, 8)) { ($top, $left, $bottom, $right) = unpack("S4", $tlbr); $width = sprintf("%dpt", $right - $left + 1); $height = sprintf("%dpt", $bottom - $top + 1); } } # GIF files: bytes 7-10 are width and height with low order byte 1st elsif ($ext eq 'gif') { if (read(SDF_GRAPHIC, $junk, 6) && read(SDF_GRAPHIC, $wh, 4)) { ($w1, $w2, $h1, $h2) = unpack("C4", $wh); $width = sprintf("%dpt", $w2 * 256 + $w1); $height = sprintf("%dpt", $h2 * 256 + $h1); } } # PCX files: bytes 5-12 are Xmin,Ymin,Xmax,Ymax with low order byte 1st elsif ($ext eq 'pcx') { if (read(SDF_GRAPHIC, $junk, 4) && read(SDF_GRAPHIC, $xy, 8)) { ($xmin1, $xmin2, $ymin1, $ymin2, $xmax1, $xmax2, $ymax1, $ymax2) = unpack("C8", $xy); $top = $ymin2 * 256 + $ymin1; $left = $xmin2 * 256 + $xmin1; $right = $xmax2 * 256 + $xmax1; $bottom = $ymax2 * 256 + $ymax1; $width = sprintf("%dpt", $right - $left + 1); $height = sprintf("%dpt", $bottom - $top + 1); } } # WMF files: bytes 7-16 are Xmin,Ymin,Xmax,Ymax,units_per_inch # with low order byte 1st elsif ($ext eq 'wmf') { if (read(SDF_GRAPHIC, $junk, 6) && read(SDF_GRAPHIC, $xy, 10)) { ($xmin1, $xmin2, $ymin1, $ymin2, $xmax1, $xmax2, $ymax1, $ymax2, $upi1, $upi2) = unpack("C10", $xy); #print STDERR "$xmin1, $xmin2, $ymin1, $ymin2.\n"; #print STDERR "$xmax1, $xmax2, $ymax1, $ymax2.\n"; #print STDERR "$upi1, $upi2.\n"; $top = $ymin2 * 256 + $ymin1; $left = $xmin2 * 256 + $xmin1; $right = $xmax2 * 256 + $xmax1; $bottom = $ymax2 * 256 + $ymax1; $scale = ($upi2 * 256 + $upi1) / 72; #print STDERR "$top, $left, $right, $bottom, $scale.\n"; if ($top > 32768) { # Assume central origin (as output by Powerpoint) $width = sprintf("%dpt", $right * 2 / $scale); $height = sprintf("%dpt", $bottom * 2 / $scale); } else { $width = sprintf("%dpt", ($right - $left + 1) / $scale); $height = sprintf("%dpt", ($bottom - $top + 1) / $scale); } } } # BMP files: bytes 19-23 and 24-27 are width and height elsif ($ext eq 'bmp') { if (read(SDF_GRAPHIC, $junk, 18) && read(SDF_GRAPHIC, $wh, 8)) { ($w1, $w2, $w3, $w4, $h1, $h2, $h3, $h4) = unpack("C8", $wh); $width = sprintf("%dpt", $w3 * 256 + $w1); $height = sprintf("%dpt", $h3 * 256 + $h1); } } else { $width = 0; $height = 0; } # Close the file close(SDF_GRAPHIC); # Return result return ($width, $height); } # # >>Description:: # {{Y:SdfColPositions}} returns a list of column positions # given a total number of columns, a format attribute and # a right margin. # sub SdfColPositions { local($columns, $format, $margin) = @_; local(@result); local($assigned); local($known); local($col); local($guess); local($ratio); # Find out how many columns are known $assigned = 0; $known = 0; for $col (split(/,/, $format)) { if ($col =~ s/^([\d\.]+)\%$/\1/) { $assigned += $col; $known++; } else { $col = 0; } push(@result, $col); } # Divide the rest of the space, if necessary if ($known < $columns) { $guess = (100 - $assigned)/($columns - $known); for ($col = 0; $col < $columns; $col++) { $result[$col] = $guess if $result[$col] == 0; } } # Convert the percentages to positions for ($col = 1; $col < $columns; $col++) { $result[$col] += $result[$col - 1]; } $#result = $columns - 1; $ratio = $margin/100; for $col (@result) { $col = int ($col * $ratio + 0.5); } # Return result return @result; } # # >>Description:: # {{Y:SdfHeadingPrefix}} returns the prefix for the next heading. # {{type}} is H, A or P and {{level}} is the heading level. # sub SdfHeadingPrefix { local($type, $level) = @_; local($prefix); # For plain headings, we do nothing return '' if $type eq 'P'; # The counter arrays start from 0, so adjust the level accordingly $level--; # For chapter headings, we number things as 1, 1.1, 1.2, etc. if ($type eq 'H') { $_sdf_heading_counters[$level]++; $#_sdf_heading_counters = $level; return join('.', @_sdf_heading_counters) . ". "; } # For appendix headings, we number things as A, A.1, A.2, etc. elsif ($type eq 'A') { if ($level == 0 && scalar(@_sdf_appendix_counters) == 0) { $_sdf_appendix_counters[$level] = 'A'; } else { $_sdf_appendix_counters[$level]++; } $#_sdf_appendix_counters = $level; return join('.', @_sdf_appendix_counters) . ". "; } } ########## Post Processing User Routines ########## # switch to the user package package SDF_USER; # execute a system command sub SdfSystem { local($cmd) = @_; local($exit_code); &'AppMsg("object", "executing '$cmd'\n") if $'verbose >= 1; $exit_code = system($cmd); if ($exit_code) { $exit_code = $exit_code / 256; &'AppMsg("warning", "'$action' exit code was $exit_code from '$cmd'"); } return $exit_code; } # execute a system command quietly (i.e. only show output if an error # occurred on verbose mode was enabled) sub SdfQuietSystem { local($cmd) = @_; local($exit_code); # Save the output in a temporary file my $tmp_file = "/tmp/sdf$$"; $cmd .= " > $tmp_file"; $cmd .= " 2>&1" if $'NAME_OS eq 'unix'; # Execute the command $exit_code = &SdfSystem($cmd); # If verbose mode is on, or something went wrong, show the output if ($verbose || $exit_code) { unless (open(TMPFILE, $tmp_file)) { &'AppMsg("app_warning", "unable to open tmp file '$tmp_file'"); } else { print ; close(TMPFILE); } } unlink($tmp_file); return $exit_code; } # execute sdfbatch sub SdfBatch { local($flags) = @_; # local(); local($file, $cmd); local($tmp_file); # Check the file exists $file = "$long.$out_ext"; unless (-f $file) { &'AppMsg("error", "cannot execute sdfbatch on nonexistent file '$file'"); return; } # Build the default command ## xxx installscript resolution may be better done during build time #$cmd = "$Config::Config{installscript}/sdfbatch $flags $short.$out_ext"; # IGC 23/Feb/98: assume sdfbatch is on the path rather than in the # same place Perl is installed. &SdfQuietSystem("sdfbatch $flags $long.$out_ext"); } # execute htmldoc sub SdfHtmldoc { local($infile, $outfile) = @_; # local(); # Check the input file exists unless (-f $infile) { &'AppMsg("error", "cannot execute htmldoc on nonexistent file '$infile'"); return; } # Build up the flags using the document variables my $toc_level = $var{'DOC_TOC'}; my $flags = $toc_level ? "--toclevels $toc_level" : "--no-toc"; my $title = $var{'DOC_TITLE'}; $flags .= " --no-title" if $title eq ''; my $two_sides = $var{'DOC_TWO_SIDES'}; $flags .= " --duplex" if $two_sides; my $page_size = $var{'DOC_PAGE_WIDTH'} . 'x' . $var{'DOC_PAGE_HEIGHT'}; $flags .= " --size $page_size"; $flags .= " --left $var{'OPT_MARGIN_INNER'}"; $flags .= " --right $var{'OPT_MARGIN_OUTER'}"; $flags .= " --top $var{'OPT_MARGIN_TOP'}"; $flags .= " --bottom $var{'OPT_MARGIN_BOTTOM'}"; my $hf = &SdfHtmldocHFOpts(); $flags .= " $hf" if $hf; my $tuning = $var{'HTMLDOC_OPTS'}; $flags .= " $tuning" if $tuning; # Execute the command &SdfQuietSystem("htmldoc $flags -f $outfile $infile"); } # Build the header/footer options for HTMLDOC sub SdfHtmldocHFOpts { return ""; } # delete a file sub SdfDelete { local($file) = @_; # local(); if (-f $file) { &'AppMsg("object", "deleting '$file'") if $'verbose >= 1; unless (unlink($file)) { &'AppMsg("object", "delete of '$file' failed: $!"); } } } # delete a set of files after a book build sub SdfBookClean { local($ext) = @_; # local(); local(@files); local($_); local(@cannot); # Leave things alone if verbose mode is on or there is nothing to do return if $'verbose; return unless @'sdf_book_files; # If an extension is given, use that set of # files, rather than the known ones. @files = @'sdf_book_files; if ($ext ne '') { for $_ (@files) { $_ = &'NameSubExt($_, $ext); } } # Delete the files @cannot = grep(!unlink($_), @files); #if (@cannot) { # &'AppMsg("object", "unable to delete '@cannot'"); #} } # rename xx.out.ps to xx.ps if FrameMaker 5 is being used to # generate PostScript #### OBSOLETE - this is now done inside sdfbatch sub SdfRenamePS { local($xx) = @_; # local(); local($cmd); # Do nothing unless FrameMaker 5 is being used return unless $'sdf_fmext eq 'fm5'; # Wait until the print driver has finished &'AppMsg("object", "waiting for the print driver\n"); until (-f "$xx.$out_ext.ps") { sleep(1); print STDERR "."; } print STDERR "\n"; # Rename the file $cmd = "/bin/mv $xx.$out_ext.ps $xx.ps"; &SdfSystem($cmd); } # package return value 1; { while (($line = ) ne '') { if ($line =~ /^%%BoundingBox:\s+([\d\.]+)\s+([\d\.]+)\s+([\d\.]+)\s+([\d\.]+)/) { $width = sprintf("%dpt", $3 - $1 + 1); $height = sprintf("sdf-2.001/perllib/sdf/find.pl010075500042570001753000000056670672116102000156140ustar00iancmtr00000400000236########## Find Routines ########## use File::Find; # Global state used by find_dirs my $_find_dirs_base = ''; my $_find_dirs_file_rule = ''; my $_find_dirs_exclude_dir_rule = ''; my $_find_dirs_sep = ''; my @_find_dirs_found = (); my %_find_dirs_found = (); # File the set of sub-directories in a directory which satisfy the # matching rules. Names are returned relative to the base directory. # If a 4th argument is provided, that string is used to separate directory # names, otherwise the directory separator for the current OS is used. sub find_dirs { $_find_dirs_base = shift; my $file_rule = shift; $_find_dirs_exclude_dir_rule = shift; $_find_dirs_sep = shift || $NAME_DIR_SEP || '/'; $_find_dirs_file_rule = $file_rule eq '' ? '-f' : "-f && $file_rule"; @_find_dirs_found = (); %_find_dirs_found = (); find(\&_wanted_for_find_dirs, $_find_dirs_base); return @_find_dirs_found; } sub _wanted_for_find_dirs { local ($dir, $file); $dir = $File::Find::dir; if ($dir ne '' && $_find_dirs_exclude_dir_rule ne '') { $file = $_; my @parts = split(/\//, $dir); $_ = pop(@parts); if (eval $_find_dirs_exclude_dir_rule) { $File::Find::prune = 1; } # Make sure we restore $_ $_ = $file; return if $File::Find::prune; } if (eval $_find_dirs_file_rule) { return if $_find_dirs_found{$dir}; $_find_dirs_found{$dir}++; $dir = substr($dir, length($_find_dirs_base) + 1); $dir =~ s#/#$_find_dirs_sep#g; push(@_find_dirs_found, $dir); } } # Global state used by find_files my $_find_files_base = ''; my $_find_files_rule = ''; my $_find_files_exclude_dir_rule = ''; my @_find_files_found = (); # File the set of files in a single directory which # satisfy the nominated rule. Names are returned relative to the # base directory. sub find_files { $_find_files_base = shift; my $matching = shift; $_find_files_exclude_dir_rule = shift; $_find_files_rule = $matching ne '' ? "-f && $matching" : "-f"; @_find_files_found = (); find(\&_wanted_for_file_files, $_find_files_base); return @_find_files_found; } sub _wanted_for_file_files { local ($dir, $file); $dir = $File::Find::dir; if ($dir ne '' && $_find_files_exclude_dir_rule ne '') { $file = $_; my @parts = split(/\//, $dir); $_ = pop(@parts); if (eval $_find_files_exclude_dir_rule) { $File::Find::prune = 1; } # Make sure we restore $_ $_ = $file; return if $File::Find::prune; } if (eval $_find_files_rule) { my $name = $File::Find::name; $name = substr($name, length($_find_files_base) + 1); $name =~ s#/#$NAME_DIR_SEP#g if $NAME_OS ne 'unix'; push(@_find_files_found, $name); } } # package return value 1; sdf-2.001/perllib/sdf/podmacs.pl010064400042570001753000000142020661420514000163030ustar00iancmtr00000400000236# $Id$ $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: POD Macros Library # # >>Copyright:: # Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 17-Jun-97 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # This library provides the built-in macros (implemented in [[Perl]]) for # compatibility with POD. # # >>Description:: # # >>Limitations:: # # Switch to the user package package SDF_USER; ##### Constants ##### ##### Variables ##### # This contains the first item in each list @_pod_item = (); # This contains the indent (i.e. N within "over N") of each list @_pod_over = (); # This contains the style for each list @_pod_style = (); ##### Initialisation ##### # # >>Description:: # {{Y:InitPodMacros}} initialises the global variables in this module. # sub InitPodMacros { # local() = @_; # local(); @_pod_item = (); @_pod_over = (); @_pod_style = (); } ##### Support Routines ##### ##### General Macros ##### # head1 - level 1 heading @_head1_MacroArgs = ( 'Name Type Default Rule', 'text rest _NULL_', ); sub head1_Macro { local(%arg) = @_; local(@text); # Return result return ("H1:$arg{'text'}"); } # head2 - level 2 heading @_head2_MacroArgs = ( 'Name Type Default Rule', 'text rest _NULL_', ); sub head2_Macro { local(%arg) = @_; local(@text); # Return result return ("H2:$arg{'text'}"); } # head3 - level 3 heading @_head3_MacroArgs = ( 'Name Type Default Rule', 'text rest _NULL_', ); sub head3_Macro { local(%arg) = @_; local(@text); # Return result return ("H3:$arg{'text'}"); } # head4 - level 4 heading @_head4_MacroArgs = ( 'Name Type Default Rule', 'text rest _NULL_', ); sub head4_Macro { local(%arg) = @_; local(@text); # Return result return ("H4:$arg{'text'}"); } # head5 - level 5 heading @_head5_MacroArgs = ( 'Name Type Default Rule', 'text rest _NULL_', ); sub head5_Macro { local(%arg) = @_; local(@text); # Return result return ("H5:$arg{'text'}"); } # head6 - level 6 heading @_head6_MacroArgs = ( 'Name Type Default Rule', 'text rest _NULL_', ); sub head6_Macro { local(%arg) = @_; local(@text); # Return result return ("H6:$arg{'text'}"); } # over - begin a list @_over_MacroArgs = ( 'Name Type Default Rule', 'N integer 4', ); sub over_Macro { local(%arg) = @_; local(@text); # If this is the first level, switch on some special processing @text = (); if (scalar(@_pod_style) == 0) { # Indent examples using the level information push(@text, '!on paragraph \'E\'; POD_LIST_E; $attr{"in"} = scalar(@_pod_style)'); # Set up the rule for paragraphs within a list push(@text, '!on paragraph \'N\'; POD_LIST_N; ' . '$style = $_pod_style[$#_pod_style]; ' . '$_pod_style[$#_pod_style] = "L" . scalar(@_pod_style)'); } # Update the state push(@_pod_item, ''); push(@_pod_over, $arg{'N'}); push(@_pod_style, ''); # Return result return @text; } # item - list item @_item_MacroArgs = ( 'Name Type Default Rule', 'text rest _NULL_', ); sub item_Macro { local(%arg) = @_; local(@text); # If an over hasn't been found, assume one @text = &over_Macro('N', 4) if scalar(@_pod_over) == 0; # Get the level my $level = scalar(@_pod_style); # If this is the first item, decide how to format the list unless ($_pod_item[$#_pod_item]) { $_pod_item[$#_pod_item] = $arg{'text'}; } # Handle bulleted lists if ($_pod_item[$#_pod_item] eq '*') { $_pod_style[$#_pod_style] = "LU$level"; } # Handle ordered lists elsif ($_pod_item[$#_pod_item] eq '1.') { $_pod_style[$#_pod_style] = $arg{'text'} eq '1.' ? "LF$level" : "LN$level"; } # Handle enumerated lists else { $_pod_style[$#_pod_style] = "L$level"; push(@text, "LI$level:$arg{'text'}"); } # Return result return @text; } # back - end a list @_back_MacroArgs = (); sub back_Macro { local(%arg) = @_; local(@result); # Update the state pop(@_pod_item); pop(@_pod_over); pop(@_pod_style); # If this terminates the first level, switch off the special processing @result = (); if (scalar @_pod_style == 0) { @result = ( '!off paragraph POD_LIST_N', '!off paragraph POD_LIST_E'); } # Return result return @result; } # cut - ignore file until next = at start of line @_cut_MacroArgs = (); sub cut_Macro { local(%arg) = @_; local(@text); # Update the parser state $'sdf_cutting = 1; # Return result return (); } # pod - begin some POD @_pod_MacroArgs = (); sub pod_Macro { local(%arg) = @_; # Return result - nothing return (); } # for - paragraph is for format X only @_for_MacroArgs = ( 'Name Type Default Rule', 'format symbol', 'text rest _NULL_', ); sub for_Macro { local(%arg) = @_; local(@text); # Return result #return (&SdfJoin("__inline", $arg{'text'}, 'target', $arg{'format'})); return ( "!block inline; target='$arg{'format'}'", $arg{'text'}, '!endblock'); } # begin - begin paragraphs for format X only @_begin_MacroArgs = ( 'Name Type Default Rule', 'format symbol', ); sub begin_Macro { local(%arg) = @_; local(@text); # Return result return (); } # end - end paragraphs for format X @_end_MacroArgs = ( 'Name Type Default Rule', 'format symbol', ); sub end_Macro { local(%arg) = @_; local(@text); # Return result return (); } # package return value 1;{'text'}"); } # over - begin a list @_over_MacroArgs = ( 'Name Type Default Rule', 'N integer 4', ); sub over_Macro { local(%arg) = @_; local(@text); # If this is the first level, switch on some special processing @text = (); if (scalar(@_pod_style) == 0) { # Indent examples using the level information psdf-2.001/perllib/sdf/tests.pl010064400042570001753000000325070661420514000160270ustar00iancmtr00000400000236# $Id$ $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: Test Framework Library # # >>Copyright:: # Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 17-Mar-97 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # This library provides a general framework # for running regression tests. # # >>Description:: # # >>Limitations:: # This really should be ported to a Perl5 module, asap. :-( # # The way of executing a test needs to be configurable, e.g. # a command might be a block of Perl code rather than a system command. # Furthermore, the result code returned from system and/or its # equivalent should be made available for checking. # # Each test needs to support optional initialisation and finalisation # routines. These could be placed in an optional file called run.pl, say. # The routines would be useful for things like: # # * deleting unwanted files # * initialising data structures (when executing Perl routines) # * checking that no existing files were changed # * checking that additional files were not generated. # !require "ctime.pl"; ######### Constants ######### # # >>Description:: # {{TESTS_DEFAULT_LOG}} is the default log file. # $TESTS_DEFAULT_LOG = 'runtests.log'; # Usage message @_TESTS_USAGE = ( "runtests - output usage", "runtests all - run all tests", "runtests test1 ... - run the nominated testcases", ); ######### Variables ######### # Starting time for tests # (This is initialised after the log file is opened) $_Tests_Start = 0; # Counter to ensure log streams are unique $_Tests_Cntr = 0; # Collected stats on test counts, cases and failures %_Tests_Count = (); %_Tests_Cases = (); %_Tests_Fails = (); # # >>Description:: # {{Y:Tests}} defines the set of available tests and the command # to run for each test. # %Tests = (); # # >>Description:: # {{Y:Tests_Verify_Fn}} defines the function used to verify that # each test succeeded. The function interface is: # # = $failures = &$verify_fn($test) # $Tests_Verify_Fn = 'verify_files'; # # # >>Description:: # The following variables are initialised by {{Y:tests_init}}: # # * {{@Tests_Order}} - the list of tests to run # * {{$Tests_Group}} - the name of this group of tests # * {{$Tests_Strm}} - the stream to output diagnostics to # * {{$Tests_Verbose}} - diagnostics level. # @Tests_Order = (); $Tests_Group = ''; $Tests_Strm = ''; $Tests_Verbose = 0; $Tests_Web = 0; $Tests_No_Logging = 0; ######### Routines ######### # # >>Description:: # sub runtests { # local() = @_; # local(); &_tests_init() || &_tests_exit(); &_tests_run(); &_tests_report(); &_tests_exit(); } # # >>Description:: # {{Y:addtests}} adds a set of tests. # {{%tests}} contains the mapping of names to commands. # sub addtests { local(%tests) = @_; # local(); %Tests = %tests; } # # >>Description:: # {{Y:gentests}} builds a set of tests from a rule and list of names. # {{rule}} contains a %s to indicate where the test name goes in the command. # sub gentests { local($rule, @names) = @_; # local(); local($test); for $test (@names) { $Tests{$test} = sprintf($rule, $test); } } # # >>Description:: # sub nestedtests { # local() = @_; # local(); local($opts); local($dir, $file); local($test); # Get the options as we need them to build the nested tests &_tests_get_options(); $opts = ""; $opts .= " -v$Tests_Verbose" if $Tests_Verbose; $opts .= " -w" if $Tests_Html; # Change the verify function $Tests_Verify_Fn = 'verify_logs'; # Get the nested tests for $test (<*/runtests>) { ($dir, $file) = split(/\//, $test); $Tests{$dir} = "cd $dir;./$file -g$Tests_Group$dir$opts all;cd .."; } } # # >>Description:: # {{Y:tests_msg}} outputs a diagnostics message. # All diagnostics are output to the current logging stream. # If {level}} is greater than {{Tests_Verbose}}, # the message is {{not}} echoed on standard error. # sub tests_msg { local($msg, $level) = @_; # local(); print STDERR "$msg\n" if $level <= $Tests_Verbose; print $Tests_Strm "$msg\n" unless $Tests_No_Logging; } # # >>_Description:: # {{Y:_tests_get_options}} processes command line options. # sub _tests_get_options { # local() = @_; # local(); local($opt, $param); while ($ARGV[0] =~ /^\-(\w)/) { $opt = $1; $param = $'; shift(@ARGV); # Get the diagnostics level, if any if ($opt eq 'v') { $Tests_Verbose = $param eq '' ? 1 : $param; } # Get the group name, if any if ($opt eq 'g') { $Tests_Group = "$param:"; } # Get the other options if ($opt eq 'n') { $Tests_No_Logging = 1; } if ($opt eq 'w') { $Tests_Web = 1; } } } # # >>_Description:: # {{Y:_tests_init}} processes the command line and # initialises the test variables. # sub _tests_init { # local() = @_; local($ok); local($log_file); local($pwd); local($now); # Get the options &_tests_get_options(); # Check the command line unless (@ARGV) { printf "usage is:\n%s\n", join("\n", @_TESTS_USAGE); return 0; } # Open the diagnostics stream, if any $Tests_Strm = "TESTS" . $_Tests_Cntr++; $log_file = $TESTS_DEFAULT_LOG; if ($Tests_No_Logging) { # do nothing } else { # Save the existing log file, if a logs directory exists if (-f $log_file) { # TO BE COMPLETED } # open the log file unless (open($Tests_Strm, ">$log_file")) { print STDERR "fatal: unable to open log file '$log_file':$!"; return 0; } } # Get the list of tests to run if ($ARGV[0] eq 'all') { @Tests_Order = sort keys %Tests; } else { @Tests_Order = @ARGV; } # Output some diagnostics $_Tests_Start = time; $now = &ctime($_Tests_Start); chop($now); &tests_msg("start time: $now", 2); # Return result return 1; } # # >>_Description:: # {{Y:_tests_run}} runs the list of tests named in {{@Tests_Order}}. # sub _tests_run { # local(); # local(); local($verify_fn); local($test, $cmd); local($test_count); local($case_count); # Get the verify function $verify_fn = $Tests_Verify_Fn; # Output some diagnostics &tests_msg(sprintf("about to run: %s", join(" ", @Tests_Order)), 2); &tests_msg("verify function: $verify_fn", 2); # Check the verify function exists unless (defined &$verify_fn) { &tests_msg("verify function '$verify_fn' not defined"); } # Run the requested tests for $test (@Tests_Order) { $ARGV = $test; $cmd = $Tests{$test}; if ($cmd) { &tests_msg("running $test: command is '$cmd'", 2); system($cmd); } else { &tests_msg("unknown test '$test'"); $_Tests_Count{$test}++; $_Tests_Cases{$test}++; $_Tests_Fails{$test}++; next; } # Verify the outputs $case_count = 1; $test_count = 1; if (defined &$verify_fn) { $_Tests_Fails{$test} += &$verify_fn($test, *case_count, *test_count); } else { $_Tests_Fails{$test}++; } $_Tests_Count{$test} += $test_count; $_Tests_Cases{$test} += $case_count; } } # # >>_Description:: # {{Y:_tests_report}} outputs a report summarising a set of tests. # The total number of failures is returned. # sub _tests_report { # local() = @_; local($total); local($test); local($test_total, $fail_total, $case_total); local($test_count, $fail_count, $case_count); local($s_tests, $s_fails, $s_cases); local($summary); local($group); local($minutes, $seconds); local($s_minutes, $s_seconds); # Report the problem counts $test_total = 0; $fail_total = 0; $case_total = 0; for $test (sort keys %_Tests_Fails) { $test_count = $_Tests_Count{$test}; $fail_count = $_Tests_Fails{$test}; $case_count = $_Tests_Cases{$test}; $test_total += $test_count; $fail_total += $fail_count; $case_total += $case_count; if ($Tests_Verbose || $fail_count > 0) { $s_fails = $fail_count == 1 ? 'failure' : 'failures'; $s_cases = $case_count == 1 ? 'test case' : 'test cases'; &tests_msg("$fail_count $s_fails in $case_count $s_cases in $Tests_Group$test"); } } # Summarise the results $s_tests = $test_total == 1 ? 'test' : 'tests'; $s_fails = $fail_total == 1 ? 'failure' : 'failures'; $s_cases = $case_total == 1 ? 'test case' : 'test cases'; $summary = "$test_total $s_tests, $case_total $s_cases, $fail_total $s_fails"; if ($Tests_Group ne '') { $group = $Tests_Group; $group =~ s/:$//; $summary .= " in $group"; } if ($_Tests_Start) { $seconds = time - $_Tests_Start; $minutes = int($seconds / 60); $seconds = $seconds % 60; $s_minutes = $minutes == 1 ? 'minute' : 'minutes'; $s_seconds = $seconds == 1 ? 'second' : 'seconds'; $summary .= " ($minutes $s_minutes, $seconds $s_seconds)"; } &tests_msg("summary: $summary"); # Return result return $total; } # # >>_Description:: # {{Y:_tests_exit}} exits the current application. # sub _tests_exit { # local() = @_; # local(); # Publish the log file on the web, if requested if ($Tests_Web && $Tests_Start) { close($Tests_Strm) unless $Tests_No_Logging; system("sdf -2html -pruntests $TESTS_DEFAULT_LOG"); } # Exit the program exit(0); } # # >>Description:: # {{Y:verify_files}} is a predefined verify function. # Each test is expected to have a directory called {{test}}.ok # which contains the expected set of output files. # Files which verify ok are deleted. If possible, the other files # are moved into a directory called {{test}}.bad. Otherwise, # the files are left where they are. # sub verify_files { local($test, *case_count, *test_count) = @_; local($fail_count); local($ok_dir, $bad_dir); local(@ok_files, $ok_file, $ok); # Check the ok directory exists $ok_dir = "$test.ok"; if (! -d $ok_dir) { &tests_msg("unable to find ok directory '$ok_dir'"); return 1; } # Check the bad directory exists $bad_dir = "$test.bad"; if (! -d $bad_dir) { mkdir($bad_dir, 0755) || &tests_msg("unable to find or create bad directory '$bad_dir': $!"); } # Check the files in the directory are ok $fail_count = 0; $case_count = 0; if ($ok_dir) { @ok_files = grep(s/$ok_dir\///, <$ok_dir/*>); for $ok_file (@ok_files) { $ok = &_tests_verify_file($ok_file, "$ok_dir/$ok_file", "$bad_dir/$ok_file", "$Tests_Group$test"); $fail_count++ unless $ok; $case_count++; } } # Return result return $fail_count; } # # >>_Description:: # {{Y:_tests_verify_file}} compares a test file against a checked file. # If the file does not match, it is renamed to {{bad_file}}. # sub _tests_verify_file { local($test_file, $check_file, $bad_file, $test_id) = @_; local($ok); local($test_data, $check_data); # Get the data from the test file unless (open(TESTFILE, $test_file)) { &tests_msg("unable to open test file '$test_file' for verification: $!"); return 0; } $test_data = join('', ); close TESTFILE; # Get the data from the check file unless (open(CHECKFILE, $check_file)) { &tests_msg("unable to open ok file '$check_file' for verification: $!"); return 0; } $check_data = join('', ); close CHECKFILE; # Compare the data if ($test_data eq $check_data) { &tests_msg("ok $test_file in $test_id", 1); unlink $test_file || &tests_msg("unable to delete '$test_file'"); return 1; } else { &tests_msg("not ok $test_file in $test_id"); rename($test_file, $bad_file) || &tests_msg("unable to rename '$test_file' to '$bad_file': $!"); return 0; } } # # >>Description:: # {{Y:verify_logs}} is a predefined verify function. # Each test is expected to be a nested test group, i.e. # each test has a directory to itself and the results of the # test run are expected to be output to a log file. # sub verify_logs { local($test, *case_count, *test_count) = @_; local($fail_count); local($log_file); # Open the log file $log_file = "$test/" . $TESTS_DEFAULT_LOG; unless (open(LOGFILE, $log_file)) { &tests_msg("unable to open test log file '$log_file': $!"); return 1; } # Get the results of the most recent run while ($line = ) { chop($line); if ($line =~ /^summary: (\d+) tests?, (\d+) test cases?, (\d+) failures?/) { $test_count = $1; $case_count = $2; $fail_count = $3; } } close(LOGFILE); # Return result return $fail_count; } # package return value 1; sdf-2.001/perllib/sdf/sdfget.pl010064400042570001753000000122650661420514000161400ustar00iancmtr00000400000236# $Id$ $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: SDFGET Support Library # # >>Copyright:: # Copyright (c) 1992-1997, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 04-Oct-97 ianc Fixed bug with * in reports # 10-Jul-97 marks Initial writing # ----------------------------------------------------------------------- # # >>Purpose:: # This library provides support for document extraction via # {{CMD:sdfget}}. # # >>Description:: # # This module is a collection of subroutines that are used for the # processsing of special {{CMD:sdfget}} directives. # # >>Note:: # These directives are quite distinct and separate from{{CMD:sdf}} # directives. # # # >>!use Package; scope=PUBLIC # >>Name:: # Sdfget # # >>Description:: # The {{B:Sdfget}} package describes the interface to the data # structures used in the extraction, storage and regeneration of # embedded documentation within source code. # package Sdfget; # constants for the Sdfget package %_ScopeList = ( 'PUBLIC', 1, 'PROTECTED', 2, 'PRIVATE', 3 ); # >>!use Methods.new # >>Name:: # new # # >>Synopsis:: # create an instance of the {{B:Sdfget}} class # # >>Description:: # {{Y:new}} creates an instance of the {{B:Sdfget}} class. # # >>Return Values:: # returns a reference to the created {{B:Sdfget}} instance # sub new { my $class = shift; my $this = {}; bless $this; } # >>!use Methods.addText # >>Name:: # addText # # >>Parameters:: # {{B:$section}} - the section this text belongs to # # {{B:@buffers}} - the list of buffers to which this key will apply # # >>Description:: # sub addText { my ($this, $section, $textref, @buflist) = @_; my ($bufname, $bufref, $docref); for $bufname (@buflist) { if (!defined ($$this{$bufname})) { $$this{$bufname} = new Sdfbuffer; } $bufref = $$this{$bufname}; $bufref->Sdfbuffer::addText($section, @$textref); } } sub getScope { my ($this, $scope) = @_; return $_ScopeList{$scope}; } sub getKeysDocs { my ($this, $bufname) = @_; my $bufref; $bufref = $$this{$bufname}; return $$bufref{'key'}, $$bufref{'doc'}; } sub printDict { my $this = shift; my $buf; my $bufref; for $buf (keys %$this) { print "Buffer: $buf..."; $bufref = $$this{$buf}; $bufref->Sdfbuffer::printBuffer(); } } # # >>!use main # # >>Description:: # {{Y:UseArgs}} extracts the buffer names and the documentation # scope from the {{E:!use}} directive line. # # >>Parameter:: # {{B:$directive}} - the directive line to be parsed # # >>Return Values:: # {{B:$doc_scope}} - the scope to which this documentation segment is # applicable. # # {{B:@buffers}} - array of buffer names to which the documentation # can be applied. # sub UseArgs { local($directive) = @_; # the directive line being parsed local ($bufpart, $scopepart); local(@buffers) = (); local($buffers) = ''; local($doc_scope) = 0; ($bufpart, $scopepart) = split (/;/, $directive); $bufpart =~ /^.*!use (.+)$/; $buffers = $1; @buffers = split(/,/, $buffers); if ($directive =~ /scope=(.+)$/){ $doc_scope = $_ScopeList{$1}; } else { $doc_scope = $_ScopeList{'PUBLIC'}; } return ($doc_scope, @buffers); } # >>!use NextSection # >>Description:: # {{Y:NextSection}} consume lines from the input stream up to # the next {{E:"!use ..."}} entry. When found, parse the line # returning any found scope and buffer names. Otherwise return a Null # scope string and an empty buffer name list. # sub NextSection { local($this, $istream) = @_; # the input stream local($key); while (<$istream>) { if (/^!use (.+)/) { return &UseArgs($_); } } # nothing found so return the set of the Null string # and an empty array return 0, (); } # >>!use main # >>Description:: # {{Y:TrimDesc}} trims the newline characters from each description # field in the buffers list # sub TrimDesc { my ($this) = @_; my ($bufref, $buffer); for $buffer (keys %$this) { $bufref = $$this{$buffer}; $bufref->Sdfbuffer::TrimDesc (); } } #### new package ##### package Sdfbuffer; ##### constants ##### $KeyIndex = 0; $HashIndex = 1; sub new { my $class = shift; my $this = {}; bless $this; } sub addText { my ($this, $section, @desc) = @_; # If this is the first time this key has occurred, # append it to the "order found" list. if (!defined $this->{'doc'}{$section}) { push (@{ $this->{'key'} }, $section); } $this->{'doc'}{$section} .= join ('', @desc); } sub TrimDesc { my ($this) = @_; my ($docref, $section, $ch); $docref = $$this{'doc'}; for $section (keys %$docref) { do { $ch = chop($$docref{$section}); } while $ch eq "\n"; $$docref{$section} .= $ch; } } sub printBuffer { my $this = shift; my $lkey; my $keys = $$this{'key'}; my $doc; for $lkey (@$keys){ print "lkey: $lkey "; } print "\n"; print "Documentation...\n"; $doc = $$this{'doc'}; for $lkey (keys %$doc) { print "lkey: $lkey\n$$doc{$lkey}\n"; } } # package return value 1; sdf-2.001/perllib/sdf/name.pl010064400042570001753000000251050661474331000156070ustar00iancmtr00000400000236# $Id$ $VERSION{''.__FILE__} = '$Revision$'; # # >>Title:: Name Processing Library # # >>Copyright:: # Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com). # You may distribute under the terms specified in the LICENSE file. # # >>History:: # ----------------------------------------------------------------------- # Date Who Change # 29-Feb-96 ianc SDF 2.000 # ----------------------------------------------------------------------- # # >>Purpose:: # This library provides support for file-name processing. # With careful use, the routines provide portability across # [[Unix]]-like and [[Windows]]-like file-naming systems. # # >>Description:: # # >>Limitations:: # # >>Resources:: # # >>Implementation:: # ######### Constants ######### # # >>Description:: # {{Y:NAME_OS}} returns the current operating system style, either # {{unix}} or {{dos}}. {{Y:NAME_DIR_TABLE}} and {{Y:NAME_PATH_TABLE}} # are lookup tables of directory and path separators for different # operating system styles. {{Y:NAME_DIR_SEP}} and {{Y:NAME_PATH_SEP}} # are the respective separators for {{NAME_OS}}. # $NAME_OS = $ENV{'COMSPEC'} ? 'dos' : 'unix'; $NAME_OS = 'mac' if $^O =~ /Mac/; %NAME_DIR_TABLE = ( 'unix', '/', 'dos', '\\', 'mac', ':', ); %NAME_PATH_TABLE = ( 'unix', ':', 'dos', ';', 'mac', ';', ); $NAME_DIR_SEP = $NAME_DIR_TABLE{$NAME_OS}; $NAME_PATH_SEP = $NAME_PATH_TABLE{$NAME_OS}; ######### Variables ######### # Lookup tables of conversion rules built by NameLoadConversionRules() %_name_conversion_sources = (); %_name_conversion_actions = (); ######### Routines ######### # # >>Description:: # {{Y:NameOS}} returns the SDF version of the OS name. # sub NameOS { return $NAME_OS; } # # >>Description:: # {{Y:NameIsAbsolute}} returns 1 if the name is in absolute (or # non-relative) format. # sub NameIsAbsolute { local($name) = @_; local($result); SWITCH: { $result = $name =~ m#^\/#, last SWITCH if $NAME_OS eq 'unix'; $result = $name =~ m#^([A-Za-z]:)?[\\/]#, last SWITCH if $NAME_OS eq 'dos'; $result = $name =~ m#^[^:]+:#, last SWITCH if $NAME_OS eq 'mac'; die "Unknown OS: $NAME_OS"; } return $result; } # # >>Description:: # {{Y:NameAbsolute}} returns the absolute name for a file. # sub NameAbsolute { local($name) = @_; local($result); local($pwd); # If already absolute, do nothing return $name if &NameIsAbsolute($name); # Get & prepend the current directory $pwd = $NAME_OS eq 'unix' || $NAME_OS eq 'mac' ? `pwd` : `cd`; chop($pwd); return &NameJoin($pwd, $name); } # # >>Description:: # {{Y:NameFind}} searches the directories for a file with the name # given. If found, the combined name (directory + local name) is returned. # If the name is absolute, the file is checked to exist. i.e. the directories # are not searched. # In either case, if the file is not found, an empty string is returned. # sub NameFind { local($name, @dirs) = @_; local($found_name); local($dir, $full); # handle "-": return itself return $name if $name eq "-"; # handle absolute filenames if (&NameIsAbsolute($name)) { if (-r $name) { return $name; } else { return ""; } } $DB::single = 1; if($NAME_OS eq 'mac') { $name =~ s#/#:#g ; $name =~ s#^:##; } # Otherwise, search for the name foreach $dir (@dirs) { if ($NAME_OS eq 'mac') { $dir = "" if $dir eq '.'; $dir =~ s#/#:#g; $dir =~ s#:$##; } if ($dir eq $NAME_DIR_SEP) { $full = $dir . $name; } else { $full = $dir . $NAME_DIR_SEP . $name; } if (-r $full) { return $full; } } # If we reach here, we had no luck return ""; } # # >>Description:: # {{Y:NameSplit}} extracts components from a name. # {{short}} is the name without the directory. # sub NameSplit { local($name) = @_; local($dir, $base, $ext, $short); # Ensure unix style $base = $name; $base =~ s#\\#/#g if $NAME_OS eq "dos"; $base =~ s#\:#/#g if $NAME_OS eq "mac"; # get directory and base.ext if ($base =~ m#/([^/]+)$#) { $dir = $`; $base = $1; } # get extension if ($base =~ m#\.([^\.]+)$#) { $base = $`; $ext = $1; } # Return result $dir =~ s#\/#:#g if $NAME_OS eq "mac"; $short = &NameJoin("", $base, $ext); return ($dir, $base, $ext, $short); } # # >>Description:: # {{Y:NamePathComponentSplit}} completely splits a path into its component parts. # Returns a list of the parts. # sub NamePathComponentSplit { my $sep; my $path = shift @_; $sep = '/'; $sep = '\\' if $NAME_OS eq 'dos'; $sep = ':' if $NAME_OS eq 'mac'; return split $sep, $path; } # # >>Description:: # {{Y:NameJoin}} builds a name from its components. If the base name is # already absolute, the directory is not prepended. # sub NameJoin { local($dir, $base, $ext) = @_; local($name); # handle "-": return itself $name = $base; return $name if $name eq "-"; # prepend directory if present and name is not already absolute if ($dir && ! &NameIsAbsolute($name)) { $name = $dir . $NAME_DIR_SEP . $name; } # append extension, if any $name .= ".$ext" if $ext; return $name; } # # >>Description:: # {{Y:NameSubExt}} substitutes the extension on a name. # sub NameSubExt { local($name, $new_ext) = @_; local($new_name); local($dir, $base, $ext); ($dir, $base, $ext) = &NameSplit($name); return &NameJoin($dir, $base, $new_ext); } # # >>Description:: # {{Y:NameLoadConversionRules}} loads a table of conversion rules to # be used by {{Y:NameFindOrGenerate}}. The fields in {{@table}} are: # # * {{Context}} - the driver for which this conversion applies # * {{To}} - the destination figure format # * {{From}} - the original figure format # * {{Action}} - the command to use to do the conversion. # # Rules do not chain, so defining rules for A->B and B->C do not # imply that A will be converted to C. If {{validate}} is set, # the table is validated. # # sub NameLoadConversionRules { local(*table, $validate) = @_; # local(); # Validate the table &TableValidate(*table, *_SDF_CONVERSION_RULES) if $validate; # Load the rules local @flds; my $rec; my %values; my $context; my $to; my $from; my $action; @flds = &TableFields(shift(@table)); for $rec (@table) { %values = &TableRecSplit(*flds, $rec); $context = $values{'Context'}; $to = $values{'To'}; $from = $values{'From'}; $action = $values{'Action'}; push(@{$_name_conversion_sources{$context,$to}}, $from); $_name_conversion_actions{$context,$from,$to} = $action; } ## Dump the table, if debugging #for $igc (sort keys %_name_conversion_sources) { # $aref = $_name_conversion_sources{$igc}; # print "$igc: "; # for $igc2 (@$aref) { # print " $igc2"; # } # print "\n"; #} } # # >>Description:: # {{Y:NameFindOrGenerate}} searches a list of directories for a file # with one of the list of extensions. The extensions are searched # for in the order given. If {{NameLoadConversionRules}} has been # called, this routine will attempt to generate a file in the current # directory using the nominated {{context}}, if any. If a file was found # or generated, the combined name (directory + local name) is returned. # If the name is absolute, the file is checked to exist. i.e. the directories # are not searched. # In either case, if the file is not found, an empty string is returned. # sub NameFindOrGenerate { local($name, $dir_list_ref, $ext_list_ref, $context) = @_; local($full); local($dir); # handle "-": return itself return $name if $name eq "-"; # handle absolute filenames if (&NameIsAbsolute($name)) { if (-r $name) { return $name; } else { return ""; } } # Otherwise, search for the name foreach $dir (@$dir_list_ref) { $dir =~ s#/#:#g if $NAME_OS eq 'mac'; $dir = "" if $dir eq '.' && $NAME_OS eq 'mac'; $full = &NameFindInDirectory($dir, $name, $ext_list_ref, $context); return $full if $full ne ''; } # If we reach here, we had no luck return ""; } # # >>Description:: # {{Y:NameFindInDirectory}} attempts to find a file directory {{dir}} # using {{base}} and the set of extensions given by {{$ext_list_ref}}. # For each base.ext combination, if it doesn't find that file, # it tries to generate a file of that name in the current # directory using: # # * the conversion rules loaded by {{Y:NameLoadConversionRules}} # * the files called {{base.*}} in the {{dir}} directory # * the {{context}} # # If the file is found or generated, its name is returned, # otherwise an empty string is returned. # # Note: If the base already has an extension, the extension list isn't used. # sub NameFindInDirectory { local($dir, $base, $ext_list_ref, $context) = @_; local($full); # If the base already has an extension, don't use the extension list my $ext = (&'NameSplit($base))[2]; my @exts = $ext ne '' ? ($ext) : @$ext_list_ref; $base = &NameSubExt($base, '') if $ext ne ''; # Find/generate the file my %rules = %{$_name_conversions{$context}}; my $i; for ($i = 0; $i <= $#exts; $i++) { $ext = $exts[$i]; $full = &NameJoin($dir, $base, $ext); return $full if -r $full; # Try generating the file my $source_ext; my $action; my $source; my $dest; for $source_ext (@{$_name_conversion_sources{$context,$ext}}) { $action = $_name_conversion_actions{$context,$source_ext,$ext}; $source = &NameJoin($dir, $base, $source_ext); if (-r $source) { $dest = &NameJoin('.', $base, $ext); # Do parameter substitution on the action my $cmd = eval '"' . $action . '"'; if ($@) { &AppMsg('warning', "error in conversion action '$action': $@"); next; } # Generate the file and check it exists my $exit_code = system($cmd); if ($exit_code) { &AppMsg('warning', "error in conversion from '$source' to '$dest': $@"); } return $dest if -r $dest; } } } # If we reach here, we had no luck return ""; } # package return value 1; AME_OS eq "dos"; $base =~ s#\:#/#g if $NAME_OS eq "mac"; # get directory and base.ext if ($base =~ m#/([^/]+)$#) { $dir = $`; $base = $1; } # get extension if ($base =~ m#\.([^\.]+)$#) { $base = $`; $ext = $1; } # Return result $dir =~ s#\/#:#g if $NAME_OS eq "mac"; $short = &NameJoin("", $base, $ext); return ($dir, $base, $ext, $short); } # # >>Description:: #sdf-2.001/perllib/Pod/004075500042570001753000000000000672243771400143105ustar00iancmtr00000400000236sdf-2.001/perllib/Pod/Diff.pm010064400042570001753000000163130635614036200155100ustar00iancmtr00000400000236package Pod::Diff; use Exporter; @ISA = qw(Exporter); @EXPORT = qw(pod_diff_files pod_diff_print_stats); use strict; # Set this for strict checking, i.e.: # * over commands must match # * multiple spaces within non-verbatim paragraphs must match my $strict = 0; # Statistics collected my $total_runs = 0; my $total_paras = 0; my $total_diffs = 0; my $total_resync_fails = 0; # The default formatting routine for a difference sub _pod_diff_fmt { my($i, $text1, $text2, $line1, $line2) = @_; # Find the first character which differs # Is there a better way than this? my $first = 0; $first++ while substr($text1, $first, 1) eq substr($text2, $first, 1); $first++; return join("\n", "*** paragraph $i - character $first ***", "--- $line1 ---", $text1, "--- $line2 ---", $text2); } # Parse a pod array into a list of paragraphs. # Each paragraph has the following fields: # # * TEXT - the paragraph text # * LINE - the starting line number sub _pod_parse_paras { my($array) = @_; my(@list); my $lineno = 0; my $text = ''; my $tab_size = 8; my $line; for $line (@$array) { $lineno++; # Trim trailing whitespace and convert tabs to spaces $line =~ s/\s+$//; 1 while $line =~ s/\t+/' ' x (length($&) * $tab_size - length($`) % $tab_size)/e; # Build and store the paragraphs if ($line =~ /^$/) { if ($text ne '') { push(@list, {TEXT => $text, LINE => $lineno}); $text = ''; } } elsif ($text eq '') { $text = $line; } else { if ($text =~ /^\s/) { $text .= "\n$line"; } else { $text .= " $line"; } } } # Save the last paragraph, if necessary if ($text ne '') { push(@list, {TEXT => $text, LINE => $lineno}); } # Return result return @list; } # Remove redundant escapes from a paragraph sub _fix_escapes { my($text) = @_; # For verbatim, leave things alone return $text if $text =~ /^ /; my $result = ''; my $phrase = ''; my @nested = (); my $tag = ''; while ($text ne '') { # A > without a proceeding < may be a sequence end marker if ($text =~ /^([^<>]*)\>/) { $text = $'; if (@nested) { $tag = pop(@nested); $phrase = $1; if ($tag eq 'E' && ($phrase eq 'gt' || $phrase eq 'lt')) { # The escape isn't necessary unless: # * the preceding character is [A-Z] for <, or # * it's inside an interior sequence for >, or if ($phrase eq 'gt' && scalar @nested > 0 || $phrase eq 'lt' && $result =~ /[A-Z]E\<$/) { $result .= "$phrase>"; } else { $result =~ s/E\<$//; $result .= $phrase eq 'gt' ? '>' : '<'; } } else { $result .= $` . $&; } } else { $result .= $` . $&; } } # A sequence which may have something nested elsif ($text =~ /([A-Z])\; chop(@pod1); close FILE1; # Load the pod from the second file unless (open(FILE2, $file2)) { warn "unable to open '$file2': $!\n"; return (); } my @pod2 = ; chop(@pod2); close FILE2; # Diff the arrays return pod_diff_arrays(\@pod1, \@pod2, $formatter); } sub pod_diff_print_stats { my($strm) = @_; print $strm "*** SUMMARY ***\n"; print $strm "Total files: ", $total_runs, "\n"; print $strm "Total paras: ", $total_paras, "\n"; print $strm "Total diffs: ", $total_diffs, "\n"; print $strm "Total resync failures: ", $total_resync_fails, "\n"; if ($total_paras) { printf $strm "PERCENT OK: %.2f%%\n", ($total_paras - $total_diffs)/$total_paras * 100; } } # package return value 1; , or if ($phrase eq 'gt' && scalar @nested > 0 || $phrase eq 'lt' && $result =~ /[A-Z]E\<$/) { $result .= "$phrase>"; } else { $result =~ s/E\<$//; $resusdf-2.001/perllib/Pod/Sdf.pm010064400042570001753000000101570636030632600153530ustar00iancmtr00000400000236package Pod::Sdf; use Exporter; @ISA = qw(Exporter); @EXPORT = qw(sdf_escape pod2sdf); use strict; sub sdf_escape { my($line) = @_; # Escape special leading characters/patterns $line = "\\$line" if $line =~ /^\s*([-&[:>#!=*^+.\\]|[A-Z_0-9]\w*[:[])/; # Escape phrase patterns if ($line =~ s/\[\[/E<2[>/g) { $line =~ s/\]\]/E<2]>/g; } if ($line =~ s/\{\{/E<2{>/g) { $line =~ s/\}\}/E<2}>/g; } return $line; } sub pod2sdf { my($pod, $param) = @_; my(@sdf) = (); # Get the conversion parameters my $main = $param->{'main'}; # If the first line isn't a pod command, we need to start cutting # until we find one my $i; my $line; if (substr($$pod[0], 0, 1) ne '=') { @sdf = ('=cut', ''); for ($i = 0; $i < scalar(@$pod); $i++) { $line = $$pod[$i]; if ($line =~ /^\=/) { push(@sdf, '=begin sdf', ''); last; } else { push(@sdf, $line); } } } # Convert the rest my $new_para = 1; my $sdf_mode = 0; my $this_type = ''; my $last_type = ''; my $in_title = ''; my $tab_size = 8; for (; $i < scalar(@$pod); $i++) { $line = $$pod[$i]; # Convert tabs to spaces 1 while $line =~ s/\t+/' ' x (length($&) * $tab_size - length($`) % $tab_size)/e; # If we're in sdf mode, just pass lines through into the output if ($sdf_mode) { if ($line =~ /^=end\s+sdf/) { $sdf_mode = 0; $line =~ s/^/#/; } push(@sdf, $line); next; } # Blank lines terminate paragraphs if ($line =~ /^\s*$/) { $new_para = 1; $last_type = $this_type; next if $in_title; } # To convert from POD paragraphs to SDF, the rules are: # * tag indented lines as V (verbatim) paragraphs # * tag normal paragraphs (with N:), if necessary # * assume the first normal paragraph after =head NAME # is the document name, if this is a main document elsif ($new_para) { if ($line =~ /^\s+/) { $this_type = 'V'; $line = ">$line"; $sdf[$#sdf] = ">" if $last_type eq 'V'; } elsif (substr($line, 0, 1) eq '=') { $this_type = '='; $in_title = $main && ($line =~ /^=head1\s+NAME\b/); if ($in_title) { next; } elsif ($line =~ /^=for\s+sdf\s*/) { $line = $'; } elsif ($line =~ /^=begin\s+sdf/) { $line =~ s/^/#/; $sdf_mode = 1; } else { $line = "=" . sdf_escape(substr($line, 1)); } } else { $this_type = 'N'; if ($in_title) { $line =~ s/(['\\])/\\$1/g; push(@sdf, "# Build the title", "!define DOC_NAME '$line'", "!build_title", ''); next; } else { $line = sdf_escape($line); } } $new_para = 0; } # For lines within a normal paragraph, we need to escape # anything with special meaning in SDF elsif ($this_type eq 'N') { $line = sdf_escape($line); } # For lines within a verbatim paragraph, make them a # new verbatim paragraph. elsif ($this_type eq 'V') { $line = ">$line"; } # Update the output push(@sdf, $line); } # If the last line is a command, we need to explicitly # terminate it so that lines immediately following don't # get accidently eaten by the = parsing if ($sdf[$#sdf] =~ /^\=/) { push(@sdf, ''); } # Return result return @sdf; } # package return value 1; sdf-2.001/perllib/Makefile.PL010064400042570001753000000002070647237714200155340ustar00iancmtr00000400000236use ExtUtils::MakeMaker; WriteMakefile( NAME => 'perllib', PMLIBDIRS => [ 'Pod', 'sdf' ], ); sdf-2.001/examples/004075500042570001753000000000000672243767600137625ustar00iancmtr00000400000236sdf-2.001/examples/2001/004075500042570001753000000000000672243767600143445ustar00iancmtr00000400000236sdf-2.001/examples/2001/stylesheets/004075500042570001753000000000000672243774600167165ustar00iancmtr00000400000236sdf-2.001/examples/2001/stylesheets/divs.sdf010064400042570001753000000046330671271614600203550ustar00iancmtr00000400000236!include "divs.css"; stylesheet !define DOC_NAME "My Document" !define DOC_CODE "code" !define DOC_VERSION "version" !define DOC_STATUS "Draft" !define DOC_AUTHOR "Ian C" !define DOC_TOC 2 !build_title # trigger header & footer generation !define HTML_URL_HOME "home.html" H1: Stylesheet testing H2: Division testing SDF documents are now "stylesheet-friendly" in that DIVs are placed around interesting parts of the document as follows: !block table Document_part DIV_name title section title table of contents contents main body main header section header footer section footer navigate section navigate !endblock The navigate DIV is nested within header and footer. (This makes it easy to format the navigation section regardless of its location.) H2: Alignment testing Normal paragraph. In principle, scripts using this library have a consistent user interface and internal structure, making them easier to use and maintain. [align] Aligned paragraph. In principle, scripts using this library have a consistent user interface and internal structure, making them easier to use and maintain. [align=Left] Left alignment. In principle, scripts using this library have a consistent user interface and internal structure, making them easier to use and maintain. [align=Right] Right alignment. In principle, scripts using this library have a consistent user interface and internal structure, making them easier to use and maintain. [align=Center] Center alignment. In principle, scripts using this library have a consistent user interface and internal structure, making them easier to use and maintain. [align=Full] Full alignment. In principle, scripts using this library have a consistent user interface and internal structure, making them easier to use and maintain. H2: Indent testing [first=20] First=20 paragraph. In principle, scripts using this library have a consistent user interface and internal structure, making them easier to use and maintain. [left=20] Left=20 paragraph. In principle, scripts using this library have a consistent user interface and internal structure, making them easier to use and maintain. [right=20] Right=20 paragraph. In principle, scripts using this library have a consistent user interface and internal structure, making them easier to use and maintain. sdf-2.001/examples/2001/stylesheets/css_linked.html010064400042570001753000000022160672217352600217110ustar00iancmtr00000400000236

    A styled paragraph.

    A styled phrase within a paragraph.

    A Non-Abc paragraph.

    A Abc paragraph.

    An Xyz phrase.

    Some big Green text.

    A changed paragraph.

    A changed phrase in a paragraph.

    sdf-2.001/examples/2001/stylesheets/css_linked.sdf010064400042570001753000000010770671271206300215170ustar00iancmtr00000400000236# Link to a stylesheet !block links Jump test.css !endblock # Now test it works ... [style='background-color: blue;; color: red'] A styled paragraph. A {{[style='background-color: blue;; color: red']styled phrase}} within a paragraph. A {{B:Non-Abc}} {{I:paragraph}}. [class=Abc] A {{B:Abc}} {{I:paragraph}}. An {{B[class=Xyz] Xyz phrase}}. [color=Green; size=24; style='text-decoration: line-through'; family='sans-serif'; bold; italics; underline; bgcolor=Purple] Some big Green text. [changed] A changed paragraph. A {{A[changed] changed phrase}} in a paragraph. sdf-2.001/examples/2001/stylesheets/css_inline.sdf010064400042570001753000000011270671271220500215210ustar00iancmtr00000400000236# Make a stylesheet part of the generated document !include "test.css"; stylesheet # Now test it works ... [style='background-color: blue;; color: red'] A styled paragraph. A {{[style='background-color: blue;; color: red']styled phrase}} within a paragraph. A {{B:Non-Abc}} {{I:paragraph}}. [class=Abc] A {{B:Abc}} {{I:paragraph}}. An {{B[class=Xyz] Xyz phrase}}. [color=Green; size=24; style='text-decoration: line-through'; family='sans-serif'; bold; italics; underline; bgcolor=Purple] Some big Green text. [changed] A changed paragraph. A {{A[changed] changed phrase}} in a paragraph. sdf-2.001/examples/2001/stylesheets/css_inline.html010064400042570001753000000022350672217352200217160ustar00iancmtr00000400000236

    A styled paragraph.

    A styled phrase within a paragraph.

    A Non-Abc paragraph.

    A Abc paragraph.

    An Xyz phrase.

    Some big Green text.

    A changed paragraph.

    A changed phrase in a paragraph.

    reely available from http://www.mincom.com/mtr/sdf. -->

    sdf-2.001/examples/2001/stylesheets/divs.css010064400042570001753000000012070671321722400203550ustar00iancmtr00000400000236/* Header and footer formatting */ DIV.header {background-color: yellow} DIV.footer {background-color: olive} /* Title section formatting */ DIV.title {color: olive} DIV.title .doc-title {color: teal; font-size: 50pt} DIV.title .doc-status {color: red} /* Table of contents formatting */ DIV.contents {color: green} /* Main body formatting */ DIV.main {color: blue} /* Table formatting. Note: Table cells don't seem to inherit things from the main DIV? */ TABLE.columns {background-color: yellow} TABLE.columns TR.heading {background-color: aqua} TABLE.columns STRONG {font-size: 20pt} TABLE.columns TD {color: purple} sdf-2.001/examples/2001/stylesheets/divs.html010064400042570001753000000104710672217353400205410ustar00iancmtr00000400000236 My Document

    Home

    My Document

    code.version (Draft)
    Ian C
    24 May 1999

    Table of Contents

    1. Stylesheet testing

    1.1. Division testing

    SDF documents are now "stylesheet-friendly" in that DIVs are placed around interesting parts of the document as follows:

    Document part DIV name
    title section title
    table of contents contents
    main body main
    header section header
    footer section footer
    navigate section navigate

    The navigate DIV is nested within header and footer. (This makes it easy to format the navigation section regardless of its location.)

    1.2. Alignment testing

    Normal paragraph. In principle, scripts using this library have a consistent user interface and internal structure, making them easier to use and maintain.

    Aligned paragraph. In principle, scripts using this library have a consistent user interface and internal structure, making them easier to use and maintain.

    Left alignment. In principle, scripts using this library have a consistent user interface and internal structure, making them easier to use and maintain.

    Right alignment. In principle, scripts using this library have a consistent user interface and internal structure, making them easier to use and maintain.

    Center alignment. In principle, scripts using this library have a consistent user interface and internal structure, making them easier to use and maintain.

    Full alignment. In principle, scripts using this library have a consistent user interface and internal structure, making them easier to use and maintain.

    1.3. Indent testing

    First=20 paragraph. In principle, scripts using this library have a consistent user interface and internal structure, making them easier to use and maintain.

    Left=20 paragraph. In principle, scripts using this library have a consistent user interface and internal structure, making them easier to use and maintain.

    Right=20 paragraph. In principle, scripts using this library have a consistent user interface and internal structure, making them easier to use and maintain.

    Home

    sdf-2.001/examples/2001/stylesheets/test.css010064400042570001753000000001100671154716600203700ustar00iancmtr00000400000236P I { color: #007f00 } P.abc B { color: #00007f } B.xyz { color: red } sdf-2.001/Makefile.PL010064400042570001753000000015030672236172100140750ustar00iancmtr00000400000236 require 5.004; # make sure perl version is at least 5.004 if (defined $ENV{SDFHOME}) { warn < 'SDF', 'DISTNAME' => 'sdf', 'VERSION' => '2.001', 'DIR' => [ qw(bin perllib) ], 'dist' => {'COMPRESS'=>'gzip -9f', 'SUFFIX'=>'.gz'}, ); package MY; # What happens when we say 'make test' # Copied libwww Makefile.PL sub test { q( TEST_VERBOSE=0 test: all $(FULLPERL) t/TEST $(TEST_VERBOSE) ); } # Use t/sdftest for test target #sub test #{ # q( #TEST_VERBOSE=0 # #test: all # cd t && ./sdftest $(FULLPERL) # #); #} sdf-2.001/INSTALL010064400042570001753000000153160672242771600131720ustar00iancmtr000004000002361. Installing SDF ================= 1.1. Overview ------------- If SDF is not yet installed, you will need to fetch it and install it. The latest version of SDF can be fetched from the SDF download page, http://www.mincom.com/mtr/sdf/download.html. If Perl is not installed, you will also need to fetch and install it. Various ports of Perl can be obtained from the Perl Home Page (http://www.perl.com/index/). SDF installation details are provided below for: o Unix o Windows NT o Windows 95 o MS-DOS/Windows 3.x. Some general Installation Notes are also provided. 1.2. Unix --------- Use the tar and gunzip programs to unpack the distribution like this: gunzip sdf-2.000.tar.gz tar xvf sdf-2.000.tar Build, test and install the software like this: perl Makefile.PL make make test make install 1.3. Windows NT --------------- Unpack the distribution using a program which understands long file names (e.g. WinZip). Within the Control Panel, go to the System properties, select the Environment tab and edit the variables as follows: 1. Update the PATH to include the bin\dos directory where SDF is installed. For example, if SDF is installed in c:\sdf, then you need to edit the PATH system variable to include c:\sdf\bin\dos. 2. Edit (or add) the PERL5LIB variable to include the Perl libraries used by SDF. For example, if SDF is installed in c:\sdf, then you need to edit the PERL5LIB variable to include c:\sdf\perllib. 3. Set the SDFBIN variable to point to the directory containing SDF's scripts, including the trailing \. For example, if SDF is installed in c:\sdf, then you need to set the SDFBIN variable to c:\sdf\bin\. Test the software. To do this: 1. Start an MS-DOS window. 2. Change directory to the t directory within the SDF distribution. 3. Run sdf without any arguments to confirm that SDF was successfully installed. 4. Run sdftest. If anything fails, sdftest will leave the failed .out and .log files in the relevant directories. 1.4. Windows 95 --------------- Unpack the distribution using a program which understands long file names (e.g. WinZip). Update the PATH to include the bin\dos directory where SDF is installed. For example, if SDF is installed in c:\sdf, then the command is: set PATH=%PATH%;c:\sdf\bin\dos Edit (or add) the PERL5LIB system variable to include the Perl libraries used by SDF. For example, if SDF is installed in c:\sdf, then the command is: set PERL5LIB=%PERL5LIB%;c:\sdf\perllib Set the SDFBIN variable to point to the directory containing SDF's scripts, including the trailing \. For example, if SDF is installed in c:\sdf, then the command is: set SDFBIN=c:\sdf\bin\ Test the software. To do this: 1. Change directory to the t directory within the SDF distribution. 2. Run sdf without any arguments to confirm that SDF was successfully installed. 3. Run sdftest. If anything fails, sdftest will leave the failed .out and .log files in the relevant directories. Note: PATH, PERL5LIB and SDFBIN should be set within your autoexec.bat file. 1.5. MS-DOS/Windows 3.x ----------------------- Use pkunzip to unpack the distribution. The command is: pkunzip -d sdf.zip Update the PATH to include the bin\dos directory where SDF is installed. For example, if SDF is installed in c:\sdf, then the command is: set PATH=%PATH%;c:\sdf\bin\dos Edit (or add) the PERL5LIB system variable to include the Perl libraries used by SDF. For example, if SDF is installed in c:\sdf, then the command is: set PERL5LIB=%PERL5LIB%;c:\sdf\perllib Set the SDFBIN variable to point to the directory containing SDF's scripts, including the trailing \. For example, if SDF is installed in c:\sdf, then the command is: set SDFBIN=c:\sdf\bin\ Test the software. To do this: 1. Change directory to the t directory within the SDF distribution. 2. Run sdf without any arguments to confirm that SDF was successfully installed. 3. Run sdftest. If anything fails, sdftest will leave the failed .out and .log files in the relevant directories. Note: PATH, PERL5LIB and SDFBIN should be set within your autoexec.bat file. 1.6. Installation Notes ----------------------- 1.6.1. Distribution Formats --------------------------- The tar.gz and zip distributions should both contain the same set of files. Therefore, it shouldn't matter which distribution you obtain provided you have the necessary software to unpack it. 1.6.2. The sdf.ini File ----------------------- The sdf.ini configuration file (in the sdf/home directory on Perl's library path) contains several sets of configuration parameters which you may want to edit after SDF is installed. Refer to the comments in the file for further details. 1.6.3. Win32 Support -------------------- SDF has been briefly tested with: o Gurusamy Sarathy's 5.004_02 Perl port (August 97), and o ActiveState's Perl port build 315 (based on 5.003_07). Both seem to work ok, although running sdftest with the 5.004_02 port leaves zero length .out and .log files for the tests which work (when they should be deleted). 1.6.4. The SDFBIN Environment Variable -------------------------------------- This environment variable is only used by the Windows/DOS wrapper batch files within bin/dos to find the real scripts. Therefore, if you wish to wrap the scripts in some other way, then there is no need to set this variable. 1.6.5. Macintosh support ------------------------ Unlike earlier versions, the 2.000 release includes support for Macintosh filename handling. Installation instructions for the Macintosh will be made available soon. 1.6.6. Testing Notes -------------------- When the sdf command is run without arguments, the output should be something like: usage : sdf [+alias] [-h[help]] [-o[out_ext]] [-l[log_ext]] [-2 format] [-D var iable,..] [-n split_level] [-f flag,..] [-I include_path,..] [-p prefilter] [-a parameters] [-P[plang]] [-N[line_numbers]] [-r report] [-L locale] [-k look] [-s style] [-S page_size] [-c config] [-u uses,..] [-H head_level] [-d driver] [-y post_filter] [-z post_process,..] [-t target] [-v[verbose]] [-w width] sdf_file ... purpose: convert an sdf file to another format version: 2.000 (SDF 2.000) If this fails, check the following: 1. perl 5.003 or later is installed (type perl -v to test) 2. the sdf script is on your path and under Unix, is executable. SDF is supplied with a regression testing system. To run the tests, change to the t directory within the SDF distribution and execute sdftest like this: sdftest This command can be used at anytime to verify your installation of SDF. The SDF Sample Showcase contains SDF source code and matching outputs. If you wish to conduct further tests, these samples can be used. sdf-2.001/PODNOTES010064400042570001753000000163200640514015600132770ustar00iancmtr00000400000236A summary of the outstanding POD-related work is given below. But first, some things to try. Converting Perl's Core Documentation to Plain Text ================================================== The command is: sdf -2txt /*.pod Converting Perl's Documentation to HTML ======================================= To generate the Perl documentation available at http://www.mincom.com/mtr/perl/catalog.html, the commands are: cd cp $SDFHOME/perl/catalog.sdf . cp $SDFHOME/perl/oracamel.gif . mkpldocs all If you wish, have a look at the perl/perl.sdm file in the SDF distribution. By making changes in there, you can: * change the logo in the top right hand corner by setting the DOC_LOGO variable * change the background colour and image by setting the HTML_BG_COLOR and HTML_BG_IMAGE variables * change the footer by editing the HTML_FOOTER macro * add a header by defining the HTML_HEADER macro * improve the hypertext generation rules by overriding the BuildLinkUrl() routine * change the L<> phrase expansion rules by setting the FORMAT_LINK_* variables The Perl camel is a trademark of O'Reilly and Associates, so please mention that in a footer, say, if you use it. How Does SDF Compare With pod2text/pod2html? ============================================ The HTML generated by SDF arguably looks a bit better than that produced by pod2html, particularly when the DOC_LOGO variable is set. However, pod2html is better than sdf in the areas of: * hypertext generation - pod2html builds a cache of Perl specific items and generates hypertext to them whenever it can * enumerated list presentation - when 2 or more items share a common description, pod2html uses less whitespace In Perl 5.004, pod2html has a problem with special characters in headings (see perlfaq4) which SDF doesn't and pod2text has a problem with wrapping verbatim paragraphs (see perldebug) which SDF doesn't. But those bugs might be fixed by now. As a general summary, the pod2* programs are much quicker than SDF, but SDF has more features. So, if you want to use tables and figures, say, then SDF produces better output. On the other hand, if you prefer the output from pod2html and/or pod2text, you can still embed SDF tables and figures in POD and then use SDF to generate vanilla POD, ready for pod2*. Converting From POD to SDF and Back Again ========================================= The command is: sdf -2pod /*.pod This will create a set of .pod files in the current directory. Comparing the Generated POD with the Original ============================================= Firstly, you might want to exclude perltoc.pod from the comparison by doing something like: mv perltoc.pod perltoc.pod.keep The command is: poddiff *.pod > PODDIFFS The poddiff program works by comparing files on a paragraph by paragraph basis. Within a non-verbatim paragraph, additional whitespace and unneeded E<> escapes are ignored. The parameter to the over command is also ignored. See the PODDIFFS file in the SDF distribution for a sample output. You may wish to examine that file and the generated POD files (for 5.004) to confirm the following: * the differences in perldata.pod and perltoot.pod are caused by (unnecessary?) Z<> sequences * the difference in perlfaq4.pod is due to sdf automatically terminating an unterminated C<> phrase (as mentioned above) after producing a warning about it * the differences in perlsubs.pod are due to one list ending and another one starting, when it seems unnecessary to do this. As yet, I haven't analysed the differences in perltoc.pod, but most of them seem to be related to list over/back commands. In any case, the output from sdf -2html -cperl perltoc.pod seems ok. Known Bugs ========== * The pod2sdf and POD::SDF.pm stuff hasn't been documented yet. I'll probably do the doco for these in vanilla POD, and offer for them to be included in the standard Perl distribution. Thoughts? * The doco hasn't been updated to reflect the new macros, phrase styles, etc. In particular, the User Guide, Reference and White Paper need to be updated. * The X phrase style doesn't work yet for any output format except POD (and those generated by going via POD). If you need a workaround, indexing can be done using the index phrase attribute. * sdf -2latex_pod xxx generates an xxx.out.tex file, rather than an xxx.tex file. * The implementation of BuildLinkUrl() in perl/perl.sdm (i.e. the perl configuration library) still needs some more intelligence. * The -w option isn't currently passed through to pod2text. (I had trouble getting pod2text to accept it.) * The toraw.pl driver needs to be updated to dump <> style phrases rather than {{}} style ones. When this is done, the expected output files in the test/*/checked directories will need to be updated. Other Thoughts ============== At the moment, the pod2* programs are substantially faster than the sdf program. The main performance issue with sdf is the loading of its configuration files. So, a one line document can take several seconds to convert, but a 100 line document doesn't take much longer. I'm planning to address configuration file caching as part of the source code migration to Perl 5. Note that users can specify things on the command line and/or top line of a file which can affect the configuration loading process, so configuration caching is non trival. Some of the nice features in pod2html (e.g. hypertext link generation for Perl-specific items in general text) aren't available and I'm not yet sure how to provide them. A new -e option could be used to specify that SDF is embedded in source code comments and the appropriate leading character sequence should be stripped, if found. That sequence could be derived from the file extension or explicitly specified as a parameter to the -e option. Alternatively, SDF could check the file extension and assume the -e option if it looks like source code. The intention here is to provide a simple version of the functionality provided by Brad Appleton's POD::Parser preprocess_line() routine. The pod filter could take a select argument ala Brad Appleton's POD::Parser stuff. In fact, implementing the POD::SDF module using POD::Parser might be a good idea. (This wasn't done because the pod2sdf subroutine is currently pretty trivial.) POD pretty printing could be added by updating stdlib/langdefs.sdm. Each of the commands could be added as a keyword, although I'm not sure if we can highlight the interior sequences? Tim MacKenzie's enhancements to the txt output driver haven't been applied to the pod output driver yet. When that is done, wrapping of text within table cells should work. The POD convention of starting documentation with a =head NAME and putting the actual title as the next paragraph is a pain. I wish POD documents started with a =title instead. Perhaps pod2sdf could do this? It would be good if pod2sdf had an option to produce "traditional" SDF, i.e. with tagged lists, rather than over/item/back lists. The poddiff program isn't yet useful for comparing POD generated by sdf -2pod with POD in a .pm file. This could be changed by teaching Pod::Diff.pm to ignore lines which have been cut. sdf-2.001/MANIFEST010064400042570001753000000510620672243164400132630ustar00iancmtr00000400000236INSTALL LICENSE MANIFEST MANIFEST.SKIP Makefile.PL PODDIFFS PODNOTES README bin/Makefile.PL bin/dos/mif2rtf.bat bin/dos/mkpldocs.bat bin/dos/pod2sdf.bat bin/dos/poddiff.bat bin/dos/prn2ps.bat bin/dos/sdf.bat bin/dos/sdf2hlp.bat bin/dos/sdf2mif.bat bin/dos/sdf2rtf.bat bin/dos/sdfapi.bat bin/dos/sdfbatch.bat bin/dos/sdfcli.bat bin/dos/sdfget.bat bin/dos/sdngen.bat bin/fm2ps bin/mif2rtf bin/mkpldocs bin/pod2sdf bin/poddiff bin/prn2ps bin/sdf bin/sdfapi bin/sdfbatch bin/sdfcli bin/sdfget bin/sdngen doc/build doc/catalog.html doc/catalog.sdf doc/faq/faq.html doc/faq/faq.sdf doc/faq/faq_fmts.sdf doc/faq/faq_gen.sdf doc/faq/faq_lang.sdf doc/faq/faq_real.sdf doc/faq/index.html doc/genhtml/index.html doc/genhtml/index.sdf doc/guru/about.html doc/guru/about.sdf doc/guru/app.html doc/guru/dict.html doc/guru/ex_dvrs.html doc/guru/ex_dvrs.sdf doc/guru/ex_filt.html doc/guru/ex_filt.sdf doc/guru/ex_look.html doc/guru/ex_look.sdf doc/guru/ex_mac.html doc/guru/ex_mac.sdf doc/guru/ex_para.html doc/guru/ex_para.sdf doc/guru/ex_phras.html doc/guru/ex_phras.sdf doc/guru/ex_tbl.html doc/guru/ex_tbl.sdf doc/guru/gg_sdf.html doc/guru/gg_sdf.sdf doc/guru/in_api.html doc/guru/in_api.sdf doc/guru/in_ex.html doc/guru/in_ex.sdf doc/guru/index.html doc/guru/misc.html doc/guru/name.html doc/guru/parse.html doc/guru/table.html doc/home.html doc/home.sdf doc/index.html doc/notes/latex.notes doc/paper/index.html doc/paper/key.gif doc/paper/mydoc.sdf doc/paper/sdfarch.eps doc/paper/sdfarch.gif doc/paper/sdfarch.vsd doc/paper/sdfintro.html doc/paper/sdfintro.sdf doc/pdf.gif doc/podusers/index.html doc/podusers/index.sdf doc/postscript.gif doc/quickref/index.html doc/quickref/qr_sdf.html doc/quickref/qr_sdf.sdf doc/ref/classes/corganis.sdf doc/ref/classes/cproduct.sdf doc/ref/classes/creferen.sdf doc/ref/classes/cterms.sdf doc/ref/corganis.html doc/ref/cproduct.html doc/ref/creferen.html doc/ref/cterms.html doc/ref/fabout.html doc/ref/fabstrac.html doc/ref/faddress.html doc/ref/fappendi.html doc/ref/fascii_g.html doc/ref/fbox.html doc/ref/fchanged.html doc/ref/fcomment.html doc/ref/fdatestr.html doc/ref/fdefault.html doc/ref/fdefine.html doc/ref/fend.html doc/ref/fexample.html doc/ref/ffront.html doc/ref/fget.html doc/ref/fhlp_hea.html doc/ref/fhlp_win.html doc/ref/filters/fabout.sdf doc/ref/filters/fabstrac.sdf doc/ref/filters/faddress.sdf doc/ref/filters/fappendi.sdf doc/ref/filters/fascii_g.sdf doc/ref/filters/fbox.sdf doc/ref/filters/fchanged.sdf doc/ref/filters/fcomment.sdf doc/ref/filters/fdatestr.sdf doc/ref/filters/fdefault.sdf doc/ref/filters/fdefine.sdf doc/ref/filters/fend.sdf doc/ref/filters/fexample.sdf doc/ref/filters/ffront.sdf doc/ref/filters/fget.sdf doc/ref/filters/fhlp_hea.sdf doc/ref/filters/fhlp_win.sdf doc/ref/filters/finline.sdf doc/ref/filters/flangdef.sdf doc/ref/filters/fnameval.sdf doc/ref/filters/fnofill.sdf doc/ref/filters/fnote.sdf doc/ref/filters/fplain.sdf doc/ref/filters/fpod.sdf doc/ref/filters/fquote.sdf doc/ref/filters/fscript.sdf doc/ref/filters/fsdf.sdf doc/ref/filters/fsection.sdf doc/ref/filters/fsimple.sdf doc/ref/filters/ftable.sdf doc/ref/filters/ftitle.sdf doc/ref/filters/ftopics.sdf doc/ref/filters/fverbati.sdf doc/ref/finline.html doc/ref/flangdef.html doc/ref/fmt_ini.html doc/ref/fmt_ini.sdf doc/ref/fmt_sdg.html doc/ref/fmt_sdg.sdf doc/ref/fmt_tbl.html doc/ref/fmt_tbl.sdf doc/ref/fnameval.html doc/ref/fnofill.html doc/ref/fnote.html doc/ref/fplain.html doc/ref/fpod.html doc/ref/fquote.html doc/ref/fscript.html doc/ref/fsdf.html doc/ref/fsection.html doc/ref/fsimple.html doc/ref/ftable.html doc/ref/ftitle.html doc/ref/ftopics.html doc/ref/fverbati.html doc/ref/gl_cli.html doc/ref/gl_cli.sdf doc/ref/in_claif.html doc/ref/in_claif.sdf doc/ref/in_class.html doc/ref/in_class.sdf doc/ref/in_dstyl.html doc/ref/in_dstyl.sdf doc/ref/in_esc.html doc/ref/in_esc.sdf doc/ref/in_filif.html doc/ref/in_filif.sdf doc/ref/in_filt.html doc/ref/in_filt.sdf doc/ref/in_fmt.html doc/ref/in_fmt.sdf doc/ref/in_mac.html doc/ref/in_mac.sdf doc/ref/in_macif.html doc/ref/in_macif.sdf doc/ref/in_oattr.html doc/ref/in_oattr.sdf doc/ref/in_ostyl.html doc/ref/in_ostyl.sdf doc/ref/in_pattr.html doc/ref/in_pattr.sdf doc/ref/in_prog.html doc/ref/in_prog.sdf doc/ref/in_pstyl.html doc/ref/in_pstyl.sdf doc/ref/in_sub.html doc/ref/in_sub.sdf doc/ref/in_sym.sdf doc/ref/in_var.html doc/ref/in_var.sdf doc/ref/index.html doc/ref/macros/mblock.sdf doc/ref/macros/mbuild_t.sdf doc/ref/macros/mcatalog.sdf doc/ref/macros/mclass.sdf doc/ref/macros/mclear.sdf doc/ref/macros/mcontinu.sdf doc/ref/macros/mdefault.sdf doc/ref/macros/mdefine.sdf doc/ref/macros/melse.sdf doc/ref/macros/melseif.sdf doc/ref/macros/melsif.sdf doc/ref/macros/mend_top.sdf doc/ref/macros/mendbloc.sdf doc/ref/macros/mendif.sdf doc/ref/macros/mendmacr.sdf doc/ref/macros/mexecute.sdf doc/ref/macros/mexport.sdf doc/ref/macros/mgetcli.sdf doc/ref/macros/mgetcode.sdf doc/ref/macros/mgetdoc.sdf doc/ref/macros/mif.sdf doc/ref/macros/mimport.sdf doc/ref/macros/minclude.sdf doc/ref/macros/minherit.sdf doc/ref/macros/minit.sdf doc/ref/macros/minsert.sdf doc/ref/macros/mjumps.sdf doc/ref/macros/mline.sdf doc/ref/macros/mmacro.sdf doc/ref/macros/mmessage.sdf doc/ref/macros/moff.sdf doc/ref/macros/mon.sdf doc/ref/macros/moutput.sdf doc/ref/macros/mperlapi.sdf doc/ref/macros/mrestric.sdf doc/ref/macros/mscript.sdf doc/ref/macros/mslide_d.sdf doc/ref/macros/mslide_u.sdf doc/ref/macros/msubsect.sdf doc/ref/macros/mundef.sdf doc/ref/macros/muse.sdf doc/ref/mblock.html doc/ref/mbuild_t.html doc/ref/mcatalog.html doc/ref/mclass.html doc/ref/mclear.html doc/ref/mcontinu.html doc/ref/mdefault.html doc/ref/mdefine.html doc/ref/melse.html doc/ref/melseif.html doc/ref/melsif.html doc/ref/mend_top.html doc/ref/mendbloc.html doc/ref/mendif.html doc/ref/mendmacr.html doc/ref/mexecute.html doc/ref/mexport.html doc/ref/mgetcli.html doc/ref/mgetcode.html doc/ref/mgetdoc.html doc/ref/mif.html doc/ref/mimport.html doc/ref/minclude.html doc/ref/minherit.html doc/ref/minit.html doc/ref/minsert.html doc/ref/mjumps.html doc/ref/mline.html doc/ref/mmacro.html doc/ref/mmessage.html doc/ref/moff.html doc/ref/mon.html doc/ref/moutput.html doc/ref/mperlapi.html doc/ref/mrestric.html doc/ref/mscript.html doc/ref/mslide_d.html doc/ref/mslide_u.html doc/ref/msubsect.html doc/ref/mundef.html doc/ref/muse.html doc/ref/prn2ps.html doc/ref/prn2ps.sdf doc/ref/re_sdf.html doc/ref/re_sdf.sdf doc/ref/reasdf.html doc/ref/reasdf.sdf doc/ref/sappendt.html doc/ref/sappendt.sdf doc/ref/sdf.html doc/ref/sdf.sdf doc/ref/sdfapi.html doc/ref/sdfapi.sdf doc/ref/sdfbatch.html doc/ref/sdfbatch.sdf doc/ref/sdfcli.html doc/ref/sdfcli.sdf doc/ref/sdfget.html doc/ref/sdfget.sdf doc/ref/sdftest.html doc/ref/sdftest.sdf doc/ref/sdngen.html doc/ref/sdngen.sdf doc/ref/sfindfil.html doc/ref/sfindfil.sdf doc/ref/sformatt.html doc/ref/sformatt.sdf doc/ref/sprepend.html doc/ref/sprepend.sdf doc/ref/var_conv.html doc/ref/var_conv.sdf doc/ref/var_doc.html doc/ref/var_doc.sdf doc/ref/var_file.html doc/ref/var_file.sdf doc/ref/var_misc.html doc/ref/var_misc.sdf doc/release/2000.html doc/release/2000.sdf doc/release/2000b10.html doc/release/2000b10.sdf doc/release/2000b11.html doc/release/2000b11.sdf doc/release/2000b12.html doc/release/2000b12.sdf doc/release/2000b4b.html doc/release/2000b4b.sdf doc/release/2000b4c.html doc/release/2000b4c.sdf doc/release/2000b5.html doc/release/2000b5.sdf doc/release/2000b6.html doc/release/2000b6.sdf doc/release/2000b6a.html doc/release/2000b6a.sdf doc/release/2000b6b.html doc/release/2000b6b.sdf doc/release/2000b6c.html doc/release/2000b6c.sdf doc/release/2000b7.html doc/release/2000b7.sdf doc/release/2000b7a.html doc/release/2000b7a.sdf doc/release/2000b7b.html doc/release/2000b7b.sdf doc/release/2000b7c.html doc/release/2000b7c.sdf doc/release/2000b8.html doc/release/2000b8.sdf doc/release/2000b8a.html doc/release/2000b8a.sdf doc/release/2000b9.html doc/release/2000b9.sdf doc/release/2000b9a.html doc/release/2000b9a.sdf doc/release/2001.html doc/release/2001.sdf doc/release/2001b1.html doc/release/2001b1.sdf doc/release/index.html doc/release/rn_sdf.html doc/release/rn_sdf.sdf doc/sdfbig.gif doc/sdflogo.bmp doc/sdflogo.gif doc/sqbull.gif doc/user/credits.html doc/user/credits.sdf doc/user/in_book.sdf doc/user/in_cond.html doc/user/in_cond.sdf doc/user/in_custf.html doc/user/in_custf.sdf doc/user/in_event.html doc/user/in_event.sdf doc/user/in_examp.html doc/user/in_examp.sdf doc/user/in_fg.html doc/user/in_fg.sdf doc/user/in_fggen.html doc/user/in_fggen.sdf doc/user/in_fgov.html doc/user/in_fgov.sdf doc/user/in_fgpos.html doc/user/in_fgpos.sdf doc/user/in_fgtit.html doc/user/in_fgtit.sdf doc/user/in_gsex.html doc/user/in_gsex.sdf doc/user/in_gsgen.html doc/user/in_gsgen.sdf doc/user/in_hdg.html doc/user/in_hdg.sdf doc/user/in_hdrfr.sdf doc/user/in_hyper.html doc/user/in_hyper.sdf doc/user/in_index.sdf doc/user/in_insta.html doc/user/in_insta.sdf doc/user/in_intro.html doc/user/in_intro.sdf doc/user/in_libr.html doc/user/in_libr.sdf doc/user/in_lists.html doc/user/in_lists.sdf doc/user/in_looks.html doc/user/in_looks.sdf doc/user/in_notes.html doc/user/in_notes.sdf doc/user/in_omgmt.html doc/user/in_omgmt.sdf doc/user/in_ovatt.html doc/user/in_ovatt.sdf doc/user/in_overv.html doc/user/in_overv.sdf doc/user/in_ovexp.html doc/user/in_ovexp.sdf doc/user/in_ovflt.html doc/user/in_ovflt.sdf doc/user/in_ovmac.html doc/user/in_ovmac.sdf doc/user/in_ovpar.html doc/user/in_ovpar.sdf doc/user/in_ovphr.html doc/user/in_ovphr.sdf doc/user/in_ovvar.html doc/user/in_ovvar.sdf doc/user/in_parag.html doc/user/in_parag.sdf doc/user/in_phrs.sdf doc/user/in_sdadv.html doc/user/in_sdadv.sdf doc/user/in_start.html doc/user/in_start.sdf doc/user/in_style.html doc/user/in_style.sdf doc/user/in_symb.html doc/user/in_symb.sdf doc/user/in_table.sdf doc/user/in_tb.html doc/user/in_tb.sdf doc/user/in_tboth.html doc/user/in_tboth.sdf doc/user/in_tbov.html doc/user/in_tbov.sdf doc/user/in_tbpos.html doc/user/in_tbpos.sdf doc/user/in_tbrow.html doc/user/in_tbrow.sdf doc/user/in_tbsiz.html doc/user/in_tbsiz.sdf doc/user/in_tbss.html doc/user/in_tbss.sdf doc/user/in_tbsty.html doc/user/in_tbsty.sdf doc/user/in_tbtit.html doc/user/in_tbtit.sdf doc/user/in_title.html doc/user/in_title.sdf doc/user/ug_sdf.html doc/user/ug_sdf.sdf doc/user/ugasdf.html doc/user/ugasdf.sdf doc/website examples/2001/stylesheets/css_inline.html examples/2001/stylesheets/css_inline.sdf examples/2001/stylesheets/css_linked.html examples/2001/stylesheets/css_linked.sdf examples/2001/stylesheets/divs.css examples/2001/stylesheets/divs.html examples/2001/stylesheets/divs.sdf examples/2001/stylesheets/test.css perllib/Makefile.PL perllib/Pod/Diff.pm perllib/Pod/Sdf.pm perllib/sdf/apiperl.pl perllib/sdf/app.pl perllib/sdf/app.sdf perllib/sdf/calc.pl perllib/sdf/dict.pl perllib/sdf/filters.pl perllib/sdf/find.pl perllib/sdf/home/images/arrow.bmp perllib/sdf/home/images/arrow.gif perllib/sdf/home/images/back.bmp perllib/sdf/home/images/back.gif perllib/sdf/home/images/bar1.bmp perllib/sdf/home/images/bar1.gif perllib/sdf/home/images/bg_ball.bmp perllib/sdf/home/images/bg_ball.gif perllib/sdf/home/images/bk_diam.bmp perllib/sdf/home/images/bk_diam.gif perllib/sdf/home/images/camera1.bmp perllib/sdf/home/images/camera1.gif perllib/sdf/home/images/constrt1.bmp perllib/sdf/home/images/constrt1.gif perllib/sdf/home/images/dir.gif perllib/sdf/home/images/doc.gif perllib/sdf/home/images/exclam.bmp perllib/sdf/home/images/exclam.gif perllib/sdf/home/images/exit1.bmp perllib/sdf/home/images/exit1.gif perllib/sdf/home/images/folders.bmp perllib/sdf/home/images/folders.gif perllib/sdf/home/images/ftp1.bmp perllib/sdf/home/images/ftp1.gif perllib/sdf/home/images/greenbal.bmp perllib/sdf/home/images/greenbal.gif perllib/sdf/home/images/hot_dot.bmp perllib/sdf/home/images/hot_dot.gif perllib/sdf/home/images/htx.gif perllib/sdf/home/images/images.sdm perllib/sdf/home/images/info1.bmp perllib/sdf/home/images/info1.gif perllib/sdf/home/images/info2.bmp perllib/sdf/home/images/info2.gif perllib/sdf/home/images/key.bmp perllib/sdf/home/images/key.gif perllib/sdf/home/images/m0omo7eu.bmp perllib/sdf/home/images/m0omo7eu.gif perllib/sdf/home/images/mail1.bmp perllib/sdf/home/images/mail1.gif perllib/sdf/home/images/mail2.bmp perllib/sdf/home/images/mail2.gif perllib/sdf/home/images/mailto.bmp perllib/sdf/home/images/mailto.gif perllib/sdf/home/images/mf6.gif perllib/sdf/home/images/new1.bmp perllib/sdf/home/images/new1.gif perllib/sdf/home/images/new2.bmp perllib/sdf/home/images/new2.gif perllib/sdf/home/images/new3.bmp perllib/sdf/home/images/new3.gif perllib/sdf/home/images/news1.bmp perllib/sdf/home/images/news1.gif perllib/sdf/home/images/next.bmp perllib/sdf/home/images/next.gif perllib/sdf/home/images/pdf.gif perllib/sdf/home/images/postscript.gif perllib/sdf/home/images/pow.bmp perllib/sdf/home/images/pow.gif perllib/sdf/home/images/printer.gif perllib/sdf/home/images/ps.gif perllib/sdf/home/images/qsd.gif perllib/sdf/home/images/ques1.bmp perllib/sdf/home/images/ques1.gif perllib/sdf/home/images/rd_ball.bmp perllib/sdf/home/images/rd_ball.gif perllib/sdf/home/images/sdf.gif perllib/sdf/home/images/sdfbig.bmp perllib/sdf/home/images/sdfbig.gif perllib/sdf/home/images/sdflogo.bmp perllib/sdf/home/images/sdflogo.gif perllib/sdf/home/images/sqbull.gif perllib/sdf/home/images/square_b.bmp perllib/sdf/home/images/square_b.gif perllib/sdf/home/images/text.gif perllib/sdf/home/images/triangle.gif perllib/sdf/home/images/txt.gif perllib/sdf/home/locale/cz_cz.sdl perllib/sdf/home/locale/de_de.sdl perllib/sdf/home/locale/en_au.sdl perllib/sdf/home/locale/en_ca.sdl perllib/sdf/home/locale/en_uk.sdl perllib/sdf/home/locale/en_us.sdl perllib/sdf/home/locale/ru_ru.sdl perllib/sdf/home/look/fancy/fancy.sdm perllib/sdf/home/look/fancy/manual.sds perllib/sdf/home/look/fancy/mif.sdn perllib/sdf/home/look/fancy/pages.sdm perllib/sdf/home/look/infomap/infomap.sdm perllib/sdf/home/look/infomap/mif.sdn perllib/sdf/home/look/infomap/pages.sdm perllib/sdf/home/look/overhead/mif.sdn perllib/sdf/home/look/overhead/overhead.sdm perllib/sdf/home/look/simple/admin.sds perllib/sdf/home/look/simple/covers.sdm perllib/sdf/home/look/simple/document.sds perllib/sdf/home/look/simple/fax.sds perllib/sdf/home/look/simple/listing.sds perllib/sdf/home/look/simple/manual.sds perllib/sdf/home/look/simple/memo.sds perllib/sdf/home/look/simple/mif.sdn perllib/sdf/home/look/simple/mif.sdt.keep perllib/sdf/home/look/simple/minutes.sds perllib/sdf/home/look/simple/newslttr.sds perllib/sdf/home/look/simple/pages.sdm perllib/sdf/home/look/simple/paper.sds perllib/sdf/home/look/simple/rtf.sdn perllib/sdf/home/look/simple/simple.sdm perllib/sdf/home/perl/catalog.sdf perllib/sdf/home/perl/oracamel.gif perllib/sdf/home/perl/perl.sdm perllib/sdf/home/sdf.ini perllib/sdf/home/sdf/document.reg perllib/sdf/home/sdf/sdf.sdm perllib/sdf/home/sdfbatch.ini perllib/sdf/home/stdlib/A4.fm4 perllib/sdf/home/stdlib/A4.fm5 perllib/sdf/home/stdlib/all.sdg perllib/sdf/home/stdlib/bugtrack.sdm perllib/sdf/home/stdlib/default.sdg perllib/sdf/home/stdlib/defines.sdm perllib/sdf/home/stdlib/delphi.sdm perllib/sdf/home/stdlib/hlp.sdn perllib/sdf/home/stdlib/homepage.sdm perllib/sdf/home/stdlib/html.sdn perllib/sdf/home/stdlib/langdefs.sdm perllib/sdf/home/stdlib/latex.sdn perllib/sdf/home/stdlib/macros.sdm perllib/sdf/home/stdlib/mif.sdn perllib/sdf/home/stdlib/misc.sdm perllib/sdf/home/stdlib/module.sdp perllib/sdf/home/stdlib/objects.sdm perllib/sdf/home/stdlib/pages.sdm perllib/sdf/home/stdlib/pod.sdn perllib/sdf/home/stdlib/rtf.sdn perllib/sdf/home/stdlib/sdf_dir.sdr perllib/sdf/home/stdlib/sdgmacs.sdm perllib/sdf/home/stdlib/settings.sdm perllib/sdf/home/stdlib/sgml.sdn perllib/sdf/home/stdlib/simple.sdp perllib/sdf/home/stdlib/stdlib.sdm perllib/sdf/home/stdlib/testcase.sdm perllib/sdf/home/stdlib/txt.sdn perllib/sdf/home/stdlib/usecases.sdm perllib/sdf/macros.pl perllib/sdf/misc.pl perllib/sdf/name.pl perllib/sdf/parse.pl perllib/sdf/podmacs.pl perllib/sdf/post_htx.pl perllib/sdf/post_mf6.pl perllib/sdf/sdfget.pl perllib/sdf/specials.pl perllib/sdf/subs.pl perllib/sdf/table.pl perllib/sdf/tests.pl perllib/sdf/toexpand.pl perllib/sdf/tohtml.pl perllib/sdf/tolatex.pl perllib/sdf/tomif.pl perllib/sdf/topod.pl perllib/sdf/toraw.pl perllib/sdf/tosgml.pl perllib/sdf/totxt.pl perllib/sdf/values.pl t/TEST t/doatest.clone t/doatest.pl t/doatest.templ t/filter/about.sdf t/filter/about.t t/filter/address.sdf t/filter/address.t t/filter/appendix.sdf t/filter/appendix.t t/filter/checked/about.log t/filter/checked/about.out t/filter/checked/address.log t/filter/checked/address.out t/filter/checked/appendix.log t/filter/checked/appendix.out t/filter/checked/comment.log t/filter/checked/comment.out t/filter/checked/default.log t/filter/checked/default.out t/filter/checked/define.log t/filter/checked/define.out t/filter/checked/end.log t/filter/checked/end.out t/filter/checked/example.log t/filter/checked/example.out t/filter/checked/front.log t/filter/checked/front.out t/filter/checked/inline.log t/filter/checked/inline.out t/filter/checked/parastyl.log t/filter/checked/parastyl.out t/filter/checked/plain.log t/filter/checked/plain.out t/filter/checked/script.log t/filter/checked/script.out t/filter/checked/sdf.log t/filter/checked/sdf.out t/filter/checked/table.log t/filter/checked/table.out t/filter/comment.sdf t/filter/comment.t t/filter/default.sdf t/filter/default.t t/filter/define.sdf t/filter/define.t t/filter/end.sdf t/filter/end.t t/filter/example.sdf t/filter/example.t t/filter/front.sdf t/filter/front.t t/filter/inline.sdf t/filter/inline.t t/filter/parastyl.sdf t/filter/parastyl.t t/filter/plain.sdf t/filter/plain.t t/filter/script.sdf t/filter/script.t t/filter/sdf.sdf t/filter/sdf.t t/filter/table.sdf t/filter/table.t t/general/checked/expr.log t/general/checked/expr.out t/general/checked/formats.log t/general/checked/formats.out t/general/checked/lineno.log t/general/checked/lineno.out t/general/checked/macro.log t/general/checked/macro.out t/general/checked/para1.log t/general/checked/para1.out t/general/checked/para2.log t/general/checked/para2.out t/general/checked/phrase.log t/general/checked/phrase.out t/general/checked/zero.log t/general/checked/zero.out t/general/expr.sdf t/general/expr.t t/general/formats.sdf t/general/formats.t t/general/lineno.sdf t/general/lineno.t t/general/macro.sdf t/general/macro.t t/general/para1.sdf t/general/para1.t t/general/para2.sdf t/general/para2.t t/general/phrase.sdf t/general/phrase.t t/general/zero.sdf t/general/zero.t t/html/checked/lists.html t/html/lists.sdf t/html/lists.t t/macro/block.sdf t/macro/block.t t/macro/catalog.sdf t/macro/catalog.t t/macro/cell.sdf t/macro/cell.t t/macro/checked/block.log t/macro/checked/block.out t/macro/checked/catalog.log t/macro/checked/catalog.out t/macro/checked/cell.log t/macro/checked/cell.out t/macro/checked/class.log t/macro/checked/class.out t/macro/checked/default.log t/macro/checked/default.out t/macro/checked/define.log t/macro/checked/define.out t/macro/checked/else.log t/macro/checked/else.out t/macro/checked/elsif.log t/macro/checked/elsif.out t/macro/checked/endblock.log t/macro/checked/endblock.out t/macro/checked/endif.log t/macro/checked/endif.out t/macro/checked/endmacro.log t/macro/checked/endmacro.out t/macro/checked/endtable.log t/macro/checked/endtable.out t/macro/checked/execute.log t/macro/checked/execute.out t/macro/checked/export.log t/macro/checked/export.out t/macro/checked/if.log t/macro/checked/if.out t/macro/checked/include.log t/macro/checked/include.out t/macro/checked/inherit.log t/macro/checked/inherit.out t/macro/checked/init.log t/macro/checked/init.out t/macro/checked/insert.log t/macro/checked/insert.out t/macro/checked/line.log t/macro/checked/line.out t/macro/checked/macro.log t/macro/checked/macro.out t/macro/checked/on_para.log t/macro/checked/on_para.out t/macro/checked/on_phras.log t/macro/checked/on_phras.out t/macro/checked/row.log t/macro/checked/row.out t/macro/checked/slide.log t/macro/checked/slide.out t/macro/checked/table.log t/macro/checked/table.out t/macro/checked/undef.log t/macro/checked/undef.out t/macro/class.sdf t/macro/class.t t/macro/default.sdf t/macro/default.t t/macro/define.sdf t/macro/define.t t/macro/else.sdf t/macro/else.t t/macro/elsif.sdf t/macro/elsif.t t/macro/endblock.sdf t/macro/endblock.t t/macro/endif.sdf t/macro/endif.t t/macro/endmacro.sdf t/macro/endmacro.t t/macro/endtable.sdf t/macro/endtable.t t/macro/execute.sdf t/macro/execute.t t/macro/export.sdf t/macro/export.t t/macro/if.sdf t/macro/if.t t/macro/include.sdf t/macro/include.t t/macro/inherit.sdf t/macro/inherit.t t/macro/init.sdf t/macro/init.t t/macro/insert.sdf t/macro/insert.t t/macro/line.sdf t/macro/line.t t/macro/macro.sdf t/macro/macro.t t/macro/on_para.sdf t/macro/on_para.t t/macro/on_phras.sdf t/macro/on_phras.t t/macro/row.sdf t/macro/row.t t/macro/slide.sdf t/macro/slide.t t/macro/table.sdf t/macro/table.t t/macro/undef.sdf t/macro/undef.t t/sdftest t/sdftest.bat perllib/sdf/filters.pl perllib/sdf/find.pl perllib/sdf/home/images/arrow.bmp perllib/sdf/home/images/arrow.gif perllib/sdf/home/images/back.bmp perllib/sdf/home/images/back.gif perllib/sdf/home/images/bar1.bmp perllib/sdf/home/images/bar1.gif perllib/sdf/home/images/bg_ball.bmp perllib/sdf/home/images/bg_ball.gif perllib/sdf/home/images/bk_diam.bmp perllib/sdf/home/images/bk_diam.gif perllib/sdf/home/images/camera1.bmp perllib/sdf/home/images/camera1.gif persdf-2.001/PODDIFFS010064400042570001753000000101730635706740200132520ustar00iancmtr00000400000236perl.pod: 0 paragraphs differ perlapio.pod: 0 paragraphs differ perlbook.pod: 0 paragraphs differ perlbot.pod: 0 paragraphs differ perlcall.pod: 0 paragraphs differ perldata.pod: 1 paragraphs differ *** paragraph 50 - character 557 *** --- 267 --- You can also embed newlines directly in your strings, i.e., they can end on a different line than they begin. This is nice, but if you forget your trailing quote, the error will not be reported until Perl finds another line containing the quote character, which may be much further on in the script. Variable substitution inside strings is limited to scalar variables, arrays, and array slices. (In other words, names beginning with $ or @, followed by an optional bracketed expression as a subscript.) The following code segment prints out "The price is $100." --- 264 --- You can also embed newlines directly in your strings, i.e., they can end on a different line than they begin. This is nice, but if you forget your trailing quote, the error will not be reported until Perl finds another line containing the quote character, which may be much further on in the script. Variable substitution inside strings is limited to scalar variables, arrays, and array slices. (In other words, names beginning with $ or @, followed by an optional bracketed expression as a subscript.) The following code segment prints out "The price is $Z<>100." perldebug.pod: 0 paragraphs differ perldelta.pod: 0 paragraphs differ perldiag.pod: 0 paragraphs differ perldsc.pod: 0 paragraphs differ perlembed.pod: 0 paragraphs differ perlfaq.pod: 0 paragraphs differ perlfaq1.pod: 0 paragraphs differ perlfaq2.pod: 0 paragraphs differ perlfaq3.pod: 0 paragraphs differ perlfaq4.pod: 1 paragraphs differ *** paragraph 120 - character 197 *** --- 377 --- If you want to represent quotation marks inside a quotation-mark-delimited field, escape them with backslashes (eg, C<"like \"this\""). Unescaping them is a task addressed earlier in this section.> --- 376 --- If you want to represent quotation marks inside a quotation-mark-delimited field, escape them with backslashes (eg, C<"like \"this\""). Unescaping them is a task addressed earlier in this section. perlfaq5.pod: 0 paragraphs differ perlfaq6.pod: 0 paragraphs differ perlfaq7.pod: 0 paragraphs differ perlfaq8.pod: 0 paragraphs differ perlfaq9.pod: 0 paragraphs differ perlform.pod: 0 paragraphs differ perlfunc.pod: 0 paragraphs differ perlguts.pod: 0 paragraphs differ perlipc.pod: 0 paragraphs differ perllocale.pod: 0 paragraphs differ perllol.pod: 0 paragraphs differ perlmod.pod: 0 paragraphs differ perlmodlib.pod: 0 paragraphs differ perlobj.pod: 0 paragraphs differ perlop.pod: 0 paragraphs differ perlpod.pod: 0 paragraphs differ perlre.pod: 0 paragraphs differ perlref.pod: 0 paragraphs differ perlrun.pod: 0 paragraphs differ perlsec.pod: 0 paragraphs differ perlstyle.pod: 0 paragraphs differ perlsub.pod: 0 paragraphs differ perlsyn.pod: 0 paragraphs differ perltie.pod: 0 paragraphs differ perltoot.pod: 1 paragraphs differ *** paragraph 338 - character 1 *** --- 1759 --- From the C++ perspective, all methods in Perl are virtual. This, by the way, is why they are never checked for function prototypes in the argument list as regular builtin and user-defined functions can be. --- 1737 --- Z<>From the C++ perspective, all methods in Perl are virtual. This, by the way, is why they are never checked for function prototypes in the argument list as regular builtin and user-defined functions can be. perltrap.pod: 0 paragraphs differ perlvar.pod: 3 paragraphs differ *** paragraph 39 - character 2 *** --- 107 --- =item $> --- 106 --- =back *** paragraph 40 - character 1 *** --- 112 --- Contains the subpattern from the corresponding set of parentheses in the last pattern matched, not counting patterns matched in nested blocks that have been exited already. (Mnemonic: like \digit.) These variables are all read-only. --- 108 --- =over 8 *** paragraph 41 - character 8 *** --- 114 --- =item $MATCH --- 110 --- =item $> perlxs.pod: 0 paragraphs differ perlxstut.pod: 0 paragraphs differ *** SUMMARY *** Total files: 45 Total paras: 11345 Total diffs: 6 Total resync failures: 2 PERCENT OK: 99.95% ide strings is limited to scalar variables, arrays, and array slices. (In other words, names beginning with $ or @, followed by an optional bracketed expression as a subscript.) The following code segment prints out "The price is $Z<>100." perldebug.pod: 0 paragraphs differ perldelta.pod: 0 paragraphs differ perldiag.pod: 0 paragraphs differ perldsc.pod: 0 paragraphs differ perlembed.posdf-2.001/LICENSE010064400042570001753000000040760630244570600131400ustar00iancmtr00000400000236Copyright (C) 1992-1997, Ian Clatworthy (ianc@mincom.com) All rights reserved. The author of this package is Ian Clatworthy (ianc@mincom.com). This package can be distributed free for commercial and non-commercial use as long as the following conditions are adhered to. The following conditions apply to all the components found in this distribution. Copyright remains the author's and any Copyright notices in the software are not to be removed. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code and documentation must retain the copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS PACKAGE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. The license and distribution terms for any publically available version or derivative of this package cannot be changed. i.e. this package cannot simply be copied and put under another distrubution license [including the GNU Public License.] If you wish to use this package and are unsure what the conditions above mean, send me email and we can sort it out. Ian Clatworthy ianc@mincom.com Brisbane, Australia +61 7 3303 3333 sdf-2.001/README010064400042570001753000000057160661525317200130160ustar00iancmtr00000400000236Welcome to SDF (Simple Document Format) 2.001beta1 ================================================== What is SDF? ------------ SDF (Simple Document Format) is a freely available document development system which generates high quality outputs in a variety of formats from a single source. The output formats supported include PostScript(tm), PDF, HTML, plain text, POD, man pages, LaTeX, MIF, SGML, Windows(tm) help, RTF, MIMS F6 help and MIMS HTX help. If the idea of specifying documents in a logical manner via a simple markup language sounds appealing, SDF may be useful to you. SDF documents are simple to create and maintain, minimising the time spent on documentation. In particular, SDF directly supports the creation and maintenance of large, on-line documentation systems (including intranets) via centralised hypertext management and rule-based hypertext generation. As well as normal documents, SDF is useful for: * user manuals (paper-based and online) * online document catalogs * Perl module documentation * Delphi(tm) component documentation * source code listings (pretty printing most languages). SDF is also good for literate programming, i.e. documentation can be embedded in the comments of most programming languages and can be selectively extracted. The embedded documentation can be in any markup language you like, although there are advantages to using SDF's markup language. SDF is freely available for commercial and non-commercial use. See the LICENSE file for details. Requirements ------------ SDF has been completely developed in Perl, a popular and highly portable scripting language. Perl 5.004 or later is recommended, although SDF will probably run on earlier versions of Perl 5. To generate PostScript, SDF requires one of the following: * the freely available pod2ps program * the freely available SGML-Tools and LaTeX packages * FrameMaker 5.x or later * a word processor which can import RTF. Earlier versions of FrameMaker will generally work, but I don't explicitly support them. To generate PDF, Adobe's Acrobat is recommended. To generate Windows help, a help compiler (e.g. hcp.exe) is required. Installation ------------ Installation instructions are provided in the INSTALL file. These instructions are also provided in the "SDF User Guide" (http://www.mincom.com/mtr/sdf/user/in_insta.html). Further Information ------------------- For the latest information and further details on SDF, see the SDF home page (http://www.mincom.com/mtr/sdf/). The following mailing lists are available: * sdf-users@mincom.com - for general questions * sdf-bugs@mincom.com - for reporting bugs and fixes. To subscribe to these lists, send email to sdf-users-request@mincom.com and/or sdf-bugs-request@mincom.com for instructions on using factotum, the majordomo variant that manages these lists. In short, send email to factotum@mincom.com with a message body of "subscribe sdf-users" or "subscribe sdf-bugs". Share and enjoy, Ian Clatworthy ianc@mincom.com 27-Oct-98 sdf-2.001/MANIFEST.SKIP010064400042570001753000000001240647545277200140330ustar00iancmtr00000400000236Makefile$ \.ps$ \.pdf$ \.old$ \.bak$ \.orig$ pm_to_blib$ ^sdf.prj$ ^\.sdf.prcs_aux$