1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
|
# coding: utf-8
=begin
* Name: SiSU
* Description: a framework for document structuring, publishing and search
* Author: Ralph Amissah
* Copyright: (C) 1997 - 2009 Ralph Amissah All Rights Reserved.
* License: GPL 3 or later:
SiSU, a framework for document structuring, publishing and search
Copyright (C) Ralph Amissah
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your option)
any later version.
This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.
You should have received a copy of the GNU General Public License along with
this program. If not, see <http://www.gnu.org/licenses/>.
If you have Internet connection, the latest version of the GPL should be
available at these locations:
<http://www.fsf.org/licensing/licenses/gpl.html>
<http://www.gnu.org/licenses/gpl.html>
<http://www.jus.uio.no/sisu/gpl.fsf/toc.html>
<http://www.jus.uio.no/sisu/gpl.fsf/doc.html>
<http://www.jus.uio.no/sisu/gpl.fsf/plain.txt>
* SiSU uses:
* Standard SiSU markup syntax,
* Standard SiSU meta-markup syntax, and the
* Standard SiSU object citation numbering and system
* Hompages:
<http://www.jus.uio.no/sisu>
<http://www.sisudoc.org>
* Download:
<http://www.jus.uio.no/sisu/SiSU/download.html>
* Ralph Amissah
<ralph@amissah.com>
<ralph.amissah@gmail.com>
** Description: interactive infomation/help
=end
module SiSU_Help
require "#{SiSU_lib}/sysenv"
require "#{SiSU_lib}/param"
include SiSU_Screen
class Help
def initialize(request='',color='')
@request,@color=request,color
if color =~/color_off/; @cX=SiSU_Screen::Ansi.new('k').cX
else @cX=SiSU_Screen::Ansi.new('yes').cX
end
fns='help_example_dummy_file_name.sst'
@env=SiSU_Env::Info_env.new(fns)
@db=SiSU_Env::Info_db.new
m=/.+\/(?:src\/)?(\S+)/im # m=/.+?\/(?:src\/)?([^\/]+)$/im # m=/.+\/(\S+)/m
@output_stub=Dir.pwd[m,1]
end
def help_request
begin
gotten=nil
regx=/^(list|com(?:mands)?|mod(?:ifiers)|markup|syntax|example(?:37|38)?|head(?:ers?)?|(?:heading|title|level|structure)s?|endnotes|footnotes|tables?|customise|skin|dir(?:ectories)?|paths?|lang(?:uage)?|modules|setup|conf(?:ig(?:ure)?)?|standards?|li[cs]en[sc]e|scratch|install|termsheet|dublin(?:core)?|dc|customise|styles?|appearance|theme|env(ironment)?|dir(?:ector(?:y|ies))?|metaverse|abstract|features|summary|(?:short)?cuts?|sisu|about|ext(?:ernal)?(?:_?prog(?:rams)?)?)|utf-?8|plaintext|html|xml|xhtml|odf|odt|opendocument|css|pdf|latex|tex|(?:tex)?info|search|(?:hyper)?est(?:raier)?|searchform|cgi|sql|db|postgresql|pg?sql|sqlite|convert|php|webrick|sitemaps?|ya?ml|ansi|colors|-[AabcDdEeFHhIMmNnopqrRSstUuVvwXxyZz0-9]|-[Ddcv]|-[CcFLSVvW]/
help_info=%{#{@cX.blue_hi}SiSU help#{@cX.off} #{@cX.ruby}~#{@cX.off} #{@request}}
help_list=%{#{@cX.blue}sisu --help#{@cX.off} #{@cX.cyan}type keyword else "enter" to exit help:\n\tkeywords include:#{@cX.off} #{@cX.brown}list, (com)mands, short(cuts), (mod)ifiers, (env)ironment, markup, syntax, headers, headings, endnotes, tables, example, customise, skin, (dir)ectories, path, (lang)uage, db, install, setup, (conf)igure, convert, external_programs, dublincore, termsheet, search, sql, hyper(est)raier, features, external_programs, license#{@cX.off} \n}
help_prompt=%{#{@cX.fuschia}exit, [or carriage return to exit help] #{@cX.off}\n#{@cX.blue_hi}SiSU help#{@cX.off} #{@cX.ruby}~#{@cX.off} }
until gotten =~/exit|quit|bye|q|^\s*$/ \
and ( @request.nil? or @request.empty? )
@help=Help.new(@request,@color)
if @request
puts help_info
gotten=@request
@request=nil
end
case gotten
when /h((?:elp)| )|~/i
@help.summary
help_@request
when /list/; @help.summary
when /com(mands)?/; @help.commands
when /mod(ifiers)?/; @help.modifiers
when /markup|syntax/; @help.markup
when /example\b/; @help.example
when /example37/; @help.example37
when /example38/; @help.example38
when /(?:heading|title|level)s?|structure/; @help.headings
when /head(ers?)?/; @help.headers
when /dublin(core)?|dc/; @help.dublin_core
when /(?:foot|end)notes/; @help.endnotes
when /tables?/; @help.tables
when /customise|skin/; @help.customise
when /modules/; @help.modules
when /env(ironment)?/; @help.environment
when /dir(ector(y|ies))?/; @help.directories
when /paths?/; @help.path
when /setup/; @help.setup
when /conf(?:ig(?:ure)?)?/; @help.configure
when /standards?/; @help.standards
when /lang(?:uage)?/; @help.languages
when /li[cs]en[sc]e/; @help.license
when /scratch/; @help.scratch
when /install/; @help.install
when /termsheet/; @help.termsheet
when /customise|styles?|appearance|theme/; @help.customise
when /metaverse/; @help.dal
when /plaintext|ascii|-[aAeE]/; @help.plaintext
when /utf-?8/i; @help.utf8
when /html|-[hH]/; @help.html
when /css/; @help.css
when /xhtml|-b/; @help.xhtml
when /xml|-[xX]/; @help.xml
when /odf|odt|opendocument|-o/; @help.odf
when /php/; @help.php
when /pdf|-p/; @help.pdf
when /latex|tex/; @help.latex
when /(tex)?info/; @help.texinfo
when /lout/; @help.lout
when /concordance|index|-w/; @help.concordance
when /search\b/; @help.help_search
when /(?:hyper)?est(?:raier)?/; @help.hyperestraier
when /db|database|sql|postgresql|sqlite|pg?sql|-[dD]/; @help.sql
when /searchform|cgi/; @help.cgi
when /convert/; @help.convert
when /webrick|-W/; @help.webrick
when /abstract|features|summary|about|sisu/; @help.abstract
when /ext(?:ernal)?(?:_?prog(?:rams)?)?/; @help.external_programs
when /ya?ml/; @help.yaml
when /sitemaps?/; @help.sitemap
when /(?:short)?cuts?/; @help.shortcuts
when /ansi|colors?/; SiSU_Screen::Ansi.new('c').colors
else @help.summary
end
print help_list
print help_prompt
gotten=nil
gotten=gets
end
rescue
#STDERR.puts Ansi.new($!, $@).rescue
# dies silently... for now, silence of use in connection with "sisu ~ commands" etc.
ensure
end
end
def summary
print <<WOK
SiSU, Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Ralph Amissah
License GPL version 3 or Later. This program comes with ABSOLUTELY NO WARRANTY;
This is free software, and you are welcome to redistribute it under the conditions of the GPL3 or later.
For more license detail type/enter: "sisu --help license"
for help type 'sisu --help', 'sisu --help [help request]', 'man sisu', (or see the system or online documentation)
typing "sisu" on its own or "sisu --help", should give you this sisu help summary and the sisu (interactive help mode) help prompt, from which help on each keyword can be obtained.
alternatively typing #{@cX.orange}sisu --help#{@cX.off} #{@cX.green}[keyword]#{@cX.off} at the command prompt will provide the sisu help page requested and return to the command prompt (if nothing is found it will print this page and return to the command prompt)
Keywords (related to using SiSU)
#{@cX.green}help#{@cX.off} or #{@cX.green}list#{@cX.off} this sisu help summary
#{@cX.green}commands#{@cX.off} sisu --help commands
#{@cX.green}environment#{@cX.off} sisu --help env
------------------------------------------
Preparing Documents for SiSU
#{@cX.green}markup#{@cX.off} sisu --help markup (an incomplete overview)
#{@cX.green}headers#{@cX.off} sisu --help headers (document-wide instructions, meta-data)
#{@cX.green}structure#{@cX.off} sisu --help structure (document structure, headings, tables of contents)
#{@cX.green}endnotes#{@cX.off} sisu --help endnotes
#{@cX.green}tables#{@cX.off} sisu --help tables
#{@cX.green}example 0.37#{@cX.off} sisu --help example37
#{@cX.green}example 0.38#{@cX.off} sisu --help example
------------------------------------------
#{@cX.green}search#{@cX.off} sisu --help search
------------------------------------------
#{@cX.green}customise#{@cX.off} sisu --help customise
------------------------------------------
SiSU's License
#{@cX.green}license#{@cX.off} sisu --help license
for help type 'sisu --help', 'sisu --help [help request]', 'man sisu', (or see the system or online documentation)
WOK
# #{@cX.cyan}sisu_convert#{@cX.off} program for initial (very basic and partial) conversion to sisu file format (html and word97 supported)
end
def abstract
print <<WOK
Features:
#{@cX.cyan}(i)#{@cX.off} minimal markup requirement
#{@cX.cyan}(ii)#{@cX.off} single file marked up for multiple outputs
#{@cX.cyan}(iii)#{@cX.off} markup is simpler than html
#{@cX.cyan}(iv)#{@cX.off} the simple syntax is mnemonic, influenced by mail/messaging/wiki markup practices
#{@cX.cyan}(v)#{@cX.off} human readable, and easily writable
#{@cX.cyan}(vi)#{@cX.off} multiple outputs include amongst others: html; pdf via LaTeX; (structured) XML; sql - currently PostgreSQL and sqlite; plaintext, (also texinfo)
#{@cX.cyan}(vii)#{@cX.off} all text objects (headings and paragraphs) are numbered identically, for citation purposes, in all outputs (html, pdf, sql etc.)
#{@cX.cyan}(viii)#{@cX.off} creates organised directory/file structure for output
#{@cX.cyan}(ix)#{@cX.off} easily mapped with its clearly defined structure, with all text objects numbered, you know in advance where in each document output type, a bit of text will be found (eg. from an sql search, you know where to go to find the prepared html output or pdf etc.)... there is more
#{@cX.cyan}(x)#{@cX.off} use of Dublin Core and other meta-tags to permit the addition of some semantic information on documents, and making easy integration of rdf/rss feeds etc.
#{@cX.cyan}(xi)#{@cX.off} very easily skinnable, document appearance on a project/site wide, or document instance level easily controlled/changed
#{@cX.cyan}(xii)#{@cX.off} in many cases a regular expression may be used (once in the document header) to define all or part of a documents structure obviating or reducing the need to provide structural markup within the document
#{@cX.cyan}(xiii)#{@cX.off} is a batch processor for handling large document sets, ... though once generated they need not be re-generated, unless changes are made to the desired presentation of a particular output type
#{@cX.cyan}(xiv)#{@cX.off} possible to pre-process, which permits the easy creation of standard form documents, and templates/term-sheets
#{@cX.cyan}(xv)#{@cX.off} extremely modular, (thanks in no small part to Ruby) another output format required, write another module....
#{@cX.cyan}(xvi)#{@cX.off} easy to update output formats (eg html, xhtml, latex/pdf produced can be updated in program and run against whole document set)
#{@cX.cyan}(xvii)#{@cX.off} easy to add, modify, or have alternative syntax rules for input, should you need to
#{@cX.cyan}(xviii)#{@cX.off} "Concordance" wordmap, consisting of all the words in a document and their (text object) locations within the text
#{@cX.cyan}(xix)#{@cX.off} tied to revision control system, only code and marked up file need be backed up, to be sure of the much larger document set
#{@cX.cyan}(xx)#{@cX.off} syntax highlighting files for markup, primarily (g)vim so far.
SiSU was developed in relation to legal documents, and so is strong across a wide variety of texts (law, literature...), though weak on formulae/statistics, it does handle images. An assumption has been document sets that are to be preserved and maintained over time (also a result of the legal text origin). SiSU has been developed and used over a number of years, and the requirements to cover a wide range of documents have been thoroughly explored.
There is more detailed information available on it from:
#{@cX.blue}http://www.jus.uio.no/sisu#{@cX.off}
* plaintext
* html
* XML (structured)
* LaTeX/pdf
* texinfo
* sql (at present postgresql & sqlite)
A couple of sample inputs and outputs:
The markup for "War and Peace" (chosen because it is a large text & to test the use of SiSU on Project Gutenberg's plaintext), this is the markup, very little after the headers (there is an insert of their legal notices). Took no time at all, it is a particularly simple text to markup though
A simple document and a more demanding document
#{@cX.blue}http://www.jus.uio.no/sisu/sample/war.and.peace.leo.tolstoy.er20 http://www.jus.uio.no/sisu/sample/autonomy.markup1.er30#{@cX.off}
Some resulting outputs:
html #{@cX.blue}http://www.jus.uio.no/sisu/war.and.peace.leo.tolstoy/ http://www.jus.uio.no/sisu/autonomy.markup1/#{@cX.off}
#{@cX.blue}http://www.jus.uio.no/sisu/autonomy.markup1/doc#{@cX.off}
pdf #{@cX.blue}http://www.jus.uio.no/sisu/war.and.peace.leo.tolstoy/portrait http://www.jus.uio.no/sisu/autonomy.markup1/portrait
#{@cX.blue}http://www.jus.uio.no/sisu/war.and.peace.leo.tolstoy/landscape http://www.jus.uio.no/sisu/autonomy.markup1/landscape#{@cX.off}
plaintext #{@cX.blue}http://www.jus.uio.no/sisu/war.and.peace.leo.tolstoy/doc.txt http://www.jus.uio.no/sisu/autonomy.markup1/doc.txt#{@cX.off}
WOK
end
def commands
print <<WOK
#{@cX.ruby}-a#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces plaintext with Unix linefeeds. Without markup, (object numbers are omitted), has footnotes at end of each para‐ graph that contains them. Modifier options available: --footnotes (default) or --endnotes and for linefeeds --unix (default) or --msdos
#{@cX.ruby}-b#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces xhtml/XML output for browser viewing (sax parsing)
#{@cX.ruby}-C#{@cX.off} initialise shared output directory (config files such as css and dtd files are not updated if they already exist unless modifier is used) #{@cX.ruby}-C --init=site#{@cX.off} configure/initialise site more extensive than -C on its own, shared output directory files/force update, existing shared output config files such as css and dtd files are updated if this modifier is used. in a new markup document working directory should initialise the corresponding output directory, though SiSU will automatically do this, the first time it is run (for processing) in a given directory.
#{@cX.ruby}-c#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} screen toggle ansi screen colour on or off depending on default set (unless -c flag is used: if sisurc colour default is set to ´true´, output to screen will be with colour, if sisurc colour default is set to ´false´ or is undefined screen output will be without colour)
#{@cX.ruby}-D#{@cX.off} #{@cX.green}[instruction]#{@cX.off} #{@cX.green}[filename]#{@cX.off} database instruction, see database section below
#{@cX.ruby}-d#{@cX.off} #{@cX.green}[instruction]#{@cX.off} #{@cX.green}[filename]#{@cX.off} database instruction, see database section below [only -D currently available]
#{@cX.ruby}-F#{@cX.off} generate examples of (naive) cgi search form for sqlite and pgsql depends on your already having used sisu to populate an sqlite and/or pgsql database, (the sqlite version scans the output directories for existing sisu_sqlite databases, so it is first necessary to create them, before generating the search form) see -d -D and the database section below. If the optional parameter webrick is passed, the cgi examples created will be set up to use the default port set for use by the webrick server, (otherwise the port is left blank and the system setting used, usually 80). The samples are dumped in the present work directory which must be writable, (with screen instructions given that they be copied to the cgi-bin directory).
#{@cX.ruby}-H#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces html (css version) (creates html (using css)), with url link suffixes (.html .pdf etc.) omitted ("Hide"). For web servers that are confireud so as not to require file extensions to locate and serve files. [behaviour switched see -h]
#{@cX.ruby}-h#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces html (hardlinks i.e. with name suffixes in links/local urls). html, with internal document links that include the document suffix, ie whether it is .html or .pdf (required for browsing directly off a file system, and works with most web servers). [behaviour switched see -H]
#{@cX.ruby}-I#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces texinfo file with its myriad of possibilities
#{@cX.ruby}-L#{@cX.off} prints license information
#{@cX.ruby}-M#{@cX.off} #{@cX.green}[filename/wildcard/url]#{@cX.off} maintenance mode, files created for processing are not deleted, and their locations are indicated (also see -V)
#{@cX.ruby}-m#{@cX.off} #{@cX.green}[filename/wildcard/url]#{@cX.off} create (new)metaVerse (used in all subsequent processing). Produce a meta file, the first step in processing, and the file all subsequent processing utilize. (Should usually be run together with other commands to ensure that the lated version of markup source document is used, i.e. add -m flag to other flags required).
#{@cX.ruby}-N#{@cX.off} #{@cX.green}[filename/wildcard/url]#{@cX.off} document content certificate as md5 digest tree of document produced (as digest.txt), the digest for the document, and digests for each object contained within the document (together with information on software versions that produced it). Try -mNV for verbose digest output to screen
#{@cX.ruby}-n#{@cX.off} #{@cX.green}[filename/wildcard/url]#{@cX.off} skip meta-markup (building of "metaverse"), this skips the equivalent of -m
#{@cX.ruby}-p#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces LaTeX pdf (portrait & landscape). Default paper size is set in config file, or document header, or provided with additional command line parameter, e.g. --papersize='a4' preset sizes include: 'A4', U.S. 'letter' and 'legal' and book sizes 'A5' and 'B5' (system defaults to A4).
#{@cX.ruby}-q#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} quiet, less output to screen
#{@cX.ruby}-r#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} copies sisu output files to remote host using scp (default). This requires that sisurc.yml has been provided with information on hostname and user name, and that you have your "keys" and ssh agent in place.
#{@cX.ruby}-S#{@cX.off} #produces a sisupod, a zipped sisu directory of markup files including sisu markup source files and the directories local configuration file, images and skins. Note: this only includes the configuration files or skins contained in ./_sisu not those in ~/.sisu The resulting tar gzip file has a .zip suffix added to the markup source directory name. To tar and gzip individual files see the -Z [filename/wildcard] option. Note: (this option is tested only with zsh)
#{@cX.ruby}-S#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces a sisupod a zipped sisu of the content assocated with the specified sisu markup documnt, i.e. including sisu markup source file, (and associated documents if a master file, or available in multilingual versions), together with related images and skin. The resulting zipped file has a .zip suffix added to the markup source file name by default, though a .ssp suffix is also recognised. The directory structure of the unzipped file is understood by sisu, and sisu commands can be run within it. SiSU commands can be run against a sisupod contained in a local directory, or provided as a url on a remote site. As there is a security issue with skins provided by other users, they are not applied unless the flag --trust or --trusted is added to the command instruction, it is recommended that file that are not your own are treated as untrusted. This provides a convenient way of packing documents files for sending Note: if you wish to send multiple files, it quickly becomes more space efficient to tar and gzip the sisu markup directory, (without the _sisu_processing subdirectory) rather than the individual files for sending). See the -S option without [filename/wildcard]
#{@cX.ruby}-t#{@cX.off} #{@cX.green}[filename/wildcard (*.termsheet.rb)]#{@cX.off} standard form document builder, preprocessing feature
#{@cX.ruby}-U#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} prints url list/map for the available processing flags options and resulting files that could be requested, (can be used to get a list of processing options in relation to a file, together with information on the output that would be produced), -u provides url mapping for those flags requested for processing. The default assumes sisu_webrick is running and provides webrick url mappings where appropriate, but these can be switched to file system paths in sisurc.yml
#{@cX.ruby}-u#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} provides url mapping of output files for the flags requested for processing, also see -U
#{@cX.ruby}-V#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} on its own provides SiSU version and environment information (sisu --help env)
#{@cX.ruby}-V#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} even more verbose than -v the -V flag provides some additional information, also see -M
#{@cX.ruby}-v#{@cX.off} on its own, provides SiSU version information.
#{@cX.ruby}-v#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} provides more verbose output of what is being built, where it is being built (and error messages if any), as with -u flag provides a url mapping of files created for each of the processing flag requests
#{@cX.ruby}-X#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces XML output with deep document structure, in the nature of dom
#{@cX.ruby}-x#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces XML output (sax parsing)
#{@cX.ruby}-W#{@cX.off} #{@cX.green}[port]#{@cX.off} starts ruby´s webrick webserver, points at sisu output directories (default port is set)
#{@cX.ruby}-w#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces concordance, a rudimentary index of all the words in a document
#{@cX.ruby}-Z#{@cX.off} Zap, if used with other processing flags #{@cX.green}deletes output files#{@cX.off} of the type about to be processed, prior to processing. If -Z is used as the lone processing related flag (or in conjunction with a combination of -[mMvVq]), will remove the related document output directory.
#{@cX.ruby}-z#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces php (zend) [feature disabled, depreciated]
#{@cX.ruby}--harvest#{@cX.off} #{@cX.green}*.ss[tm]#{@cX.off} makes two lists of sisu output based on the sisu markup documents in a directory: list of author and authors works (year and titles), and; list by topic with titles and author. Makes use of header metadata fields (author, title, date, topic_register). Can be used with -M and -R flags.
#{@cX.ruby}databases#{@cX.off}
#{@cX.ruby}dbi - database interface -D or --pgsql set for postgresql -d or --sqlite set for sqlite#{@cX.off}
#{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--create#{@cX.off} creates empty postgresql db and required tables & indexes (rb.dbi) [#{@cX.ruby}-d --create#{@cX.off} sqlite equivalent] it may be necessary to first run sisu #{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--createdb#{@cX.off}
#{@cX.ruby}-Di#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} or #{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--import#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} imports data specified to postgresql db (rb.dbi) [#{@cX.ruby}-d --import#{@cX.off} sqlite equivalent]
#{@cX.ruby}-Du#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} or #{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--update#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} updates/imports specified data to postgresql db (rb.dbi) [#{@cX.ruby}-d --update#{@cX.off} sqlite equivalent]
#{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--remove#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} removes specified data to postgresql db (rb.dbi) [#{@cX.ruby}-d --remove#{@cX.off} sqlite equivalent]
#{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--dropall#{@cX.off} kills data" and drops (postgresql) db, tables & indexes [#{@cX.ruby}-d --dropall#{@cX.off} sqlite equivalent]
#{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--recreate#{@cX.off} kills data" and drops (postgresql or sqlite) db, tables & indexes, then creates an empty db with tables and indexes [#{@cX.ruby}-d --recreate#{@cX.off} sqlite equivalent]
also see command #{@cX.green}shortcuts#{@cX.off}, and shorthand mappings for multiple flags
WOK
end
def shortcuts
cf_defaults=SiSU_Env::Info_processing_flag.new
print <<WOK
#{@cX.ruby}Shorthand for multiple flags#{@cX.off}
#{@cX.ruby}--update#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} Checks existing file output and runs the flags required to update this output. This means that if only html and pdf output was requested on previous runs, only the -hp files will be applied, and only these will be generated this time, together with the summary. This can be very convenient, if you offer different outputs of different files, and just want to do the same again.
#{@cX.ruby}-1#{@cX.off} to #{@cX.ruby}-5#{@cX.off} #{@cX.green}[filename or wildcard]#{@cX.off}
#{@cX.green}Default shorthand mappings#{@cX.off} (note that the defaults can be changed in the #{@cX.green}sisurc.yml#{@cX.off} file):
(these can be turned off if unavailable in sisurc.yml under program_set:)
#{@cX.green}processing shortcut defaults set to:#{@cX.off}
color defaut set (on==true) #{@cX.blue}#{cf_defaults.color}#{@cX.off}
sisu -1 #{@cX.blue}#{cf_defaults.cf_1}#{@cX.off}
sisu -2 #{@cX.blue}#{cf_defaults.cf_2}#{@cX.off}
sisu -3 #{@cX.blue}#{cf_defaults.cf_3}#{@cX.off}
sisu -4 #{@cX.blue}#{cf_defaults.cf_4}#{@cX.off}
sisu -5 #{@cX.blue}#{cf_defaults.cf_5}#{@cX.off}
defaults may be changed in active sisurc.yml file under 'flag:'
add -v for verbose mode and -c (color toggle), e.g.
sisu -2vc [filename or wildcard]
WOK
end
def modifiers
print <<WOK
#{@cX.ruby}Command flag modifiers#{@cX.off}
#{@cX.ruby}--no-ocn#{@cX.off} [with -h -H or -p] switches off object citation numbering. Produce output without identifying numbers in margins of html or LaTeX/pdf output.
#{@cX.ruby}--no-annotate#{@cX.off} strips output text of editor endnotes~[* square brackets ]~ denoted by asterisk or dagger/plus sign
#{@cX.ruby}--no-asterisk#{@cX.off} strips output text of editor endnotes~[* square brackets ]~ denoted by asterisk
#{@cX.ruby}--no-dagger#{@cX.off} strips output text of editor endnotes~[+ square brackets ]~ denoted by dagger/plus sign
WOK
end
def misccom
<<WOK
#{@cX.cyan}misc#{@cX.off}
#{@cX.green}-s#{@cX.off} [filename or wildcard] #{@cX.green}spellcheck#{@cX.off} (aspell previously ispell
\t#{@cX.green}mailer examples#{@cX.off}
from vim mail.er10 (not gvim) issue command
\t:! ruby -S mailer.rb instruction/landscape|a4l|portrait|a4p/ email@address/alias subject line
\t:! ruby -S mailer.rb a4l ralph@amissah.com testing continues
from vim mail.er10 use your vim alias \\mail or \\mutt (modify command line as required)
#{@cX.green}feeds rss/rdf#{@cX.off}
#{@cX.blue}-R #{@cX.off} (yaml|rss) extraction of semantic data into yaml file for auto build of xml feeds (rss, rdf) #{@cX.fuschia}[work area]#{@cX.off}
#{@cX.green}-R #{@cX.off} yaml extraction of semantic data into yaml file for auto build of xml feeds (rss, rdf)
#{@cX.green}-R #{@cX.off} rss creates rss2.0 feed
WOK
end
def markup
print <<WOK
sisu
Note: files for SiSU should be in UTF-8 character encoding.
#{@cX.cyan}Data text markup#{@cX.off} (alternative to available html subset)
#{@cX.green}% SiSU 0.38#{@cX.off} [statement on first line of document, declared file-type identifier, SiSU markup document, markup used is version 0.38]
#{@cX.green}:A~#{@cX.off} heading/title [levels :A to :C available (and beneath that 1 to 6)]
#{@cX.green}1~#{@cX.off}filename heading [segmentation level, levels 1 to 6 available]
#{@cX.green}!{#{@cX.off}emphasis#{@cX.green}}!#{@cX.off}
#{@cX.green}*{#{@cX.off}bold text#{@cX.green}}*#{@cX.off}
#{@cX.green}_{#{@cX.off}underscore#{@cX.green}}_#{@cX.off}
#{@cX.green}/{#{@cX.off}italics#{@cX.green}}/#{@cX.off}
#{@cX.green}"{#{@cX.off}citation#{@cX.green}}"#{@cX.off}
#{@cX.green}^{#{@cX.off}superscript#{@cX.green}}^#{@cX.off}
#{@cX.green},{#{@cX.off}subscript#{@cX.green}},#{@cX.off}
#{@cX.green}+{#{@cX.off}inserted text#{@cX.green}}+#{@cX.off}
#{@cX.green}-{#{@cX.off}strikethrough#{@cX.green}}-#{@cX.off}
------------------------------------------
#{@cX.cyan}Indentation and bullets#{@cX.off}
#{@cX.green}_1#{@cX.off} indent paragraph one level
#{@cX.green}_2#{@cX.off} indent paragraph two steps
#{@cX.green}_*#{@cX.off} bullet text
#{@cX.green}_1*#{@cX.off} bullet text, first indent
------------------------------------------
#{@cX.cyan}Numbered List#{@cX.off} (not to be confused with headings/titles, (document structure))
#{@cX.green}##{@cX.off} numbered list numbered list 1., 2., 3, etc.
#{@cX.green}_##{@cX.off} numbered list numbered list indented second level a., b., c., d., etc.
------------------------------------------
#{@cX.cyan}Endnotes#{@cX.off}
#{@cX.green}~{#{@cX.off}footnote/endnote#{@cX.green}}~#{@cX.off} endnote#{@cX.green}~{#{@cX.off}self contained endnote marker & endnote in one#{@cX.green}}~#{@cX.off}
#{@cX.green}~{*#{@cX.off}asterisk footnote/endnote#{@cX.green}}~#{@cX.off}
editor's annotations, square bracket notes
#{@cX.green}~[*#{@cX.off}numbered asterisk footnote/endnote series#{@cX.green}]~#{@cX.off}
#{@cX.green}~[+#{@cX.off}numbered dagger/plus sign footnote/endnote series#{@cX.green}]~#{@cX.off}
---
alternative endnote pair notation
#{@cX.green}~^#{@cX.off} endnote marker
#{@cX.green}^~#{@cX.off} endnote text following the paragraph in which the marker occurs
------------------------------------------
#{@cX.cyan}Links#{@cX.off}
http://url.org on its own would be automatically marked up and hyperlinked to itself
#{@cX.green}{#{@cX.off} [text to link] #{@cX.green}}#{@cX.off}http://url.org
#{@cX.green}{#{@cX.off}image.png#{@cX.green}}#{@cX.off}http://url.org
#{@cX.green}{#{@cX.off}image.png#{@cX.green}}#{@cX.off}image #{@cX.green}{#{@cX.off}tux.png 64#{@cX.green}x#{@cX.off}80#{@cX.green}}#{@cX.off}image
Linked image example
#{@cX.green}{#{@cX.off} SiSU Geek Writer #{@cX.green}}#{@cX.off}http://www.jus.uio.no/sisu/ url example
#{@cX.green}{#{@cX.off}tux.png 64#{@cX.green}x#{@cX.off}80 "a better way" #{@cX.green}}#{@cX.off}http://www.jus.uio.no/sisu/ image example with all options (width x height)
Note: png and jpg support only (no gif support)
shortcut - hyper-linked text with endnote providing the url information
#{@cX.green}{~^#{@cX.off} [text to link] #{@cX.green}}#{@cX.off}http://url.org maps to #{@cX.green}{#{@cX.off} [text to link] #{@cX.green}}#{@cX.off}http://url.org #{@cX.green}~{#{@cX.off} http://url.org #{@cX.green}}~#{@cX.off}
produces hyper-linked text within a document/paragraph, with an endnote providing the url for the text location used in the hyperlink
shortcut:
#{@cX.green}{#{@cX.off} [text to link] #{@cX.green}[3sS]}#{@cX.off}markup_source_filename.sst
if a server host name has been provided/configured, will provide a list of available output types that would be generated using the shortcut command and the markup file provided, i.e. output generated using the command (as configured):
"sisu -3sS markup_source_filename.sst"
using server host, directory stub, filename to compose the link.
------------------------------------------
adding fixed names in html, manual location marker/tagging
#{@cX.green}*~[name]#{@cX.off} <a name="[name]">
------------------------------------------
#{@cX.green}~##{@cX.off} unnumbered paragraph (place marker at end of paragraph)
#{@cX.green}-##{@cX.off} unnumbered paragraph, delete when not required (place marker at end of paragraph) [used in dummy headings, eg. for segmented html]
------------------------------------------
manual page breaks (LaTeX/pdf)
#{@cX.green}<:pb>#{@cX.off} page break, which breaks a page, starting a new page in single column text and a new column in double column text
#{@cX.green}<:pn>#{@cX.off} page new, which starts a new page, in both single and double column text (leaving an empty column in double column text if necessary).
Note: page breaks are usually introduced to pdfs either as header instructions, indicating that pages should break at given levels
------------------------------------------
#{@cX.cyan}Composite documents#{@cX.off}
It is possible to build a document by creating a master document that requires other documents. The documents required may complete documents that could be generated independently, or they could be markup snippets, prepared so as to be easily available to be placed within another text. If the calling document is a master document (built mainly from other documents), it should be named with the suffix #{@cX.blue}.ssm#{@cX.off} Within this document you would provide information on the other documents that should be included within the text. These may be other documents that would be processed in a regular way, or markup bits prepared only for inclusion within a master document #{@cX.blue}.sst#{@cX.off} regular markup file, or #{@cX.blue}.ssi#{@cX.off} (insert/information) A secondary file of the composite document is built prior to processing with the same prefix and the suffix #{@cX.blue}.ssm.sst#{@cX.off}
#{@cX.cyan}#basic sisu markup alternatives#{@cX.off}
#{@cX.green}{#{@cX.off}filename.ssi#{@cX.green}}require#{@cX.off}
#{@cX.green}<< {#{@cX.off}filename.ssi#{@cX.green}}#{@cX.off}
#{@cX.cyan}#using textlink alternatives#{@cX.off}
#{@cX.green}|#{@cX.off}filename.ssi#{@cX.green}|@|^|require#{@cX.off}
#{@cX.green}<< |#{@cX.off}filename.ssi#{@cX.green}|@|^|#{@cX.off}
#{@cX.cyan}#using thlnk alternatives#{@cX.off}
#{@cX.green}<url:#{@cX.off}filename.ssi#{@cX.green}>require#{@cX.off}
#{@cX.green}<< <url:#{@cX.off}filename.ssi#{@cX.green}>#{@cX.off}
#{@cX.cyan}Composite documents - remote parts#{@cX.off}
Composite documents may be built from remote parts, by using the composite document syntax with a url. This makes sense using either sisu regular syntax (which is just a convenient way of marking up), or thlnk syntax, which also recognises remote urls, and permits hyperlinking ascii to the url location.
#{@cX.cyan}Remote documents#{@cX.off}
SiSU will download and process remote locations if a url is provided instead of a filename. [this at present works only for sisu markup files without images]
------------------------------------------
#{@cX.green}%#{@cX.off}#{@cX.off} add a comment to text, that will be removed prior to processing (place marker at beginning of line)
#{@cX.green}\\#{@cX.off}#{@cX.off} escape a sepcial character, whether general: { } < > or contextual special characters, (in combination with other characters) ~ - _ / % ^ and occasionally ! # + ,
#{@cX.green}%%#{@cX.off}#{@cX.off} same as above but recognised by vim folds for placing fold in document text, in addition to headers and headings
------------------------------------------
#{@cX.ruby}More HELP on Markup#{@cX.off} markup help is available on:
document wide instructions: headers (document structure)
general text markup: headings; endnotes; tables (which also includes a note on preformatted text)
configuration and customisation
document or site wide customisation: customise; skin
WOK
help_markup
# {../_sisu/image/tux.png http://www.jus.uio.no/sisu/ w=64 c=\"a better way\" }:image depreciated image eg
# <!image http://www.jus.uio.no/sisu/ ../_sisu/image/tux.png width=\"64\" height=\"80\" !> old form
end
def example
help_markup
end
def example37
print <<WOK
% SiSU 0.16 - 0.37
0~title Working Sample Document
0~subtitle Demonstrating markup
0~creator Ralph Amissah
0~date
0~markup num_top=4
0~bold [regular expression of words/phrases to be made bold]
0~italics [regular expression of words/phrases to italicise]
0~links { SiSU }http://www.jus.uio.no/sisu { FSF }http://www.fsf.org
1~ A Sample Document
2~ just for fun
4~ This is Chapter One or Article One
Ordinary Text follows here. The Title would be a Chapter or Article depending on the type of document you were working to produce.
4~ This would be Chapter Two or Article Two
And so on.
Assuming sisu is configured properly so it has been instructed where to put the work files and ouput files, you would generate this text once saved, with the suffix .sst if saved as example.sst, by typing sisu -mhwxp example.sst while in the directory in which the file is saved.
_1 -m initial processing, -h html (css based), -w concordance for html, -x xml, -p pdf output, generated via latex, there are of course additional options
_1 for a listing type: sisu ~ commands
_1 for an outline of sisu markup type: sisu ~ markup
The example ends here.
WOK
help_markup
end
def example38
print <<WOK
% SiSU 0.38
@title: Working Sample Document
@subtitle: Demonstrating markup
@creator: Ralph Amissah
@date:
@markup: num_top=4
@bold: [regular expression of words/phrases to be made bold]
@italics: [regular expression of words/phrases to italicise]
@links: { SiSU }http://www.jus.uio.no/sisu { FSF }http://www.fsf.org
:A~ A Sample Document
:B~ just for fun
1~ This is Chapter One or Article One
Ordinary Text follows here. The Title would be a Chapter or Article depending on the type of document you were working to produce.
1~ This would be Chapter Two or Article Two
And so on.
Assuming sisu is configured properly so it has been instructed where to put the work files and ouput files, you would generate this text once saved, with the suffix .sst if saved as example.sst, by typing sisu -mhwxp example.sst while in the directory in which the file is saved.
_1 -m initial processing, -h html (css based), -w concordance for html, -x xml, -p pdf output, generated via latex, there are of course additional options
_1 for a listing type: sisu ~ commands
_1 for an outline of sisu markup type: sisu ~ markup
The example ends here.
WOK
help_markup
end
def headers
print <<WOK
Header tags appear at the beginning of a document and provide meta information on the document (such as the Dublin Core), or information as to how the document as a whole is to be processed.
All header instructions take either the form #{@cX.green}@headername:#{@cX.off} or #{@cX.green}0~headername#{@cX.off}. All Dublin Core meta tags are available
#{@cX.green}@indentifier:#{@cX.off} information or instructions
or
#{@cX.green}0~indentifier#{@cX.off} information or instructions
where the #{@cX.green}"identifier"#{@cX.off} is a tag recognised by the program, and the #{@cX.green}"information"#{@cX.off} or #{@cX.green}"instructions"#{@cX.off} belong to the tag/indentifier specified
Note: a header where used should only be used once; all headers apart from 0~title are optional; the @structure: or 0~toc header is used to describe document structure, and can be useful to know.
This is a sample header (#{@cX.fuschia}Dublin Core in fuschia,#{@cX.off} #{@cX.cyan}other information headers in cyan,#{@cX.off} #{@cX.ruby}markup instructions in red#{@cX.off}):
#{@cX.fuschia}@title:#{@cX.off} My Title - This is now the Title of the Document and used as such
#{@cX.cyan}@subtitle:#{@cX.off} The Subtitle if any
#{@cX.fuschia}@creator:#{@cX.off} [or @author:] Surname, Other names (if more than one author separate author names with a semi colon, if name is of an institution just write name or the name contains a comma enclose in quotation marks)
#{@cX.fuschia}@topic_register:#{@cX.off} [e.g.:] text markup language; application:text processing;output:html|xml|latex|pdf|sql
#{@cX.fuschia}@subject:#{@cX.off} (whatever your subject)
#{@cX.fuschia}@description:#{@cX.off}
#{@cX.fuschia}@publisher:#{@cX.off}
#{@cX.fuschia}@contributor:#{@cX.off}
#{@cX.fuschia}@translator:#{@cX.off} [or @translated_by:]
#{@cX.fuschia}@illustrator:#{@cX.off} [or @illustrated_by:]
#{@cX.fuschia}@prepared_by:#{@cX.off} [or @digitized_by:]
#{@cX.fuschia}@date:#{@cX.off} 2000-08-27
\t[ also #{@cX.fuschia}@date.created:#{@cX.off} #{@cX.fuschia}@date.issued:#{@cX.off} #{@cX.fuschia}@date.available:#{@cX.off} #{@cX.fuschia}@date.valid:#{@cX.off} #{@cX.fuschia}@date.modified:#{@cX.off} ]
#{@cX.fuschia}@type:#{@cX.off} article
#{@cX.fuschia}@format:#{@cX.off}
#{@cX.fuschia}@identifier:#{@cX.off}
#{@cX.fuschia}@source:#{@cX.off}
#{@cX.fuschia}@language:#{@cX.off} [or @language.document:] [country code for language if available, or language, English, en is the default setting] (en - English, fr - French, de - German, it - Italian, es - Spanish, pt - Portuguese, sv - Swedish, da - Danish, fi - Finnish, no - Norwegian, is - Icelandic, nl - Dutch, et - Estonian, hu - Hungarian, pl - Polish, ro - Romanian, ru - Russian, el - Greek, uk - Ukranian, tr - Turkish, sk - Slovak, sl - Slovenian, hr - Croatian, cs - Czech, bg - Bul garian ) [however, encodings are not available for all of the languages listed.]
#{@cX.fuschia}@language.original:#{@cX.off}
original language in which the work was published
#{@cX.fuschia}@papersize:#{@cX.off}
(A4|US_letter|book_B5|book_A5|US_legal)
#{@cX.fuschia}@relation:#{@cX.off}
#{@cX.fuschia}@coverage:#{@cX.off}
#{@cX.fuschia}@rights:#{@cX.off} copyright, all rights reserved, public domain, copyleft, creative commons variant, etc.
#{@cX.cyan}@owner:#{@cX.off}
#{@cX.cyan}@keywords:#{@cX.off} text document generation processing management latex pdf structured xml citation [your keywords here, used for example by rss feeds, and in sql searches]
#{@cX.cyan}@abstract:#{@cX.off} [paper abstract, placed after table of contents]
#{@cX.cyan}@comment:#{@cX.off} [...]
#{@cX.cyan}@catalogue:#{@cX.off} #{@cX.green}loc=#{@cX.off}[Library of Congress classification]; #{@cX.green}dewey=#{@cX.off}[Dewey classification]; #{@cX.green}isbn=#{@cX.off}[ISBN]; #{@cX.green}pg=#{@cX.off}[Project Gutenberg text number]
#{@cX.cyan}@classify_loc:#{@cX.off} [Library of Congress classification]
#{@cX.cyan}@classify_dewey:#{@cX.off} [Dewey classification]
#{@cX.cyan}@classify_isbn:#{@cX.off} [ISBN]
#{@cX.cyan}@classify_pg:#{@cX.off} [Project Gutenberg text number]
#{@cX.cyan}@prefix_a:#{@cX.off} [prefix is placed just before table of contents - not implemented]
#{@cX.cyan}@prefix_b:#{@cX.off} or #{@cX.cyan}@prefix:#{@cX.off} [prefix is placed just after table of contents]
#{@cX.cyan}@rcs:#{@cX.off} $Id$ [used by rcs or cvs to embed version (revision control) information into document, rcs or cvs can usefully provide a history of updates to a document ]
#{@cX.ruby}@structure:#{@cX.off} PART; CHAPTER; SECTION; ARTICLE; none; none;
optional, document structure can be defined by words to match or regular expression (the regular expression is assumed to start at the beginning of a line of text i.e. ^) default markers :A~ to :C~ and 1~ to 6~ can be used within text instead, without this header tag, and may be used to supplement the instructions provided in this header tag if provided (@structure: is a synonym for @toc:)
#{@cX.ruby}@level:#{@cX.off} newpage=3; breakpage=4 [paragraph level, used by latex to breakpages, the page is optional eg. in newpage]
#{@cX.ruby}@markup:#{@cX.off} num_top=4 [various markup instructions, eg: num_top=4 headings tobe numbered, starting at heading level 4... the default is to provide 3 levels, as in 1 level 4, 1.1 level 5, 1.1.1 level 6, markup to be merged within level]
#{@cX.ruby}@bold:#{@cX.off} [regular expression of words/phrases to be made bold]
#{@cX.ruby}@italics:#{@cX.off} [regular expression of words/phrases to italize]
#{@cX.ruby}@vocabulary:#{@cX.off} name of taxonomy/vocabulary/wordlist to use against document
#{@cX.ruby}@skin:#{@cX.off} skin_doc_[name_of_desired_document_skin]
#{@cX.ruby}@links:#{@cX.off} { SiSU }http://www.jus.uio.no/sisu/; { FSF }http://www.fsf.org
#{@cX.ruby}@@promo:#{@cX.off} sisu, ruby, search_libre_docs, open_society [places content in right pane in html, makes use of list.yml and promo.yml, commented out sample in document sample: free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst]
#{@cX.grey}% header ends here, NB only @title: is mandatory [this would be a comment]#{@cX.off}
#{@cX.grey}% NOTE: headings/levels below refer to 0.38 expermental markup
(a conversion script provided in sisu-examples, modify.rb makes conversion between 0.37 and 0.38 markup simple)#{@cX.off}
#{@cX.blue}:A~#{@cX.off} Top level heading [this is usually the same as the title @title: ]
#{@cX.blue}:B~#{@cX.off} Second level heading [this is a heading level divider]
#{@cX.blue}:C~#{@cX.off} Third level heading [this is a heading level divider]
#{@cX.blue}1~#{@cX.off} Top level heading preceding substantive text of document or sub-heading 5, the heading level that would normally be marked 1. or 2. or 3. etc. in a document
#{@cX.blue}2~#{@cX.off} Second level heading preceding substantive text of document or sub-heading 6, the heading level that would normally be marked 1.1 or 1.2 or 1.3 or 2.1 etc in a document
#{@cX.blue}3~#{@cX.off} Third level heading preceding substantive text of document, that would normally be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document
WOK
help_markup
end
def headers37
print <<WOK
Header tags appear at the beginning of a document and provide meta information on the document (such as the Dublin Core), or information as to how the document as a whole is to be processed.
All header instructions take either the form #{@cX.green}@headername:#{@cX.off} or #{@cX.green}0~headername#{@cX.off}. All Dublin Core meta tags are available
#{@cX.green}@indentifier:#{@cX.off} information or instructions
or
#{@cX.green}0~indentifier#{@cX.off} information or instructions
where the #{@cX.green}"identifier"#{@cX.off} is a tag recognised by the program, and the #{@cX.green}"information"#{@cX.off} or #{@cX.green}"instructions"#{@cX.off} belong to the tag/indentifier specified
Note: a header where used should only be used once; all headers apart from 0~title are optional; the 0~toc header is used to describe document structure, and can be useful to know.
This is a sample header (#{@cX.fuschia}Dublin Core in fuschia,#{@cX.off} #{@cX.cyan}other information headers in cyan,#{@cX.off} #{@cX.ruby}markup instructions in red#{@cX.off}):
#{@cX.green}0~#{@cX.off}#{@cX.fuschia}title#{@cX.off} My Title - This is now the Title of the Document and used as such
#{@cX.green}0~#{@cX.off}#{@cX.cyan}subtitle#{@cX.off} The Subtitle if any
#{@cX.green}0~#{@cX.off}#{@cX.fuschia}creator#{@cX.off} [or ~author] Ralph Amissah
#{@cX.green}0~#{@cX.off}#{@cX.fuschia}subject#{@cX.off} (whatever your subject)
#{@cX.green}0~#{@cX.off}#{@cX.fuschia}description#{@cX.off}
#{@cX.green}0~#{@cX.off}#{@cX.fuschia}publisher#{@cX.off}
#{@cX.green}0~#{@cX.off}#{@cX.fuschia}contributor#{@cX.off}
#{@cX.green}0~#{@cX.off}#{@cX.fuschia}translator#{@cX.off} [or ~translated_by]
#{@cX.green}0~#{@cX.off}#{@cX.fuschia}illustrator#{@cX.off} [or ~illustrated_by]
#{@cX.green}0~#{@cX.off}#{@cX.fuschia}prepared_by#{@cX.off} [or ~digitized_by]
#{@cX.green}0~#{@cX.off}#{@cX.fuschia}date#{@cX.off} 2000-08-27
\t[ also #{@cX.green}0~#{@cX.off}#{@cX.fuschia}date.created#{@cX.off} #{@cX.green}0~#{@cX.off}#{@cX.fuschia}date.issued#{@cX.off} #{@cX.green}0~#{@cX.off}#{@cX.fuschia}date.available#{@cX.off} #{@cX.green}0~#{@cX.off}#{@cX.fuschia}date.valid#{@cX.off} #{@cX.green}0~#{@cX.off}#{@cX.fuschia}date.modified#{@cX.off} ]
#{@cX.green}0~#{@cX.off}#{@cX.fuschia}type#{@cX.off} article
#{@cX.green}0~#{@cX.off}#{@cX.fuschia}format#{@cX.off}
#{@cX.green}0~#{@cX.off}#{@cX.fuschia}identifier#{@cX.off}
#{@cX.green}0~#{@cX.off}#{@cX.fuschia}source#{@cX.off}
#{@cX.green}0~#{@cX.off}#{@cX.fuschia}language#{@cX.off} [country code for language if available, or language, English, en is the default setting] (en - English, fr - French, de - German, it - Italian, es - Spanish, pt - Portuguese, sv - Swedish, da - Danish, fi - Finnish, no - Norwegian, is - Icelandic, nl - Dutch, et - Estonian, hu - Hungarian, pl - Polish, ro - Romanian, ru - Russian, el - Greek, uk - Ukranian, tr - Turkish, sk - Slovak, sl - Slovenian, hr - Croatian, cs - Czech, bg - Bul garian ) [however, encodings are not available for all of the languages listed.]
#{@cX.green}0~#{@cX.off}#{@cX.fuschia}relation#{@cX.off}
#{@cX.green}0~#{@cX.off}#{@cX.fuschia}coverage#{@cX.off}
#{@cX.green}0~#{@cX.off}#{@cX.fuschia}rights#{@cX.off} copyright, all rights reserved, public domain, copyleft, creative commons variant, etc.
#{@cX.green}0~#{@cX.off}#{@cX.cyan}owner#{@cX.off}
#{@cX.green}0~#{@cX.off}#{@cX.cyan}keywords#{@cX.off} text document generation processing management latex pdf structured xml citation [your keywords here, used for example by rss feeds, and in sql searches]
#{@cX.green}0~#{@cX.off}#{@cX.cyan}abstract#{@cX.off} [paper abstract, placed after table of contents]
#{@cX.green}0~#{@cX.off}#{@cX.cyan}comment#{@cX.off} [...]
#{@cX.green}0~#{@cX.off}#{@cX.cyan}classify_loc#{@cX.off} Library of Congress classification
#{@cX.green}0~#{@cX.off}#{@cX.cyan}classify_dewey#{@cX.off} Dewey classification system
#{@cX.green}0~#{@cX.off}#{@cX.cyan}classify_isbn#{@cX.off} ISBN
#{@cX.green}0~#{@cX.off}#{@cX.cyan}classify_pg#{@cX.off} Project Gutenberg text number
#{@cX.green}0~#{@cX.off}#{@cX.cyan}prefix_a#{@cX.off} [prefix is placed just before table of contents - not implemented]
#{@cX.green}0~#{@cX.off}#{@cX.cyan}prefix_b#{@cX.off} or #{@cX.green}0~#{@cX.off}#{@cX.cyan}prefix#{@cX.off} [prefix is placed just after table of contents]
#{@cX.green}0~#{@cX.off}#{@cX.cyan}rcs#{@cX.off} $Id$ [used by rcs or cvs to embed version (revision control) information into document, rcs or cvs can usefully provide a history of updates to a document ]
#{@cX.green}0~#{@cX.off}#{@cX.ruby}toc#{@cX.off} PART; CHAPTER; SECTION; ARTICLE; none; none;
optional, where document structure can be defined by a match words or regular expression (the regular expression is assumed to start at the beginning of a line of text i.e. ^)
default markers 1~ to 6~ can be used within text instead, without this header tag, and may be used to supplement the instructions provided in this header tag if provided
#{@cX.green}0~#{@cX.off}#{@cX.ruby}level#{@cX.off} newpage=3; breakpage=4 [paragraph level, used by latex to breakpages, the page is optional eg. in newpage]
#{@cX.green}0~#{@cX.off}#{@cX.ruby}markup#{@cX.off} num_top=4 [various markup instructions, eg: num_top=4 headings tobe numbered, starting at heading level 4... the default is to provide 3 levels, as in 1 level 4, 1.1 level 5, 1.1.1 level 6, markup to be merged within level]
#{@cX.green}0~#{@cX.off}#{@cX.ruby}bold#{@cX.off} [list of words to make bold with semi colon separator]
#{@cX.green}0~#{@cX.off}#{@cX.ruby}italics#{@cX.off} [list of words to italize with semi colon separator]
#{@cX.green}0~#{@cX.off}#{@cX.ruby}vocabulary#{@cX.off} name of taxonomy/vocabulary/wordlist to use against document
#{@cX.green}0~#{@cX.off}#{@cX.ruby}skin#{@cX.off} skin_doc_[name_of_desired_document_skin]
#{@cX.green}0~#{@cX.off}#{@cX.ruby}links#{@cX.off} { Google }http://google.com;
#{@cX.grey}% header ends here, NB only 0~title is mandatory [this would be a comment]#{@cX.off}
#{@cX.blue}1~#{@cX.off} Top level heading [this is usually the same as the title 0~title ]
#{@cX.blue}2~#{@cX.off} Second level heading [this is a heading level divider]
#{@cX.blue}3~#{@cX.off} Third level heading [this is a heading level divider]
#{@cX.blue}4~#{@cX.off} Top level heading preceding substantive text of document or sub-heading 5, the heading level that would normally be marked 1. or 2. or 3. etc. in a document
#{@cX.blue}5~#{@cX.off} Second level heading preceding substantive text of document or sub-heading 6, the heading level that would normally be marked 1.1 or 1.2 or 1.3 or 2.1 etc in a document
#{@cX.blue}6~#{@cX.off} Third level heading preceding substantive text of document, that would normally be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document
WOK
help_markup
end
def customise
print <<WOK
There are a number of files that control the appearance of a site or a document i.e.
#{@cX.blue}(i)#{@cX.off} files that control #{@cX.green}site-wide appearance#{@cX.off}:
#{@cX.green}defaults.rb#{@cX.off} initial values used by program, not necessary to change
skins are placed in a configuration directory beneath the markup directory ./_sisu/skin/doc or in ~/.sisu/skin/doc
if a skin is also to be used for a directory or site wide presentations, rather than being called for a single document then a softlink is placed from ~/.sisu/skin/dir or ~/.sisu/skin/site respectively to the relevant skin within ~/.sisu/skin/doc
rules for skin loading are in #{@cX.green}sysenv.rb#{@cX.off}
the skin loading heuristics / hierarchy is currently as follows:
a. if there is a skin requested within a document, thent that skin is used
0~skin skin_lm (would load skin ~/.sisu/skin/doc/skin_lm.rb)
b. use it if there is a "dir" skin with the same name as the source directory "stub" i.e.
if working in a directory called /home/myhome/workdir/lm
then if ~/.sisu/skin/dir/skin_lm.rb were found it would be used and skin_lm.rb would be a softlink to the relevant skin in the document skin directory (where all the actual skins are kept)
x. [additionally though discouraged a special rule can be set up in sysenv AddSkin.select (which could override b if desired)]
#{@cX.green}skin_site_#{@cX.off}#{@cX.cyan}[name of site skin in use]#{@cX.off}#{@cX.green}.rb#{@cX.off} this file is called by skin.rb
if there are several such files, site appearance may be changed by
requesting the skin_site desired from skin.rb
and
#{@cX.blue}(ii)#{@cX.off} presentation maintenance:
if you have a body of documents the easiest way to give them a particular appearance/skin, is to associate that directory with a skin, all files in that directory take on the specified appearance, changing appearance of documents once directories are set up is as simple as copying the files from one directory to another (or renaming the directory); or associating the directory with a different skin.
see also directories
WOK
end
def configure
print <<WOK
see the following topics
install
setup
and note for initial configuration it is necessary to run:
sisu -C
(this places the default CSS files and DTDs in place)
WOK
end
def path
help_env
puts <<WOK
If you have problems check permissions (and if in home directory ownership).
#{@cX.green}directory paths as currently set#{@cX.off}:
output docs: #{@cX.blue}#{@env.path.webserv}#{@cX.off}
cgi scripts: #{@cX.blue}#{@env.path.cgi}#{@cX.off}
processing: #{@cX.blue}#{@env.path.processing}#{@cX.off}
sisu meta markup: #{@cX.blue}#{@env.path.dal}#{@cX.off}
html tuning: #{@cX.blue}#{@env.path.tune}#{@cX.off}
latex: #{@cX.blue}#{@env.path.tex}#{@cX.off}
texinfo: #{@cX.blue}#{@env.path.texi}#{@cX.off}
images:
source: #{@cX.blue}#{@env.path.image_source}#{@cX.off}
latex source: #{@cX.blue}#{@env.path.image_source_tex}#{@cX.off}
note images are also sourced from within your pwd - #{@cX.blue}#{Dir.pwd}/_sisu/image#{@cX.off} if it exists
#{@cX.grey}[ texinfo: #{@env.path.texinfo} - check duplication ]#{@cX.off}
#{@cX.green}resource configuraton files#{@cX.off} to change the paths specified above, are searched for in the following order:
under the current SiSU markup data directory: #{@cX.blue}#{Dir.pwd}/_sisu/sisurc.yml#{@cX.off}
under the home directory ~/.sisu: #{@cX.blue}#{@env.path.home}/.sisu/sisurc.yml#{@cX.off}
in the "/etc" directory: #{@cX.blue}#{@env.path.etc}/sisurc.yml#{@cX.off}
default file paths are set by the program SiSU
#{@cX.green}skins#{@cX.off} for document appearances on a site, directory or per document basis are located in subdirectories #{@cX.blue}doc/#{@cX.off} #{@cX.blue}dir/#{@cX.off} and #{@cX.blue}site/#{@cX.off} within:
#{@cX.blue}#{Dir.pwd}/_sisu/skin#{@cX.off}
#{@cX.blue}#{@env.path.home}/.sisu/skin#{@cX.off}
#{@cX.blue}#{@env.path.etc}/skin#{@cX.off}
default appearances are set by the program SiSU in the absence of skins
#{@cX.green}Note on subdirectories for output documents#{@cX.off}
The last part of the name of the directory you choose to work from is used as the major sub-directory in which output files are placed,
i.e. if you are working in a directory called #{@cX.blue}#{@env.path.home}/ebook#{@cX.off}
the output files will be placed in a sub-directory named after the processed text within #{@cX.blue}#{@env.path.webserv}/ebook#{@cX.off}
( Within this major sub-directory, a sub-directory is made with the name of each document processed, into which output files - html, pdf, xml, plaintext etc. are placed (texinfo being an exception at present) )
#{@cX.green}sisu -C#{@cX.off} [#{@cX.green}--init=site#{@cX.off}] configure/initialise shared output directory files initialize shared output directory (config files such as css and dtd files are not updated if they already exist unless modifier is used). -C --init=site configure/initialise site more extensive than -C on its own, shared output directory files/force update, existing shared output config files such as css and dtd files are updated if this modifier is used. in a new markup document working directory should initialise the corresponding output directory, though SiSU will automatically do this, the first time it is run (for processing) in a given directory.
There are additional details, ... this should get you started.
See also
sisu --help directory
WOK
help_env
end
def directories
help_env
print <<WOK
the directory structure used by sisu is controlled by the configuration files #{@cX.blue}sisurc.yml#{@cX.off}
there are separate directories for the following:
(a) #{@cX.green}data directories#{@cX.off}
the directories in which you place the SiSU marked-up data files that are to be processed
there may be as many directories and files as you choose to have,
you are currently in: #{@cX.blue}#{Dir.pwd}#{@cX.off}
(b) #{@cX.green}output directory#{@cX.off}
by default files in the data directory are output to
a sub-directory within the output directory (usually the web document directory), or to an sql database
of the same name as the stub or last portion of the data directory name
by way of example
you are currently in: #{@cX.blue}#{Dir.pwd}#{@cX.off}
the document output directory is set to: #{@cX.blue}#{@env.path.webserv}#{@cX.off}
documents from your current directory will be placed in: #{@cX.blue}#{@env.path.output}#{@cX.off}
the final output is placed in subdirectories either as configured by default in the program or as modified by SiSU configuration files
subdirectories are created within the main output directory, based on the name of the data directory
subsubdirectories are created the sub-directory contained in the main output directory based on the name of the file
(subdirectories are created in this (output) sub-directory named after the data file)
for this reason it is a convention to give descriptive names to the data file.
The default output directory is #{@cX.green}~/sisu_www#{@cX.off}
The output directory is currently set to:
#{@cX.blue}#{@env.path.webserv}#{@cX.off}
Output files, are currently set to be produced in:
processed document output: #{@cX.blue}#{@env.path.output}#{@cX.off}
a document in the current directory #{@cX.blue}#{Dir.pwd}#{@cX.off}
will have its output placed in: #{@cX.blue}#{@env.path.output}/#@output_stub#{@cX.off}
NB: the verbose flag v included in the generate command string, should
result in a list of output filenames together with their paths.
The flag U on its own (e.g. sisu -U gpl3.fsf.sst) should provide a list
of output files that could be generated together with their paths.
(c) #{@cX.green}configuration files#{@cX.off}
SiSU program defaults are set within the program, and may be adjusted in the yml file #{@cX.blue}sisurc.yml#{@cX.off} which is searched for in the following paths, which are prioritized as listed (the first one found is loaded):
###
under the current SiSU markup data directory: #{@cX.blue}#{@env.path.pwd}/_sisu/sisurc.yml#{@cX.off}
under the home directory ~/.sisu: #{@cX.blue}#{@env.path.home}/.sisu/sisurc.yml#{@cX.off}
in the "/etc" directory: #{@cX.blue}#{@env.path.etc}/sisurc.yml#{@cX.off}
(d) #{@cX.green}processing directories#{@cX.off} sisu creates a number of processing directories,
where these should be located can be modified in #{@cX.green}~/.sisu/sisurc.yml#{@cX.off}
work directories include the following:
root working directory #{@cX.blue}#{@env.path.processing}#{@cX.off}
metaverse intermediate markup #{@cX.blue}#{@env.path.dal}#{@cX.off}
tune html (for special html/navigation pages) #{@cX.blue}#{@env.path.tune}#{@cX.off}
tex for latex and pdf #{@cX.blue}#{@env.path.tex}#{@cX.off}
texinfo for texinfo and info files #{@cX.blue}#{@env.path.texi}#{@cX.off}
These files are usually used only for processing and removed. There is a maintenance flag to keep them.
(e) #{@cX.green}images#{@cX.off}
there are a number of categories of images,
NB the document markup directory is initialised by issuing the command
sisu -C --init=site
this creates the output sub-directory, and makes necessary image links, and
copies images specific to the markup directory if there are any.
general images for the sisu program that come with the package,
that are the defaults used by sisu, these are installed with the program
images that the author wishes to include within documents,
these should be placed in a sub-directory
within the current document markup directory called #{@cX.green}_sisu/image#{@cX.off}
if an instruction is given to process a remote document which contains
downloadable images, they are included in a sub-directory of the current
markup directory #{@cX.green}_sisu/sisu/image_external#{@cX.off} that is created
if necessary for the purpose.
finally skins may specify/indicate other image directories. see sisu --help skin
any site images required by the skin instruction must be copied in to the
site image directory (it may be necessary to do manual configuration depending
on what you are trying to achieve).
(f) #{@cX.green}program directories#{@cX.off}
sisu --help install
sisu ~ install
See also
sisu --help path
WOK
help_env
end
def program_found?(program)
if program
rc=if SiSU_Env::Info_settings.new.program?(program)
SiSU_Env::Info_settings.new.program?(program)
else ''
end
if program =='rmagick'; program='identify' #rmagick is ruby lib uses imagemagick's identify
end
bin=if SiSU_Env::System_call.new.program_found?(program)
SiSU_Env::System_call.new.program_found?(program)
else 'false'
end
else bin,rc='false','false'
end
if program; "#{@cX.blue}#{program}#{@cX.off} bin: #{@cX.brown}#{bin}#{@cX.off} rc: #{@cX.brown}#{rc}#{@cX.off}"
else "bin: #{@cX.brown}#{bin}#{@cX.off} rc: #{@cX.brown}#{rc}#{@cX.off}"
end
end
def sisu_version
version=SiSU_Env::Info_version.new.get_version
rb_ver=SiSU_Env::Info_version.new.rbversion
if version[:version]
tell=SiSU_Screen::Ansi.new('-v',version[:project],version[:version],version[:date_stamp],version[:date],rb_ver)
tell.version
else puts 'SiSU version information not available'
end
end
def rhost
@ls=leading_spaces=' '*49
@rhost=SiSU_Env::Info_remote_host.new.rhost
def r1
if @rhost.r1; @rhost.r1 + "\n"
else ''
end
end
def r2
if @rhost.r2; @ls + @rhost.r2 + "\n"
else ''
end
end
def r3
if @rhost.r3; @ls + @rhost.r3 + "\n"
else ''
end
end
def r4
if @rhost.r4; @ls + @rhost.r4 + "\n"
else ''
end
end
def r5
if @rhost.r5; @ls + @rhost.r5 + "\n"
else ''
end
end
def r6
if @rhost.r6; @ls + @rhost.r6 + "\n"
else ''
end
end
def note
msg='(remote settings user and host set in sisurc.yml under remote:)'
if @rhost.r1; @ls + msg
else msg
end
end
self
end
def environment
cf_defaults=SiSU_Env::Info_processing_flag.new
sisu_version
x =<<WOK
#{@cX.green}current and output directories#{@cX.off}
user: #{@cX.blue}#{@env.user}#{@cX.off}
home: #{@cX.blue}#{@env.path.home}#{@cX.off}
remote set [remote user]@[remote host]: #{@cX.blue}#{rhost.r1}#{rhost.r2}#{rhost.r3}#{rhost.r4}#{rhost.r5}#{rhost.r6}#{@cX.off}#{rhost.note}
locale (encoding, UTF-8 desired): #{@cX.blue}#{@env.locale}#{@cX.off}
current directory: #{@cX.blue}#{@env.path.pwd}#{@cX.off}
document output root directory set to: #{@cX.blue}#{@env.path.webserv}#{@cX.off}
documents from current directory placed in: #{@cX.blue}#{@env.path.output}#{@cX.off}
webrick url: #{@cX.blue}#{@env.url.webserv_base_cgi}#{@cX.off}
(to start webrick server 'sisu -W')
sqlite db for present directory: #{@cX.blue}sqlite #{@env.path.output}/sisu_sqlite.db#{@cX.off}
postgresql port set to: #{@cX.blue}#{@db.psql.port}#{@cX.off}
postgresql db for present directory: #{@cX.blue}#{@db.psql.db}#{@cX.off}
[first create manually if necessary: 'createdb #{@db.psql.db}']
[generated sqlite cgi search form]: #{@cX.blue}#{@env.url.webserv_base_cgi}/cgi-bin/sisu_sqlite.cgi#{@cX.off}
[generated postgresql cgi search form]: #{@cX.blue}#{@env.url.webserv_base_cgi}/cgi-bin/sisu_pgsql.cgi#{@cX.off}
(to generate 'sisu -F' or 'sisu -F webrick')
#{@cX.green}configuration files#{@cX.off}
sisurc.yml used: #{@cX.blue}#{@env.path.yamlrc}#{@cX.off}
configuration information search path: #{@cX.blue}#{@env.path.rc.join(', ')}#{@cX.off}
(directory also relevant for skins and images)
digest (md5 or sha256): #{@cX.blue}#{@env.digest.type}#{@cX.off}
papersize set (LaTeX/pdf): #{@cX.blue}#{@env.papersize}#{@cX.off}
(digest and papersize can be changed in sisurc.yml under default:)
#{@cX.green}intermediate processing#{@cX.off}
processing directory: #{@cX.blue}#{@env.path.processing}#{@cX.off}
(to keep processing output, use -M flag)
#{@cX.green}programs selected for viewing output#{@cX.off}
text editor: #{@cX.blue}#{@env.program.text_editor}#{@cX.off}
web browser: #{@cX.blue}#{@env.program.web_browser}#{@cX.off}
console web browser: #{@cX.blue}#{@env.program.console_web_browser}#{@cX.off}
pdf viewer: #{@cX.blue}#{@env.program.pdf_viewer}#{@cX.off}
xml viewer: #{@cX.blue}#{@env.program.xml_editor}#{@cX.off}
odf viewer: #{@cX.blue}#{@env.program.odf_viewer}#{@cX.off}
(default selections can be changed in sisurc.yml under program_select:)
#{@cX.green}programs used if available#{@cX.off}
word count: #{program_found?(@env.program.wc)}
imagemagick/rmagick: #{program_found?(@env.program.rmagick)}
tidy: #{program_found?(@env.program.tidy)}
rexml: #{program_found?(@env.program.rexml)}
latex to pdf: #{program_found?(@env.program.pdflatex)}
postgresql: #{program_found?(@env.program.postgresql)}
sqlite: #{program_found?(@env.program.sqlite)}
(these can be turned off if unavailable in sisurc.yml under program_set:)
#{@cX.green}processing shortcut defaults set to:#{@cX.off}
color defaut set (on==true) #{@cX.blue}#{cf_defaults.color}#{@cX.off}
sisu -0 #{@cX.blue}#{cf_defaults.cf_0}#{@cX.off} [default]
sisu -1 #{@cX.blue}#{cf_defaults.cf_1}#{@cX.off}
sisu -2 #{@cX.blue}#{cf_defaults.cf_2}#{@cX.off}
sisu -3 #{@cX.blue}#{cf_defaults.cf_3}#{@cX.off}
sisu -4 #{@cX.blue}#{cf_defaults.cf_4}#{@cX.off}
sisu -5 #{@cX.blue}#{cf_defaults.cf_5}#{@cX.off}
(defaults may be changed in active sisurc.yml file under flag:)
#{@cX.green}special powers, risky operations set:#{@cX.off}
zap (delete output directories) #{@cX.blue}#{SiSU_Env::Info_settings.new.permission?('zap')}#{@cX.off}
css copy (copy over css files) #{@cX.blue}#{SiSU_Env::Info_settings.new.permission?('css_modify')}#{@cX.off}
(true/false defaults may be changed in active sisurc.yml file under permissions_set:)
NOTE: for HELP type 'sisu --help', 'sisu --help [help request]', 'man sisu', (or see the system or online documentation)
WOK
print x
end
def dublin_core
print <<WOK
@title:
@subtitle: [is added to title for purposes of Dublin Core description]
@creator:
@type:
@subject:
@date: [ccyy-mm-dd]
@date.created:
@date.issued:
@date.available:
@date.valid:
@date.modified:
@source:
@language: en
@papersize: A4
@relation:
@coverage:
@rights:
WOK
end
def headings
print <<WOK
These are not required, a header is quicker to prepare if a documents structure can be defined by matching words or a regular expression, see headers).
@structure: PART; CHAPTER; SECTION; ARTICLE; none; none;
structure can be defined by a match words or regular expression (the regular expression is assumed to start at the beginning of a line of text i.e. ^)
The following heading or level (structuring) defaults are available (for use instead of or together with @structure: header):
1~ 2~ 3~ 4~ 5~ 6~
or, [0.38]
:A~ :B~ :C~ 1~ 2~ 3~
Heading tags take either of the forms above, ranging from 1-6
They appear at the beginning of the line on which a heading appears,
the number indicates the level of the heading with level 1 being a title,
segments (in html output) are by default created on level 4
(segmented text is split/segmented on level 4, and
assigned a file name automatically according to the title number,
unless you explicitly specify otherwise)
eg.
% SiSU 0.16 - 0.37
1~ Document Title
2~ Document Subtitle whatever it is
3~ Part
4~ Chapter
5~ Heading
6~ sub-heading
in the 0.38 notation this maps to:
% SiSU 0.38
:A~ Document Title
:B~ Document Subtitle whatever it is
:C~ Part
1~ Chapter
2~ Heading
3~ sub-heading
(a conversion script provided in sisu-examples, modify.rb makes conversion between 0.37 and 0.38 markup simple)
Normal text would follow each heading level as appropriate, though it is most usual to start with ordinary writing beneath level 4 as it is at this level that segments are created.
Automatic numbering of paragraphs is usually set to start at level 4 trough level 6 and takes the form 1. then 1.1 then 1.1.1 this being given as a Header tag 0~ There may be up to 6 levels in a document,
If auto-numbering is on, then for html output the segments created (on level 4 headings) are automatically assigned the name of the title number.
However, you may indicate an alternative set of key/title words, with one of the following instructions:
4~filename This is a Section or Subject Heading
If there is a strictly discernable word appearing at the beginning of the line in a document that identifies the level,
the words can be used to identify the levels in a header tag:
0~toc Part; Chapter; Section; Article; none; none
instead of providing individual heading tags
sisu structure, (0.38) alternative notation, A,B,C,1,2,3 mapping to 1,2,3,4,5,6
SiSU has in effect two sets of levels to be considered
1-3 headings/levels, (A-C [0.38]) pre-ordinary paragraphs /pre-substantive text, and
4-6 headings/levels, (1-3 [0.38]) levels which are followed by ordinary text.
This may be conceptualised as levels A,B,C, 1,2,3, and using such letter number notation, in effect:
A must exist, optional B and C follow in the sequence
1 must exist, optional 2 and 3 follow in the sequence
i.e. there are two independent heading level sequences A,B,C and 1,2,3 or using the standard notation 1,2,3 and 4,5,6
on the positive side: (a) the A,B,C,1,2,3 alternative makes explicit an aspect of structuring documents in SiSU that is not otherwise obvious to the newcomer (though it appears more complicated, is more in your face and likely to be understood fairly quickly); (b) the substantive text follows levels 1,2,3 and it is 'nice' to do most work in those levels
WOK
end
def languages
puts <<WOK
Multi-language Document File Naming and Directory Mapping
If the same document exists in different language versions, and it is desired that the published language versions should reside in the same output directory, the following filenaming convention should be observed, using Spannish as the sample language code (es) [it is very likley the use of country codes as language codes will be changed or extended in future] [filename]~[language code].sst
filename~es.sst
within sisurc.yml under the heading
default:
language file: [at 1, 2 or 3]
determines the output filenaming convention used, as follows:
(1) [output directory path]/filename/es.index.html
(2) [output directory path]/filename/index.es.html
(3) [output directory path]/filename/index.html.es (which Apache for example can be configured to use to automatically serve each users preference)
filename~fr.sst
filename~de.sst
etc. would be placed in the same directory using the same convention as indeed would:
filename.sst
using the default convention mapping convention.
Selecting this form of filename will overide other language settings including the language header within a document.
WOK
end
def endnotes
print <<WOK
(1) Footnote/endnotes tags take a number of possible forms, the simplest being to embed an endnote within your text~{ this would appear as an endnote, and would have an automatically assigned number }~ Embedded endnotes~{this is an endnote}~ and at the end of the paragraph~{* an asterisk marked note }~ writing the endnote:~{another endnote}~
------------------------------------------
#{@cX.ruby}All you need to know about endnotes appears above this line...#{@cX.off} apart from the fact that you cannot mix endnote markup styles
(2) The other ways of inserting an endnote involve placing a tag within the text as to where the endnote reference number should appear like so~^ and at the end of the paragraph writing the endnote:~^
^~ like so, this is an endnote
^~ another endnote
WOK
end
def tables
print <<WOK
#{@cX.green}table{ [number of columns] [column width %];[column width %]#{@cX.off}
[table content, line breaks are important see example below]
#{@cX.green}}table#{@cX.off}
#{@cX.grey}----#{@cX.off}
This is a sample table:
-----------------------
#{@cX.green}table{ c3; 40; 30; 30;#{@cX.off}
This is a table
this would become column two of row one
column three of row one is here
And here begins another row
column two of row two
column three of row two, and so on
#{@cX.green}}table#{@cX.off}
there is an alternative way to markup tables, a sample document is provided in the file
#{@cX.green}sisu_output_overview.sst#{@cX.off} located in
#{@cX.green}/usr/share/doc/sisu#{@cX.off} or equivalent directory
preformatted text
-----------------
#{@cX.green}poem{#{@cX.off}
[Text here]
#{@cX.green}}poem#{@cX.off}
#{@cX.grey}----#{@cX.off}
#{@cX.green}group{#{@cX.off}
[Text here]
#{@cX.green}}group#{@cX.off}
#{@cX.grey}----#{@cX.off}
#{@cX.green}code{#{@cX.off}
[Text here]
#{@cX.green}}code#{@cX.off}
WOK
end
def modules
print <<WOK
#{@cX.ruby}IGNORE#{@cX.off}
WOK
end
def modules_old
print <<WOK
#{@cX.ruby}DATED NOT CURRENT - IGNORE#{@cX.off}
This file is to contain some information the different programs that form sisu:
their inter-relationship (for which see sisu-chart.pdf)
and
what they do
sisu\ttui/command line program that when run with flags against files produces requested output
~/.sisu\tconfiguration directory, contains sisu configuration, and skins for alternative appearances
param\tgathers parameters from the sourcefile, when called by metaverse parameters are saved to pstore file
sysenv\tgets system information, and builds directory structure
init\tintialised defaults for appearance
skin\tsite wide skin
format\tformatting instructions assosciated with and used by calling module
metaverse\tinitial processing stage, preliminary file on which subsequent processing is done is created [-m]
plaintext\tplaintext creating module [-a]
html\thtml creating modules [-h]
texpdf\tlatex and pdf creating modules [-p]
xml & xml_dom\txml creating modules [-x -X]
concordance\tword map creating module [-w]
termsheet\tcreation of documents from termsheet and standard forms [-t]
dbi\tdbi database build and populating module, default postgresql [-D]
dbi_sqlite\tdbi database build and populating module, for sqlite [-d]
#{@cX.ruby}DATED NOT CURRENT - IGNORE#{@cX.off}
WOK
end
def install
#% system configuration
print <<WOK
#{@cX.green}Install SiSU#{@cX.off}
Presumably if you are reading this interactively you have a copy of SiSU already installed, nevertheless here are a few notes.
SiSU does require setup, the executable file #{@cX.blue}sisu#{@cX.off} is placed in #{@cX.blue}#{Config::CONFIG['bindir']}#{@cX.off} or #{@cX.blue}#{Config::CONFIG['sitelibdir']}#{@cX.off} and the library files, in #{@cX.blue}#{Config::CONFIG['rubylibdir']}/#{SiSU_lib}#{@cX.off}
or in #{@cX.blue}#{Config::CONFIG['sitelibdir']}/#{SiSU_lib}#{@cX.off}
SiSU comes with a number of installers, including #{@cX.blue}setup.rb#{@cX.off}, #{@cX.blue}install#{@cX.off} and a #{@cX.blue}Rantfile#{@cX.off} if rant is installed on your system, you may need to be root to install sisu on your system. After unpacking the tarball, in the top directory of the tarball which contains the named files type, one of:
sudo ./sisu-install base
sudo ./sisu-install setup
if that does not work try
sudo ruby ./sisu-install setup
if rant is installed on your system you may instead run:
sudo rant base
for further options:
./sisu-install -T
SiSU is pre-packaged for some GNU/Linux distributions such as Debian.
For information on download and installation, see #{@cX.blue}http://www.jus.uio.no/sisu/SiSU/download#{@cX.off}
For post installation help it is best you refer to '#{@cX.blue}man 8 sisu#{@cX.off}'
Host
host: #{@cX.blue}#{@env.hostname}#{@cX.off}
arch: #{@cX.blue}#{@env.arch}#{@cX.off}
Directories for installation
bin: #{@cX.blue}#{Config::CONFIG['bindir']}#{@cX.off} or #{@cX.blue}#{Config::CONFIG['sitelibdir']}#{@cX.off}
lib (site-ruby): #{@cX.blue}#{Config::CONFIG['rubylibdir']}/#{SiSU_lib}#{@cX.off} or #{@cX.blue}#{Config::CONFIG['sitelibdir']}/#{SiSU_lib}#{@cX.off}
conf [etc]: #{@cX.blue}#{@env.path.etc}/sisu#{@cX.off}
data (document samples, images, README): #{@cX.blue}#{@env.path.sample_data}#{@cX.off}
processing: #{@cX.blue}#{@env.path.processing}#{@cX.off}
output www: #{@cX.blue}#{@env.path.output}#{@cX.off}
Output files, are currently set to be produced in:
processed document output: #{@cX.blue}#{@env.path.output}#{@cX.off}
a document in the current directory #{@cX.blue}#{Dir.pwd}#{@cX.off}
will have its output placed in: #{@cX.blue}#{@env.path.output}/#@output_stub#{@cX.off}
Install any additional programs of interest (that SiSU makes use of, that are not already on your system)
Programs SiSU makes use of include:
LaTeX
texinfo
pdfetex aka. pdflatex
sqlite
postgresql
Again, refer to '#{@cX.blue}man 8 sisu#{@cX.off}'
For additional help on using SiSU once installed type:
sisu --help
WOK
end
def setup
print <<WOK
#{@cX.green}configuration files#{@cX.off}
sisurc.yml used:
#{@cX.blue}#{@env.path.yamlrc}#{@cX.off}
configuration information search path:
#{@cX.blue}#{@env.path.rc.join(', ')}#{@cX.off}
(directory also relevant for skins and images)
to initialise the mapped output directory, from within the markup document directory type:
#{@cX.blue}sisu -CC#{@cX.off}
for information on your current sisu configuration settings, type:
#{@cX.blue}sisu --help env#{@cX.off}
or
#{@cX.blue}sisu -V#{@cX.off}
see also
#{@cX.blue}man 8 sisu#{@cX.off}
and
#{@cX.blue}http://www.jus.uio.no/sisu/SiSU#{@cX.off}
WOK
end
def termsheet
print <<WOK
#{@cX.green}sisu -t [termsheetname].termsheet.rb#{@cX.off}
will produce the collection of documents associated with [termsheetname.termsheet.rb]
#{@cX.green}termsheet.rb#{@cX.off} files:
(i) are named after the facility
(ii) contain instructions as to which standard forms to use for the agreement (standard_form.rb)
there may be several, eg. the termsheet, and the resulting:
main agreement; collection account charge; and deed of assignment
(iii) contain the variable terms of the agreement, borrower, interest etc.
for a new loan agreement fill out a new termsheet specifying
what standard forms are to be used,
and the terms of the agreement.
#{@cX.green}standard_form.rb#{@cX.off} files:
contain the standard terms of the agreement
there is a standard form for each variation of agreement
(so eg. there are as many facility agreements as there are variations in standard facility)
these may be prepared for any agreement that is to be reused.
(preparation takes the form of formating and
placing variable holders for the variables that are to be provided by the termsheet.rb file)
it is necessary to purge the directory ~facilityData when old files are removed
WOK
end
def help_commands
print <<WOK
also see:
sisu --help commands
man sisu
WOK
end
def help_env
print <<WOK
for sisu environment information see:
sisu --help env
WOK
end
def help_general
help_env
help_commands
end
def help_markup
print <<WOK
for help with sisu markup see:
sisu --help markup
sisu --help header
sisu --help structure [sisu --help heading]
to check markup version in file:
sisu --identify [filename].sst
for brief descriptive summary of markup history
sisu --query-history
or if for a particular version
sisu --query-0.38
for markup:
sisu --help example38
sample marked up documents are provided in directory:
#{@cX.green}sisu-examples/sample/document_samples_sisu_markup/#{@cX.off}
and online
#{@cX.green}www.jus.uio.no/sisu#{@cX.off}
WOK
end
def convert
print <<WOK
for information on the markup version used within a sisu markup file:
sisu --inspect [filename]
to convert between sst markup versions 0.37 and 0.38:
sisu --to-current
sisu --to-38 [filename/wildcard]
sisu --to-37 [filename/wildcard]
convert an sst file with footnotes following text to (preferred) inline footnotes
sisu --convert-footnotes [filename/wildcard]
to convert from sst to simple xml representations (sax, dom and node):
sisu --to-sax [filename/wildcard]
sisu --to-sxs [filename/wildcard]
sisu --to-dom [filename/wildcard]
sisu --to-sxd [filename/wildcard]
sisu --to-node [filename/wildcard]
sisu --to-sxn [filename/wildcard]
to convert to sst from simple xml representations (sax, dom and node):
sisu --from-xml2sst [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]]
sisu --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]]
to attempt to convert a kdissert (.kdi) file to sisu markup:
sisu --from-kdi [kdissert filename]
(very basic and experimental)
WOK
end
def dal
print <<WOK
sisu -m [filename/wildcard] creates the metaverse, used by all other modules for downstream processing
WOK
help_commands
end
def utf8
print <<WOK
documents prepared for sisu processing should be stored in utf8
WOK
end
def plaintext
print <<WOK
sisu -A [filename/wildcard] plaintext with dos linefeeds (footnotes follow paragraphs)
sisu -a [filename/wildcard] plaintext with Unix linefeeds (footnotes follow paragraphs)
sisu -E [filename/wildcard] plaintext with dos linefeeds (endnotes follow document)
sisu -e [filename/wildcard] plaintext with Unix linefeeds (endnotes follow document)
sisu -ho [filename/wildcard] exclude ocn, object numbers
WOK
help_commands
end
def html
print <<WOK
sisu -h [filename/wildcard] html document type suffixes included
sisu -H [filename/wildcard] html without document type suffixes
sisu -ho [filename/wildcard] exclude ocn, object numbers
WOK
help_commands
end
def xhtml
print <<WOK
sisu -b [filename/wildcard] xhtml document
WOK
help_commands
end
def xml
print <<WOK
sisu -x [filename/wildcard] xml document (sax type parsing)
sisu -X [filename/wildcard] xml document (dom type parsing)
sisu -o [filename/wildcard] odt document, (odf open document format)
WOK
help_commands
end
def odf
print <<WOK
sisu -o [filename/wildcard] odt document, (odf open document format)
WOK
help_commands
end
def php
print <<WOK
not supported
[php output has been removed]
WOK
help_commands
end
def pdf
print <<WOK
sisu -p [filename/wildcard] produces pdf files from LaTeX output
WOK
help_commands
end
def latex
print <<WOK
sisu -p [filename/wildcard] produces pdf files from LaTeX output
WOK
help_commands
end
def texinfo
print <<WOK
sisu -I [filename] produces texinfo and info files
info and texinfo files are currently left in a separate work/output directory... have not decided what to do with them
on my system info works fine point at file with info command
pinfo, requires you to be within the work/output directory
cd [work/output directory]
and then to point at the file using
pinfo ./[filename]
WOK
help_commands
end
def lout
print <<WOK
sisu -l [filename/wildcard]
not currently supported, revisit someday?
WOK
help_commands
end
def concordance
print <<WOK
sisu -W starts the sisu webrick server, default port 8081
WOK
help_commands
end
def help_search
print <<WOK
SiSU searches,
depending on how you wish to implement search,
the following may bre of interest:
sisu --help sql
sisu --help searchform (or 'sisu --help cgi')
sisu --help hyperestraier (or 'sisu --help est')
sisu --help webrick
WOK
end
def cgi
print <<WOK
sisu -F generates a sample search form
sisu -F --webserv=webrick generates a sample search form for use with the webrick server
sisu -Fv as above, and provides some information on setting up hyperestraier
sisu -W starts the webrick server
the generated search form must be copied to the webserver directory as instructed
WOK
help_search
help_general
end
def sql
print <<WOK
Mappings to two databases are provided by default,
postgresql and sqlite,
the same commands are used within sisu to construct and populate databases
however -d (lowercase) denotes sqlite and -D (uppercase) denotes postgresql
the examples here will used -d (lowercase)
alternatively --sqlite or --pgsql may be used
sisu -d --createdb creates database where no database existed before
sisu -d --create creates database tables where no database tables existed before
sisu -d --dropall destroys database (including all its content)!!
sisu -d --recreate destroys existing database and builds a new empty database structure
sisu -d --import [filename/wildcard] populates database with the contents of the file
sisu -d --update [filename/wildcard] updates file contents in database
sisu -F --webserv=webrick builds a cgi web search frontend for the database created
Postgresql
user: #{@cX.blue}#{@db.user}#{@cX.off}
current db set: #{@cX.blue}#{@db.psql.db}#{@cX.off}
port: #{@cX.blue}#{@db.psql.port}#{@cX.off}
dbi connect: #{@cX.blue}#{@db.psql.dbi}#{@cX.off}
sqlite
current db set: #{@cX.blue}#{@db.sqlite.db}#{@cX.off}
dbi connect #{@cX.blue}#{@db.sqlite.dbi} #{@cX.off}
Note on databases built
By default, [unless otherwise specified] databases are built on a directory basis, from collections of documents within that directory.
The name of the directory you choose to work from is used as the database name,
i.e. if you are working in a directory called #{@cX.blue}#{@env.path.home}/ebook#{@cX.off} the database #{@cX.blue}SiSU_ebook#{@cX.off} is used. [otherwise a manual mapping for the collection is necessary]
WOK
help_search
help_general
end
def webrick
print <<WOK
sisu -W starts the sisu webrick server, default port 8081
WOK
help_commands
end
def hyperestraier
out_dir='(' + `ls #{@env.path.webserv}`.split("\n").join('|') + ')'
print <<WOK
See the documentation for hyperestraier
#{@cX.blue}
http://hyperestraier.sourceforge.net/
file:///usr/share/doc/hyperestraier/index.html
#{@cX.off} #{@cX.orange}
man estcmd
#{@cX.off}
on sisu_hyperestraier:
#{@cX.blue}
man sisu_hyperestraier
/usr/share/doc/sisu/sisu_markup/sisu_hyperestraier/index.html
#{@cX.off}
NOTE: The examples that follow assume that sisu output is placed in the directory
/home/ralph/sisu_www
(A) to generate the index
within the webserver directory to be indexed:
#{@cX.orange}estcmd gather -sd [index name] [directory path to index]#{@cX.off}
the following are examples that will need to be tailored according to your needs:
#{@cX.green}
cd #{@env.path.webserv}
estcmd gather -sd casket #{@env.path.webserv}
#{@cX.off}
you may use the 'find' command together with 'egrep' to limit
indexing to particular document collection directories within
the web server directory:#{@cX.green}
find /home/ralph/sisu_www -type f | egrep '#{@env.path.output}/.+?\.html$' |estcmd gather -sd casket - #{@cX.off}
check which directories in the webserver/output directory #{@cX.green}#{@env.path.webserv}#{@cX.off}
you wish to include in the search index, these appear to be:
#{@env.path.webserv}/#{@cX.green}#{out_dir}#{@cX.off}
as sisu duplicates output in multiple file formats,
it it is probably preferable to limit the estraier index
to html output, and as it may also be desirable to
exclude files 'doc.html' and 'concordance.html', as these
duplicate information held in other html output e.g. #{@cX.green}
find /home/ralph/sisu_www -type f | egrep '/sisu_www/(sisu|bookmarks)/.+?\.html$' | egrep -v '(doc|concordance)\.html$' |estcmd gather -sd casket - #{@cX.off}
from your current document preparation/markup directory, you would construct a rune along the following lines: #{@cX.green}
find /home/ralph/sisu_www -type f | egrep '#{@env.path.webserv}/([specify first directory for inclusion]|[specify second directory for inclusion]|[another directory for inclusion? ...])/.+?\.html$' | egrep -v '(doc|concordance)\.html$' |estcmd gather -sd #{@env.path.webserv}/casket - #{@cX.off}
(B) to set up the search form
(i) copy #{@cX.green}estseek.cgi#{@cX.off} to your cgi directory and set file permissions to 755: #{@cX.green}
sudo cp -vi /usr/lib/estraier/estseek.cgi /usr/lib/cgi-bin
sudo chmod -v 755 /usr/lib/cgi-bin/estseek.cgi
sudo cp -v /usr/share/hyperestraier/estseek.* /usr/lib/cgi-bin #{@cX.off}
[see estraier documentation for paths]
(ii) edit #{@cX.green}estseek.conf#{@cX.off}, with attention to the lines starting 'indexname:' and 'replace:': #{@cX.green}
indexname: #{@env.path.webserv}/casket
replace: ^file://#{@env.path.webserv}{{!}}#{@env.url.webserv_host_base}
replace: /index\.html?${{!}}/ #{@cX.off}
(C) to test using webrick, start webrick: #{@cX.green}
sisu -W #{@cX.off}
and try open the url: #{@cX.blue}
#{@env.url.webserv_host_base}/cgi-bin/estseek.cgi #{@cX.off}
WOK
end
def yaml
print <<WOK
Yaml sisurc files may be used to configure sisu, these are searched for in the following locations:
under the current SiSU markup data directory: #{@cX.blue}#{Dir.pwd}/_sisu/sisurc.yml#{@cX.off}
under the home directory ~/.sisu: #{@cX.blue}#{@env.path.home}/.sisu/sisurc.yml#{@cX.off}
in the "/etc" directory: #{@cX.blue}#{@env.path.etc}/sisurc.yml#{@cX.off}
The Yaml files #{@cX.blue}promo.yml#{@cX.off} and #{@cX.blue}list.yml#{@cX.off} may be used to build a minor right pane in html, they may be placed in the following locations:
under the current SiSU markup data directory: #{@cX.blue}#{Dir.pwd}/_sisu/skin/yml/#{@cX.off}
under the home directory ~/.sisu: #{@cX.blue}#{@env.path.home}/.sisu/skin/yml/#{@cX.off}
in the "/etc" directory: #{@cX.blue}#{@env.path.etc}/skin/yml/#{@cX.off}
these may be called by the sisurc.yml, skins for document, directory or site, or from individual document headers in the header @@promo: [a commented out example header may be found in document sample: free_as_in_freedom.richard_stallman_cru‐ sade_for_free_software.sam_williams.sst, it calls for the specified lists in list.yml, which in turn calls the widgets named in promo.yml which are used to build content in the right pane of html output]
WOK
end
def sitemap
print <<WOK
SiSU sitemaps,
an experimental feature (following g,y,m announcement to use them this week)
sisu -Y [filename/wildcard]
it may be necessary run -m first (generate the the metaverse)
sisu -mY [filename/wildcard]
to generate/update the index of sitemaps
sisu --sitemaps
WOK
end
def license
print <<WOK
* License: GPL 3 or later:
SiSU, a framework for document structuring, publishing and search
Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
2007, 2008 Ralph Amissah
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your option)
any later version.
This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.
You should have received a copy of the GNU General Public License along with
this program. If not, see <#{@cX.blue}http://www.gnu.org/licenses/#{@cX.off}>.
If you have Internet connection, the latest version of the GPL should be
available at these locations:
<#{@cX.blue}http://www.fsf.org/licenses/gpl.html#{@cX.off}>
<#{@cX.blue}http://www.gnu.org/licenses/gpl.html#{@cX.off}>
<#{@cX.blue}http://www.jus.uio.no/sisu/gpl.fsf#{@cX.off}>
* SiSU uses:
* Standard SiSU markup syntax,
* Standard SiSU meta-markup syntax, and the
* Standard SiSU object citation numbering and system
* Hompages:
<#{@cX.blue}http://www.jus.uio.no/sisu#{@cX.off}>
<#{@cX.blue}http://www.sisudoc.org#{@cX.off}>
* Download:
<#{@cX.blue}http://www.jus.uio.no/sisu/SiSU/download.html#{@cX.off}>
Ralph Amissah
<#{@cX.blue}ralph@amissah.com#{@cX.off}>
<#{@cX.blue}ralph.amissah@gmail.com#{@cX.off}>
WOK
end
def standards
print <<WOK
* SiSU uses:
* Standard SiSU markup syntax,
* Standard SiSU meta-markup syntax, and the
* Standard SiSU object citation numbering and system
© Ralph Amissah 1997, current 2005.
All Rights Reserved.
Information on these may be obtained from:
http://www.jus.uio.no/sisu
More information to be provided later.
* however note also the License section
* Ralph Amissah ralph@amissah.com
Ralph Amissah ralph.amissah@gmail.com
WOK
end
def conversion
print <<WOK
sisu_convert does the initial conversion from a couple of file formats to SiSU file format, currently only html and word97
#{@cX.cyan}sisu_convert#{@cX.off} [keyword]
sisu [keyword]
#{@cX.green}--html#{@cX.off} convert from html
#{@cX.green}--pace#{@cX.off} convert from html does some initial headers...
------------------------------------------
Preparing Documents for SiSU
#{@cX.green}--word97#{@cX.off} sisu --help markup (an incomplete overview)
WOK
end
def external_programs
puts <<WOK
external ruby programs
external programs
#{@cX.cyan}pdf output - tex/latex#{@cX.off}
#{@cX.orange}required#{@cX.off}
tex-base/latex
pdfetex aka. pdflatex
#{@cX.brown}suggested/recommended#{@cX.off}
#{@cX.cyan}db/sql output#{@cX.off}
#{@cX.orange}required#{@cX.off}
postgresql
#{@cX.brown}suggested/recommended#{@cX.off}
sqlite
#{@cX.cyan}xml/xhtml/html output#{@cX.off}
#{@cX.orange}required#{@cX.off}
#{@cX.brown}suggested/recommended#{@cX.off}
tidy (xml, xhtml well formed check)
trang (relaxng, rnc to dtd conversion)
WOK
end
def scratch
print <<WOK
Types of tag,
then there are various tags which occur within the document.
Structural tags, which consist of:
heading tags that identify headings within text, and;
footnote/endnote tags ...
Markup instructions: giving information as to what is to be done to the presentation of the text
Markup tags
These have been kept to a minimum. A number of text html markup tags can be used <b>to bold</b> <i>to indent</i> <sup>for superscript</sup> <sub>for subscript text</sub>
_1 at the beginning of a line indents the paragraph
_2 at the beginning of a line double indents the paragraph
Others include
Other things to note:
By default paragraphs are automatically numbered... and is the same across all output formats
This makes citation a lot easier... regardless of the form of output that is being looked at
It also permits the building of various addons, like the concordance feature which identifies each word and the paragraphs in which the word appears with links to the paragraph...
Urls are automatically turned to live links in the html and pdf files created...
WOK
end
end
end
__END__
|