File: chapter-installation.xml

package info (click to toggle)
refdb 1.0.2-3
  • links: PTS, VCS
  • area: main
  • in suites: jessie, jessie-kfreebsd
  • size: 18,276 kB
  • ctags: 2,640
  • sloc: ansic: 62,664; xml: 40,766; sh: 6,524; perl: 2,402; php: 1,821; makefile: 666; sql: 2
file content (1324 lines) | stat: -rw-r--r-- 114,183 bytes parent folder | download
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
<?xml version="1.0"?>
<chapter id="chapter-installation">
  <title>Installation</title>
  <para>This chapter tries to explain the process of the installation. There are some things you should consider before you actually install the software. These will be discussed in the second section. The technical details of the installation on various platforms can be found in the following sections of this chapter. The final sections deal with the setup of optional web-based frontends. But first we start with a brief overview of installing and running RefDB for those who never read manuals.</para>
  <sect1>
    <title>Quickstart guide</title>
    <para>These are the essential steps to get your reference database up and running:</para>
    <procedure>
      <step performance="required">
	<para>Follow the installation instructions for either <link linkend="sect1-installation-linux">Unix/Linux</link> or <link linkend="sect1-installation-windows">Windows</link>.</para>
      </step>
      <step performance="required">
	<para><link linkend="sect1-set-up-database">Finish the installation</link> by creating and filling the internal database.</para>
      </step>
      <step performance="required">
	<para>Start the application server refdbd, either <link linkend="refentry-refdbd">manually</link> or as a daemon, as explained in the OS-specific installation sections.</para>
      </step>
      <step performance="required">
	<para><link linkend="sect1-create-database">Create</link> one or more reference databases.</para>
      </step>
      <step performance="required">
	<para><link linkend="sect1-add-user">Add</link> one or more users that are permitted to work with this database (not required if you use the SQLite database engine as it lacks access control).</para>
      </step>
      <step performance="required">
	<para><link linkend="sect1-add-bibstyles">Add</link> bibliography styles.</para>
      </step>
    </procedure>
    <para>Some of the above steps are simplified by the shell script <link linkend="refentry-refdb-init">refdb-init</link> which you should have a thorough look at. Then it is up to the users to populate the database with references, run their queries, create bibliographies, and whatever they may desire.</para>
  </sect1>
  <sect1>
    <title>Upgrading from an older version</title>
    <para>If you already run an older version of RefDB and want to upgrade to the latest version, you may have to change a few things in your local setup in order to reuse existing databases and existing configuration files. This section lists all backwards-incompatible changes of the past few versions (the complete list since the days of yore can be found in the file <filename moreinfo="none">README</filename>).</para>
    <note>
      <para>The file <filename moreinfo="none">UPGRADING</filename> contains instructions how to avoid losing your data in the case of non-trivial changes in the new version.</para>
    </note>
    <sect2>
      <title>0.9.9</title>
      <itemizedlist>
	<listitem>
	  <para>Major changes in both the reference databases and the main database require to upgrade both.</para>
	  </listitem>
	  <listitem>
	    <para>Before re-importing your reference data, you may have to migrate the contents of some AV fields to L1</para>
	</listitem>
	<listitem>
	  <para>Before re-importing custom citation styles, you may have to fix a few elements. The styles shipped with RefDB do not require these fixes, you can just add them again.</para>
	</listitem>
      </itemizedlist>
    </sect2>
    <sect2>
      <title>0.9.8</title>
      <itemizedlist>
	<listitem>
	  <para>The implementation of personal reference lists has changed, most notably in that each user can have more than one of these lists. Although there was no need to alter the database schema, one of the tables is now used to record the ownership of a reference instead of the membership of a reference in a personal list. The results may be a bit unexpected if you upgrade to 0.9.8 without migrating the data.</para>
	</listitem>
      </itemizedlist>
    </sect2>
    <sect2>
      <title>0.9.7</title>
      <itemizedlist>
	<listitem>
	  <para>The main database needs to be re-created if you use MySQL as a database engine.</para>
	</listitem>
      </itemizedlist>
    </sect2>
  </sect1>
  <sect1>
    <title>Things to know before you start</title>
    <sect2>
      <title>Which database server?</title>
      <para>RefDB currently supports MySQL and PostgreSQL as external database servers as well as SQLite as an embedded database engine. This section tries to help you decide which one to pick.</para>
      <para>The first issue is whether you want to run an external database server or not. External database servers scale better if many users share databases and they provide access control. The external database servers also use more fine-grained locking mechanisms which allow concurrent read and write accesses, whereas the SQLite engine will lock the entire database for write accesses. However, the latter does not provide access control and thus doesn't require any sort of user administration.</para>
      <formalpara>
	<title>Rule #1</title>
	<para>If you don't intend to share databases, or if running a database server scares you in any way, then you may better off with SQLite.</para>
      </formalpara>
      <para>Another issue is the way how the database engines store their data. SQLite is unique in that it uses a single architecture-independent file per database which makes transferring the data to a different box a breeze. The external database engines use more sophisticated ways to organize their data, but you need some basic administrative skills in order to replicate the data.</para>
      <formalpara>
	<title>Rule #2</title>
	<para>If you cannot rely on remote access to your databases (something which RefDB is well suited for) but have to take your data physically with you while travelling, SQLite is a better choice.</para>
      </formalpara>
      <para>Now some words about the external database servers. As with many other fundamental schisms in the Unix world (vi vs. Emacs, KDE vs. Gnome, to name a few), both database servers supported by RefDB have followers who are semi-religious about their choice. Both MySQL and PostgreSQL are robust and well-proven. This leads us to:</para>
      <formalpara>
	<title>Rule #3</title>
	<para>If you already use one of the servers, then by all means use it also for RefDB. Being familiar with the server and having it happily running usually outweighs any advantages that the other server might have.</para>
      </formalpara>
      <para>But what if you do not yet run a suitable database server? You can browse the web and read for hours about the differences between MySQL and PostgreSQL, but for the purpose of managing RefDB reference databases it boils down to one essential difference: MySQL is faster.</para>
      <para>This leads us to:</para>
      <formalpara>
	<title>Rule #4</title>
	<para>If you cherish speed over anything else, use MySQL.</para>
      </formalpara>
      <note>
	<para>There's a few more differences that you should be aware of: PostgreSQL has transaction support by default. MySQL supports transactions only if you use InnoDB tables. If you want this additional peace of mind from MySQL, make sure InnoDB is the default table type. SQLite does not support Unix-style regular expressions. If you'd like to use these more versatile expressions instead of the simpler SQL regular expressions supported by SQLite, choose MySQL or PostgreSQL.</para>
      </note>
    </sect2>
    <sect2>
      <title>Where do the components go?</title>
      <para>As RefDB is a three-tiered client-server application, you have considerable freedom to distribute the components among your computers. Although RefDB shines in a network environment, there is absolutely no problem to run all components on a single standalone workstation.</para>
      <note>
	<para>Please keep in mind that there's one tier less if you choose the SQLite embedded database engine. The databases will always be on the filesystem of the machine that runs refdbd (this doesn't exclude putting the files on an NFS share if you have a good reason to do so).</para>
      </note>
      <para>The basic idea of the client-server model has several implications:</para>
      <itemizedlist>
	<listitem>
	  <para>Many workstations can access a single server running the database server. Thus many people can access the same databases without the pain of duplicating the data and the database engine on every single machine.</para>
	</listitem>
	<listitem>
	  <para>A considerable part of the computing effort is done outside of the workstations. Therefore even rather lame workstations may be sufficient to access and manipulate the data. The database server should run on a decent machine, though (better not that dusty 486 that has doubled as a paperweight since 1990).</para>
	</listitem>
	<listitem>
	  <para>Updates of the software will mainly affect the database server and the application server. This considerably reduces your workload, as the workstations need to be updated less frequently.</para>
	</listitem>
      </itemizedlist>
      <para>The most common scenarios for using RefDB will be on a department or institute network and on a standalone workstation. Let's see how these scenarios differ:</para>
      <sect3>
	<title>Installation on a standalone workstation</title>
	<para>This is obviously the simplest case. The clients, the application server, the database server, and the databases reside on the same physical machine (see <xref linkend="figure-standalone"/>). The only requirement for the workstation is that a TCP/IP network is installed. This is necessary as the three layers of RefDB always communicate via TCP/IP sockets. The IP address 127.0.0.1 has to be specified in the configuration files of the clients and of the application server.</para>
	<figure float="0" id="figure-standalone">
	  <title>RefDB on a standalone workstation</title>
	  <mediaobject>
	    <imageobject role="html">
	      <imagedata format="PNG" fileref="refdbmanualfig2.png"/>
	    </imageobject>
	    <imageobject role="fo">
	      <imagedata format="SVG" fileref="refdbmanualfig2.svg"/>
	    </imageobject>
	  </mediaobject>
	</figure>
      </sect3>
      <sect3>
	<title>Installation in a network</title>
	<para>In a network you can take advantage of the client-server model and distribute the workload between your computers. Although the three layers can well be distributed between three physical machines, it may be more useful to install the application server on the same machine as the database server and the databases (see <xref linkend="figure-network"/>). A dedicated or general-purpose server may be most suitable to hold these components, as a workstation may get sluggish if it has to answer a lot of database requests.</para>
	<para>The clients as well as scripts and support files have to be installed on all workstations that will be used to access the databases. The client for administrative tasks, <application moreinfo="none">refdba</application>, can be restricted to the workstations of system administrators or otherwise experienced staff.</para>
	<figure float="0" id="figure-network">
	  <title>RefDB on a network</title>
	  <mediaobject>
	    <imageobject role="html">
	      <imagedata format="PNG" fileref="refdbmanualfig3.png"/>
	    </imageobject>
	    <imageobject role="fo">
	      <imagedata format="SVG" fileref="refdbmanualfig3.svg"/>
	    </imageobject>
	  </mediaobject>
	</figure>
      </sect3>
    </sect2>
    <sect2 id="sect1-mystery-init-files">
      <title>The mystery of the configuration files</title>
      <para>Like with most Unix-style software packages, the behaviour of the RefDB applications can be tweaked by configuration files. Wherever it makes sense, there is one global config file with useful admin-picked defaults, and another user config file for the individual user to play with. The purpose of the configuration files is to set some reasonable default values for the command-line switches of the RefDB programs. Once you have set these, you will never have to specify these values on the command line again, unless you want to temporarily override them.</para>
      <sect3>
	<title>Types of configuration files</title>
	<para>All RefDB applications and scripts that use configuration files (these are the server <link linkend="chapter-refdbd">refdbd</link>, the clients <link linkend="chapter-refdbc">refdbc</link>, <link linkend="chapter-refdbib">refdbib</link>, <link linkend="chapter-refdba">refdba</link>, the script <link linkend="refdbxml-configuration">refdbxml</link>, as well as the conversion filters <link linkend="refentry-bib2ris">bib2ris</link>, <link linkend="refentry-db2ris">db2ris</link>, <link linkend="refentry-med2ris">med2ris.pl</link>, <link linkend="refentry-marc2ris">marc2ris</link>, and <link linkend="refentry-en2ris">en2ris</link>) can use two configuration files each. One global configuration file is supplied by the system administrator and can be used to set values that are common for all users on that box, like the IP address of the application server. Another file can be used by every user to supply the values that were not set in the global file or to override settings in this file. The users' copies can have a leading dot to hide the files (the refdb programs will first try to read a hidden configuration file, and only if that cannot be found they try to read a non-hidden file).</para>
	<para>bib2ris, marc2ris, and med2ris use a second global configuration file if they are run as a CGI applications. A local configuration file does not make sense in this case.</para>
	<para>The default location for the global configuration files is <filename moreinfo="none">/usr/local/etc/refdb</filename>. There are two ways to change this. If you compile RefDB from the sources you can specify a different directory with the <option>--prefix</option> or <option>--sysconfdir</option> options of <command moreinfo="none">./configure</command>. E.g. if you specify <option>--sysconfdir=/etc</option>, then the configuration files will be installed in <filename class="directory" moreinfo="none">/etc/refdb</filename> (the <filename moreinfo="none">refdb</filename> part is automatically appended by the RefDB install routines). If you use precompiled binaries, use the <option>-y</option> command line option to specify the directory. In this case you have to specify the full path, i.e. <filename class="directory" moreinfo="none">/etc/refdb</filename> to read the configuration files installed by the previous example.</para>
	<para>The user copies of the client configuration files are expected to be in the users' home directories as specified by the environment variable <envar>HOME</envar>.</para>
      </sect3>
      <sect3>
	<title>Configuration file syntax</title>
	<para>All configuration files share a common syntax. There are just three essential things to know:</para>
	<itemizedlist>
	  <listitem>
	    <para>All information is stored as pairs of whitespace-separated items, one pair on each line. The first item on the line specifies the variable name, the second item specifies the variable value. Whitespace means one or more spaces or tabs in any combination.</para>
	  </listitem>
	  <listitem>
	    <para>Everything to the right of a hash sign (#) is a comment. The rest of the line is ignored.</para>
	  </listitem>
	  <listitem>
	    <para>The line endings are Unix-style (0x10, not DOS-style 0x13 0x10), regardless of the operating system.</para>
	  </listitem>
	</itemizedlist>
      </sect3>
      <sect3>
	<title>A configuration example</title>
	<para>The whole configuration stuff may sound a bit confusing, so let us now look at a simple configuration example that illustrates the principles laid out above.</para>
	<para>The following is a listing of <filename moreinfo="none">/usr/local/etc/refdb/refdbcrc</filename>, our global refdbc configuration file in this example:</para>
	<programlisting format="linespecific"># This is the global configuration file for refdbc
serverip	127.0.0.1
port	9734
pager	more
timeout	180
# end of refdbcrc
	</programlisting>
	<para>This is the corresponding copy that one of the users of the system created as <filename moreinfo="none">/home/joe/.refdbcrc</filename>:</para>
	<programlisting format="linespecific"># This is the user configuration file for refdbc
pager	less
username	joesixpack
passwd  * 
timeout	30
# end of .refdbcrc
	</programlisting>
	<para>As you can see our hypothetical system administrator configured the IP address (<varname>serverip</varname>) and the <varname>port</varname> where refdbd listens to the client requests. This value is most likely the same for all users on the system, so this is nothing to worry about for the users. <filename moreinfo="none">more</filename> is defined as the default <varname>pager</varname>, and the <varname>timeout</varname> is set to 3&#x00A0;minutes.</para>
	<para>Joe Sixpack, our reckless user, does not like <filename moreinfo="none">more</filename> as a pager and prefers to use <filename moreinfo="none">less</filename> instead. He also thinks that half a minute as a timeout should be enough. Both of these settings override the corresponding values in the global file. <varname>serverip</varname> and <varname>port</varname> are not redefined in the user's copy, so the values of the global file take effect. Joe also defined <varname>username</varname> (which happens to be different from his login name "joe") and <varname>passwd</varname> so the correct values will be used for the database access (the asterisk in the <varname>passwd</varname> field will cause refdbc to ask for the password interactively for security reasons).</para>
      </sect3>
      <sect3>
	<title>Configuration file variables</title>
	<para>For a listing of available configuration file variables please see the tables for <link linkend="refdba-configuration">refdba</link>, <link linkend="refdbc-configuration">refdbc</link>, <link linkend="refdbib-configuration">refdbib</link>, <link linkend="refdbd-configuration">refdbd</link>, <link linkend="refdbxml-configuration">refdbxml</link>, <link linkend="bib2ris-configuration">bib2ris</link>, <link linkend="db2ris-configuration">db2ris</link>, <link linkend="med2ris-configuration">med2ris</link>, <link linkend="marc2ris-configuration">marc2ris</link>, and <link linkend="en2ris-configuration">en2ris</link>.</para>
      </sect3>
    </sect2>
    <sect2>
      <title>Environment variables</title>
      <para>refdb uses the following environment variables to locate the files and directories it needs to run properly.</para>
      <variablelist>
	<varlistentry>
	  <term>HOME</term>
	  <listitem>
	    <para>This variable should be set for all users anyway. It is used to locate the personal <link linkend="sect1-mystery-init-files">configuration files</link> for the RefDB clients.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>SGML_CATALOG_FILES</term>
	  <listitem>
	    <para>If you process SGML files, this variable will be consulted to locate the catalog files required for resolving public identifiers to their local filename equivalents.</para>
	    <note>
	      <para>On some systems, the package system maintains a master catalog whose path is hard-coded into the SGML applications. In this case, the variable is not required.</para>
	    </note>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>XML_CATALOG_FILES</term>
	  <listitem>
	    <para>If you process XML files, this variable may be consulted to locate XML catalogs. If this variable is not set, many tools look into the default location <filename moreinfo="none">/etc/xml/catalog</filename> instead. Remember that some XSLT processors need access to additional Java classes to provide XML catalog support at all.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>
    <sect2>
      <title>Some notes on the filesystem</title>
      <para>The default installation procedure will install the RefDB files in locations compatible with the filesystem hierarchy standard. You will learn in the following sections how to change where the RefDB files will be installed if you want to adapt the installation to specific needs of your system. To get a better idea of what you have to take care of if you don't like the defaults, here is a list of the directories used by RefDB:</para>
      <variablelist>
	<varlistentry>
	  <term>
	    <filename class="directory" moreinfo="none">/usr/local/bin</filename>
	  </term>
	  <listitem>
	    <para>This directory will receive all binary files and shell scripts.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>
	    <filename class="directory" moreinfo="none">/usr/local/etc/refdb</filename>
	  </term>
	  <listitem>
	    <para>All global RefDB configuration files end up in this directory.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>
	    <filename class="directory" moreinfo="none">/usr/local/share/refdb</filename>
	  </term>
	  <listitem>
	    <para>This directory contains shareable, operating system independent files. The files are organized in a couple of subdirectories:</para>
	    <itemizedlist>
	      <listitem>
		<para><filename class="directory" moreinfo="none">css</filename> contains a cascading stylesheet suitable for the HTML output of the <link linkend="app-c-command-getref"><command moreinfo="none">getref</command></link> command.</para>
	      </listitem>
	      <listitem>
		<para><filename class="directory" moreinfo="none">declarations</filename> contains the default SGML declarations.</para>
	      </listitem>
	      <listitem>
		<para><filename class="directory" moreinfo="none">dsssl</filename> contains DSSSL stylesheets.</para>
	      </listitem>
	      <listitem>
		<para><filename class="directory" moreinfo="none">dtd</filename> contains the document type definitions used by RefDB.</para>
	      </listitem>
	      <listitem>
		<para><filename class="directory" moreinfo="none">examples</filename> contains a few example reference data files as well as SGML and XML test documents using RefDB citations.</para>
	      </listitem>
	      <listitem>
		<para><filename class="directory" moreinfo="none">sql</filename> contains SQL scripts used to initialize databases.</para>
	      </listitem>
	      <listitem>
		<para><filename class="directory" moreinfo="none">sru</filename> contains the XSLT and CSS stylesheets required to set up the SRU service</para></listitem>
	      <listitem>
		<para><filename class="directory" moreinfo="none">styles</filename> contains some XML files containing bibliography styles.</para>
	      </listitem>
	      <listitem>
		<para><filename class="directory" moreinfo="none">xsl</filename> contains XSLT stylesheets.</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>
	    <filename class="directory" moreinfo="none">/usr/local/var/lib/refdb/db</filename>
	  </term>
	  <listitem>
	    <para>holds the database files of embedded database engines and a version file for use by package installation scripts</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>
  </sect1>
  <sect1 id="sect1-installation-linux">
    <title>Installation on Linux and other Unix variants</title>
    <para>RefDB was designed with portability in mind. Thanks to the GNU autotools installation on many Unix variants is straightforward, others need only a little tweaking. The following instructions provide a guideline for all Unix-like systems. Please see also the hints for specific operating systems at the end of this section.</para>
    <sect2 id="sect2-generic-instructions">
      <title>Generic instructions</title>
      <sect3>
	<title>Prerequisites</title>
	<para>These instructions assume that the following software is installed and functional on your computer or on your network before you start:</para>
	<itemizedlist>
	  <listitem>
	    <para>A SQL database engine. For an external database server, choose between <ulink url="http://www.mysql.com">MySQL</ulink> (version 3.23 or later) or <ulink url="http://www.postgresql.org">PostgreSQL</ulink> (version 7.1 or later). The database server does not have to physically run on the box(es) where you plan to install RefDB, it is sufficient if it is accessible through the network.</para>
	    <para>If you prefer an embedded database engine, please use <ulink url="http://www.sqlite.org">SQLite</ulink> instead.</para>
	  </listitem>
	  <listitem>
	    <para>As far as non-standard libraries and header files are concerned, you'll need the readline library and headers (available at the <ulink url="ftp://ftp.gnu.org/readline/">GNU FTP site</ulink>). Database access requires the <ulink url="http://sourceforge.net/projects/libdbi">libdbi library</ulink> and headers as well as the <ulink url="http://sourceforge.net/projects/libdbi-drivers">libdbi-drivers</ulink> package. Furthermore, you`ll need the <ulink url="http://sourceforge.net/projects/expat">expat</ulink> library. If you need the BibTeX import filter, you'll also want to have the <ulink url="http://www.ctan.org/tex-archive/biblio/bibtex/utils/btOOL/">btparse</ulink> library.</para>
	    <note>
	      <para>Some operating systems/distributions use separate packages for the run-time libraries (ususally <filename moreinfo="none">.so</filename> files) and for the development libraries (usually <filename moreinfo="none">.a</filename> files). In order to build and run RefDB, you need both packages for each library.</para>
	    </note>
	  </listitem>
	  <listitem>
	    <para>If you want to import Pubmed or MARC datasets, please get the <ulink url="http://sourceforge.net/projects/refdb">refdb-perlmod</ulink> package. This collection of Perl modules is required to run the Pubmed and MARC import filters shipped with RefDB. These Perl modules in turn depend on MARC::Record, MARC::Charset, XML::Parser, and Text::Iconv, available at <ulink url="http://www.cpan.org">CPAN</ulink>.</para>
	  </listitem>
	</itemizedlist>
      </sect3>
      <sect3 id="sect-install-from-sources-unix">
	<title>Installation from the sources</title>
	<note>
	  <para>The installation steps proper (as opposed to the build steps) should be run with root privileges.</para>
	</note>
	<procedure>
	  <step performance="required">
	    <para>Unpack the archive in a convenient directory: <command moreinfo="none">tar -xzf refdb-x.y.z.tar.gz</command> (the actual filename depends on the version).</para>
	  </step>
	  <step performance="optional">
	    <para>If you do not want to build in the source directory, create an empty build directory.</para>
	  </step>
	  <step performance="required">
	    <para>cd into the new <filename class="directory" moreinfo="none">refdb-x.y.z</filename> source directory or into your separate build directory</para>
	  </step>
	  <step performance="required">
	    <para>Use <command moreinfo="none">./configure --help</command> to see a list of things you can customize. If you use a separate build directory, use the relative path to <filename moreinfo="none">configure</filename> in the source directory. Some important options are:</para>
	    <note>
	      <para>All paths and URLs in the following options should be entered without a trailing slash.</para>
	    </note>
	    <variablelist>
	      <varlistentry>
		<term>--prefix=PREFIX</term>
		<listitem>
		  <para>By default, all files will be installed in the <filename class="directory" moreinfo="none">/usr/local</filename> tree. Use this option to use a different install root, e.g. <filename class="directory" moreinfo="none">/usr</filename> or <filename class="directory" moreinfo="none">/opt</filename>.</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>--datadir=DIR</term>
		<listitem>
		  <para>The data files will be installed in <filename class="directory" moreinfo="none">/usr/local/share/refdb</filename> unless you use this option. The data will be installed in the directory <filename class="directory" moreinfo="none">DIR/refdb</filename>. That is, specifying "--datadir=/usr/local/share" is equivalent to the default behaviour. The configuration variable <varname>refdblib</varname> (which will be automatically generated in the example configuration files) must point to the RefDB data directory.</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>--sysconfdir=DIR</term>
		<listitem>
		  <para>The global configuration files will be installed in <filename class="directory" moreinfo="none">/usr/local/etc/refdb</filename> unless you specify a different directory here.</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>--with-libdbi-lib=DIR</term>
		<listitem>
		  <para>Use this option to specify the directory that contains the libdbi library if it is not in the default library path.</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>--with-expat-lib=DIR</term>
		<listitem>
		  <para>Use this option to specify the directory that contains the expat library if it is not in the default library path.</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>--with-btparse-lib=DIR</term>
		<listitem>
		  <para>Use this option to specify the directory that contains the btparse library if it is not in the default library path.</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>--with-sgml-declaration=PATH</term>
		<listitem>
		  <para>Specify the full path to a suitable SGML declaration for your SGML files. If this option is not used, RefDB will use its own copy of <filename moreinfo="none">docbook.dcl</filename> stolen from the DocBook DTD distribution. This SGML declaration also works for a variety of other DTDs.</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>--with-xml-declaration=PATH</term>
		<listitem>
		  <para>Specify the full path to <filename moreinfo="none">xml.dcl</filename> which is the SGML declaration for XML files. If this option is not used, RefDB will use its own copy of <filename moreinfo="none">xml.dcl</filename> which should work just fine.</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>--with-docbook-xsl=PATH</term>
		<listitem>
		  <para>Specify the full path to the root directory of the DocBook XSL stylesheets.</para>
		  <note>
		    <para>This option is required only on systems that do not maintain XML catalogs. If your system is set up properly to resolve public identifiers like those in the XSL stylesheets by XML catalogs, leave out this option. <command moreinfo="none">configure</command> checks whether the required stylesheets are accessible, so watch out for error messages. If the stylesheets can't be found, either install them, fix your catalogs, or use this option to hardcode the path.</para>
		  </note>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>--with-docbook-xsl-ns=PATH</term>
		<listitem>
		  <para>Specify the full path to the root directory of the DocBook XSL-NS (for DocBook V5.0 and later) stylesheets.</para>
		  <note>
		    <para>This option is required only on systems that do not maintain XML catalogs. If your system is set up properly to resolve public identifiers like those in the XSL stylesheets by XML catalogs, leave out this option. <command moreinfo="none">configure</command> checks whether the required stylesheets are accessible, so watch out for error messages. If the stylesheets can't be found, either install them, fix your catalogs, or use this option to hardcode the path.</para>
		  </note>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>--with-tei-xsl=PATH</term>
		<listitem>
		  <para>Specify the full path to the root directory of the TEI XSL stylesheets for P4.</para>
		  <note>
		    <para>As mentioned above for the DocBook stylesheets, use this option only if your catalogs cannot resolve the public identifiers properly. The <ulink url="http://www.tei-c.org">TEI Consortium</ulink> ships <ulink url="http://sourceforge.net/project/showfiles.php?group_id=106328&amp;package_id=141124">tei-xsl-5.2.9.zip</ulink> which contains the stylesheets for both p4 and p5. The root directory which you want to specify here is the directory which contains the p4 and p5 subdirectories, e.g. <filename class="directory" moreinfo="none">/usr/local/share/xsl/tei-xsl-5.2.9</filename>.</para>
		  </note>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>--with-tei-xsl-ns=PATH</term>
		<listitem>
		  <para>Specify the full path to the root directory of the TEI XSL stylesheets for P5.</para>
		  <note>
		    <para>As mentioned above for the DocBook stylesheets, use this option only if your catalogs cannot resolve the public identifiers properly. The <ulink url="http://www.tei-c.org">TEI Consortium</ulink> ships <ulink url="http://sourceforge.net/project/showfiles.php?group_id=106328&amp;package_id=141124">tei-xsl-5.2.9.zip</ulink> which contains the stylesheets for both p4 and p5. The root directory which you want to specify here is the directory which contains the p4 and p5 subdirectories, e.g. <filename class="directory" moreinfo="none">/usr/local/share/xsl/tei-xsl-5.2.9</filename>.</para>
		  </note>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>--with-classpath-root=PATH</term>
		<listitem>
		  <para>The refdbxml script assumes that all Java classes for the Java parsers and xslt engines are stored in a class repository, i.e. all in the same directory. Specify this directory with this option. If you keep the relevant Java classes in different directories, either create symlinks or customize refdbxml manually.</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>--with-var-dir=PATH</term>
		<listitem>
		  <para>Use this option to specify a directory where refdbd can write its PID file (a file containing the process ID). By default, <filename class="directory" moreinfo="none">/var/run</filename> will be used.</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>--with-log-dir=PATH</term>
		<listitem>
		  <para>Use this option to specify a directory where RefDB programs can write log files to, if logging is directed to a custom file. By default, <filename class="directory" moreinfo="none">/var/log</filename> will be used.</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>--with-main-db=dbname</term>
		<listitem>
		  <para>RefDB uses one main database to store citation styles and other stuff. There is exactly one such database per installation with the default name <filename moreinfo="none">refdb</filename>.  You may have to change this name if you want to run two different versions of RefDB in parallel, or if you're not free to choose your database name. Although the main database name is configurable at runtime, you should use this option to initialize your <filename>refdbdrc</filename> configuration file, as it allows the <link linkend="refentry-refdb-init">refdb-init</link> script to use the proper database name.</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>--with-db-dir</term>
		<listitem>
		  <para>Selects the directory which holds SQLite/SQLite3 databases.</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>--with-trang-jar</term>
		<listitem>
		  <para>Specifies the full path to the jar file of the <ulink url="http://www.thaiopensource.com/relaxng/trang.html">trang</ulink> tool. You need this tool if you build RefDB from SVN sources, but not if you build from a tarball.</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>--disable-docs</term>
		<listitem>
		  <para>RefDB ships with prebuilt docs. However, if you build a SVN version, or if the documentation is otherwise screwed up, you may have to build them. Building the docs from the sources requires a couple of extra tools. You can use this configure switch to build the rest of RefDB without having to install these tools.</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>--disable-clients</term>
		<listitem>
		  <para>Use this switch if you want to build and install only the application server <filename>refdbd</filename>. This is mainly targeted at package builders.</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>--disable-server</term>
		<listitem>
		  <para>Use this switch if you want to build and install only the clients but not the application server. This is mainly targeted at package builders.</para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	    <para>Some of these options are used to customize the shell scripts, XSL stylesheets, example configuration files, and HTML files which are part of RefDB. If you do not specify these options now, you can still build and install the package, but you will have to customize the scripts and stylesheets manually in order to make them work. Doing it now is <emphasis>much</emphasis> easier. You've been warned.</para>
	    <para>Start the configuration with the command <command moreinfo="none">./configure</command>, specifying any additional options as you may need. Use the relative path to <filename moreinfo="none">configure</filename> in the source directory if you build in a separate directory.</para>
	    <note>
	      <para>If your system keeps non-system header files in odd places, it may be necessary to set the <envar>CFLAGS</envar> environment variable before you run <filename moreinfo="none">configure</filename>. E.g. if headers like <filename moreinfo="none">expat.h</filename> are stored in <filename class="directory" moreinfo="none">/usr/local/include</filename>, you should run <command moreinfo="none">CFLAGS="-I/usr/local/include" ./configure</command> instead, specifying additional options as necessary.</para>
	    </note>
	  </step>
	  <step performance="required">
	    <para>
	      <command moreinfo="none">make</command>
	    </para>
	    <note>
	      <para>The autotools-generated Makefiles apparently prefer (or require?) GNU make. If <command moreinfo="none">make</command> results in spurious error messages <emphasis>about the Makefile syntax</emphasis>, try to run <command moreinfo="none">gmake</command> instead as your regular <filename moreinfo="none">make</filename> is apparently not the GNU version.</para>
	    </note>
	  </step>
	  <step performance="required">
	    <para>
	      <command moreinfo="none">make install</command>
	    </para>
	    <para>This will install the binaries and scripts in <filename class="directory" moreinfo="none">/usr/local/bin</filename> and the data in <filename class="directory" moreinfo="none">/usr/local/share/refdb</filename> unless you chose different directories in the configure step. Again, run <command moreinfo="none">gmake install</command> instead if your regular <filename moreinfo="none">make</filename> is not the GNU version.</para>
	  </step>
	  <step performance="required">
	    <para>To finish the installation, please follow the instructions in the section <link linkend="sect1-set-up-database">Finishing the RefDB installation</link> below.</para>
	  </step>
	</procedure>
	<para>If this procedure results in strange error messages, you probably use a platform that is not supported yet. The author appreciates a porting effort or a description of the problem (in this particular order).</para>
      </sect3>
      <sect3>
	<title>Living on the bleeding edge: installing a SVN version</title>
	<para>While the official release versions of RefDB are your best bet to get a stable installation, you may be interested to test the latest developments "in statu nascendi". The SVN version is guaranteed to compile on the author's development platform (currently FreeBSD 6.1), but may fail on other platforms. Known bugs may have been fixed, but new ones may have crept in as well. New features may be implemented, but might not be without problems. You've been warned. If you still want to go ahead, this is what you need to do:</para>
	<procedure>
	  <step performance="required">
	    <para>Change into a suitable directory. SVN will create a subdirectory called <filename class="directory" moreinfo="none">refdb</filename> during the following steps</para>
	  </step>
	  <step performance="required">
	    <para>Run the following command (adapt this accordingly if you use some graphical CVS frontend instead of the command line tool):</para>
	    <screen format="linespecific">
	      <prompt moreinfo="none">$~/build </prompt>
	      <userinput moreinfo="none">svn co https://svn.sourceforge.net/svnroot/refdb/refdb/trunk refdb</userinput>
	    </screen>
	    <para>Other interesting modules to check out are <filename moreinfo="none">perlmod</filename> (the Perl modules and the Perl client library) and <filename moreinfo="none">elisp</filename> (the Emacs support files).</para>
	    <para>If you are interested in a particular repository version, release, or branch, use commands along these lines:</para>
	    <screen format="linespecific">
	      <prompt moreinfo="none">$~/build </prompt>
	      <userinput moreinfo="none">svn co --revision 324 https://svn.sourceforge.net/svnroot/refdb/refdb/trunk refdb-324</userinput>
	      <userinput moreinfo="none">svn co https://svn.sourceforge.net/svnroot/refdb/refdb/tags/Release-0.9.7 refdb-0.9.7</userinput>
	      <userinput moreinfo="none">svn co https://svn.sourceforge.net/svnroot/refdb/refdb/branches/back-to-a-1-branch refdb-a1-branch</userinput>
	    </screen>
	  </step>
	  <step performance="required">
	    <para>If you want to keep track of the latest developments, you'll have to update your SVN working copy once in a while. Run this command from within the top-level source directory:</para>
	    <screen format="linespecific">
	      <prompt moreinfo="none">$~/build/refdb </prompt>
	      <userinput moreinfo="none">svn update</userinput>
	    </screen>
	    <para>Consider subscribing to the refdb-cvs mailing list as you'll be notified about each SVN checkin.</para>
	  </step>
	  <step performance="required">
	    <para>The SVN version lacks all autotool-generated files. You'll have to create them with your local autotools. RefDB contains a small script called <filename moreinfo="none">autogen.sh</filename> in its top-level directory which performs all necessary steps.</para>
	    <screen format="linespecific">
	      <prompt moreinfo="none">$~/build/refdb </prompt>
	      <userinput moreinfo="none">./autogen.sh</userinput>
	    </screen>
	    <note>
	      <para>The autotools can cause severe headaches at times. If the above command causes errors, read <filename moreinfo="none">autogen.sh</filename> and run the commands manually, substituting different versions as appropriate. E.g. substitute <command moreinfo="none">automake</command> with <command moreinfo="none">automake-1.8</command> if this gives better results. The native autotools shipped with FreeBSD 5.4 and later are unusable for our purposes, you have to install the gnu-autotools package instead. You have to modify your <envar>PATH</envar> to pick up the latter, and fiddle with the m4 macro paths in order to see the light.</para>
	    </note>
	  </step>
	  <step performance="required">
	    <para>The SVN version also lacks a few other things which are included in the source tarballs. In order to create the missing stuff, you'll need the following additional tools:</para>
	    <itemizedlist>
	      <listitem>
		<para><ulink url="http://xml.apache.org/batik/svgrasterizer.html">Batik SVG Rasterizer</ulink>: an image converter used to create the images from the <acronym>SVG</acronym> sources. The Makefile calls a script in your path called <filename moreinfo="none">rasterizer</filename> which is supposed to run this Java application appropriately.</para>
	      </listitem>
	      <listitem>
		<para><ulink url="http://dtdparse.sourceforge.net">dtdparse</ulink>: a Perl script (which in turn depends on a few Perl modules, see the installation instuctions) which generates the DTD documentation.</para>
	      </listitem>
	      <listitem>
		<para><ulink url="http://www.thaiopensource.com/relaxng/trang.html">trang</ulink>: a tool required to turn the RefDB DTDs into RelaxNG schemas.</para>
	      </listitem>
	    </itemizedlist>
	    <para>To work around problems, you may want to use the following <command moreinfo="none">./configure</command> switches:</para>
	    <itemizedlist>
		<listitem>
		  <para>--with-trang-jar=PATH</para>
		</listitem>
		<listitem>
		  <para>--disable-docs</para>
		</listitem>
	    </itemizedlist>
	  </step>
	  <step performance="required">
	    <para>Finally you're ready to build RefDB like you would with a <link linkend="sect-install-from-sources-unix">released version</link>.</para>
	  </step>
	</procedure>
	<para>There is also a neat shell script available on the RefDB <ulink url="http://refdb.sourceforge.net/download.html">download page</ulink> which helps you to keep a SVN version up to date with a minimum number of keystrokes.</para>
      </sect3>
      <sect3>
	<title>Installation of refdbd as a daemon</title>
	<para>This is all it takes to run RefDB from the command line. If you want to start refdbd as a daemon at system startup, a few more steps are necessary. The exact procedure varies greatly between operating systems and distributions. First we'll look at SysV-style systems (most Linux distributions), then at BSD-style systems (BSD-derived Unices and the Slackware Linux distribution).</para>
	<sect4>
	  <title>SysV-style</title>
	  <para>The following procedure describes the setup on a Debian GNU/Linux system. With a little help of your system handbook you should be able to adapt this to your system. On many systems <filename moreinfo="none">/etc/init.d/README</filename> contains just what you need to know or at least it points you to the correct resources.</para>
	  <procedure>
	    <step performance="required">
	      <para>Review the parameters in the script <filename moreinfo="none">refdb</filename> in the <filename class="directory" moreinfo="none">scripts</filename> directory of the source distribution (this file is not automatically installed). If necessary, change the paths and names to your needs and adapt the following steps. Make sure the <varname>BSDSTYLE</varname> variable is set to "NO" (this is the default value).</para>
	    </step>
	    <step performance="required">
	      <para>Copy the script <filename moreinfo="none">refdb</filename> to <filename moreinfo="none">/etc/init.d/</filename> and make sure it is executable: <command moreinfo="none">chmod 755 /etc/init.d/refdb</command>.</para>
	    </step>
	    <step performance="required">
	      <para>Create symbolic links from every runlevel directory that should start refdbd to <filename moreinfo="none">/etc/init.d/refdb</filename>, e.g. <command moreinfo="none">ln -s /etc/init.d/refdb /etc/rc2.d/S93refdb</command>. The numbers in the link names are a convenient and simple way to determine the sequence of daemon starts. As most likely no other daemons rely on RefDB, you can choose as high a number as you want (the daemons are started in lexicographical order).</para>
	    </step>
	    <step performance="required">
	      <para>In analogy to the previous step, generate symbolic links in every runlevel directory that should stop the daemon. Usually these are the runlevels 0 (system halt) and 6 (reboot):</para>
	      <para>
		<command moreinfo="none">ln -s /etc/init.d/refdb /etc/rc0.d/K20refdb</command>
	      </para>
	      <para>
		<command moreinfo="none">ln -s /etc/init.d/refdb /etc/rc6.d/K20refdb</command>
	      </para>
	    </step>
	    <step performance="required">
	      <para>Review the settings in the script <filename moreinfo="none">refdbctl</filename> which by default is installed in <filename moreinfo="none">/usr/local/bin/</filename>. Most likely the script was properly customized for your system in the build step so you don't have to change anything.</para>
	    </step>
	  </procedure>
	  <para>When you boot, halt, or reboot the system you should see messages on the screen telling you that the daemon has been started or stopped successfully. If you don't, please check again all paths in the scripts, the file permissions, and the runlevels you're looking at. Try to run the control script from the command line, e.g. <command moreinfo="none">refdbctl start</command>, to distinguish between general setup problems and init-related setup problems.</para>
	</sect4>
	<sect4>
	  <title>BSD-style</title>
	  <para>The following procedure describes the installation on a FreeBSD system. Other systems might differ somewhat, but you should get the idea.</para>
	  <procedure>
	    <step performance="required">
	      <para>Review the parameters in the script <filename moreinfo="none">refdb</filename> in the <filename class="directory" moreinfo="none">scripts</filename> directory of the source distribution (this file is not automatically installed). Set the value of the script variable <varname>BSDSTYLE</varname> to "YES" (the sole purpose of this variable is to make the boot message blend in seamlessly, if you happen to care for aesthetics). If necessary, change the paths and names to your needs and adapt the following steps.</para>
	    </step>
	    <step performance="required">
	      <para>Copy the script <filename moreinfo="none">refdb</filename> to <filename moreinfo="none">/usr/local/etc/rc.d/refdb.sh</filename> and make sure it is executable: <command moreinfo="none">chmod 755 /usr/local/etc/rc.d/refdb.sh</command>.</para>
	      <note>
		<para>The suffix <filename moreinfo="none">.sh</filename> is mandatory on BSD-style systems.</para>
	      </note>
	    </step>
	    <step performance="required">
	      <para>Review the settings in the script <filename moreinfo="none">refdbctl</filename> which by default is installed in <filename moreinfo="none">/usr/local/bin/</filename>. Most likely the script was properly customized for your system in the build step so you don't have to change anything.</para>
	    </step>
	  </procedure>
	  <para>When you boot, halt, or reboot the system you should see messages on the screen telling you that the daemon has been started or stopped. If you don't, please check again all paths in the scripts and the file permissions. Try to run the control script from the command line, e.g. <command moreinfo="none">refdbctl start</command>, to distinguish between general setup problems and system-related setup problems.</para>
	</sect4>
      </sect3>
    </sect2>
    <sect2>
      <title>OS-specific hints</title>
      <para>This section contains a few hints about the installation on some popular Unix-like operating systems.</para>
      <sect3>
	<title>Linux</title>
	<para>The <link linkend="sect2-generic-instructions">generic instructions</link> should work out of the box for most if not all Linux distributions.</para>
	<sect4>
	  <title>Debian GNU/Linux</title>
	  <para><ulink url="http://www.debian.org">Debian</ulink> keeps all configuration files in <filename class="directory" moreinfo="none">/etc</filename> and subdirectories thereof which makes backing up the configuration of the whole box a breeze. To support this nice feature, you want to add <option>--sysconfdir=/etc</option> to your configure options. The configuration files will then be in <filename class="directory" moreinfo="none">/etc/refdb</filename>. The following is an example of a complete configure call that works on Debian 3.0 (the line was split into several lines for the sake of clarity; type everything on one line and skip the backslashes):</para>
	  <screen format="linespecific">
	    <prompt moreinfo="none">#~ </prompt>
	    <userinput moreinfo="none">./configure --sysconfdir=/etc \
	    --with-docbook-xsl=/usr/share/sgml/docbook/stylesheet/xsl/nwalsh \
	    --with-tei-xsl=/usr/local/lib/sgml/stylesheet/xsl</userinput>
	  </screen>
	</sect4>
      </sect3>
      <sect3>
	<title>FreeBSD</title>
	<para>The BSD version of <command moreinfo="none">make</command> cannot handle the autotools-generated Makefiles correctly. Use gmake instead, and set CFLAGS=-I/usr/local/include during the configuration step. The full configure command, using the default installation paths for the accessory files and programs, looks like this:</para>
	<screen format="linespecific">
	  <prompt moreinfo="none">#~ </prompt>
	  <userinput moreinfo="none">CFLAGS=-I/usr/local/include ./configure --with-expat-lib=/usr/local/lib \
	  --with-classpath-root=/usr/local/share/java/classes </userinput>
	</screen>
	<para>The shared data end up in <filename class="directory" moreinfo="none">/usr/local/share/refdb</filename>, the configuration files will be in <filename class="directory" moreinfo="none">/usr/local/etc/refdb</filename>.</para>
      </sect3>
      <sect3>
	<title>NetBSD</title>
	<para>The BSD version of <command moreinfo="none">make</command> cannot handle the autotools-generated Makefiles correctly. Use gmake instead, and set the following environment variables before running <command moreinfo="none">./configure</command>:</para>
	<screen format="linespecific">
	  <prompt moreinfo="none">#~ </prompt>
	  <userinput moreinfo="none">setenv CFLAGS "-I/usr/pkg/include -I/usr/local/include -L/usr/pkg/lib"</userinput>
	</screen>
	<screen format="linespecific">
	  <prompt moreinfo="none">#~ </prompt>
	  <userinput moreinfo="none">setenv LDFLAGS "-L/usr/pkg/lib  -R/usr/pkg/lib -R/usr/pkg/lib/mysql"</userinput>
	</screen>
	<screen format="linespecific">
	  <prompt moreinfo="none">#~ </prompt>
	  <userinput moreinfo="none">./configure --with-mysqlclient-lib=/usr/pkg/lib/mysql --with-btparse-lib=/usr/local/lib --prefix=/usr/pkg</userinput>
	</screen>
	<para>Use additional options as needed. The shared data will end up in <filename class="directory" moreinfo="none">/usr/pkg/share/refdb</filename>, the configuration files go to <filename class="directory" moreinfo="none">/usr/pkg/etc/refdb</filename>.</para>
      </sect3>
      <sect3>
	<title>Solaris</title>
	<para>Both the standard C compiler and the standard make program will not give the desired results when building RefDB. Use gcc and gmake instead.</para>
      </sect3>
      <sect3>
	<title>OSX</title>
	<para>Use <ulink url="http://fink.sourceforge.net">fink</ulink> to conveniently install all the additional software needed. Then help <command moreinfo="none">configure</command> find the fink-installed packages in <filename class="directory" moreinfo="none">/sw</filename> by setting the following environment variables: <command moreinfo="none">CFLAGS="-I/sw/include" LDFLAGS="-L/sw/lib" ./configure [your_options]</command>.</para>
      </sect3>
    </sect2>
  </sect1>
  <sect1 id="sect1-installation-windows">
    <title>Installation on Windows&#x00A0;NT/2000/XP</title>
    <sect2>
      <title>Prerequisites</title>
      <para>In order to run RefDB you'll need a few external apps. The most important thing are the Cygwin tools which provide a Unix-like environment on the otherwise incompatible Windows platform. Additionally you'll have to build or obtain prebuilt versions of a few libraries which are not part of the standard Cygwin distribution (unless you use <link linkend="sect2-install-cygwin-bin">prebuilt binaries</link> that contain all non-standard libraries).</para>
      <sect3>
	<title>External applications</title>
	<itemizedlist>
	  <listitem>
	    <para><ulink url="http://www.cygwin.com">Cygwin toolkit</ulink>, DLL version 1.5.0 or later (the current version as of this writing, 1.5.12, has serious problems with PostgreSQL, though). The Cygwin distribution uses individual packages for the various parts. In addition to what is installed automatically (the base distribution), please make sure to select the following packages: libxml2, libxslt, expat, Perl, and a full TeX installation if you wish to create Postscript or PDF files.</para>
	  </listitem>
	  <listitem>
	    <para>A SQL database engine. Currently you can choose between <ulink url="http://www.mysql.com">MySQL</ulink> (version 3.23 or later), <ulink url="http://www.postgresql.org">PostgreSQL</ulink> (version 7.1 or later), and <ulink url="http://www.sqlite.org">SQLite/SQLite3</ulink> (versions 2.8.x or later; 3.0.x or later). The database server does not have to physically run on the box(es) where you plan to install RefDB, it is sufficient if it is accessible through the network.</para>
	    <para>Cygwin offers a prepackaged version of PostgreSQL (7.3.3 as of this writing) which used to be the most convenient way to run a database server on your Cygwin box, but as stated above it may be broke when you try. Please follow the instructions in the readme shipped with the package to install and initialize the database server. It is crucial that you install and run the separately available cygipc package, available only <ulink url="http://www.neuro.gatech.edu/users/cwilson/cygutils/cygipc/index.hml">here</ulink>.</para>
	    <para>SQLite does build on Cygwin, but all filename/path handling code uses the Windows conventions. You will have to use the Windows-style path when setting the database directory.</para>
	  </listitem>
	  <listitem>
	    <para>If you want to import Pubmed or MARC datasets, please make sure to install the Perl interpreter available for Cygwin and get the <ulink url="http://sourceforge.net/projects/refdb">refdb-perlmod</ulink> package. This collection of Perl modules is required to run the Pubmed and MARC import filters shipped with RefDB. These Perl modules in turn depend on MARC::Record, MARC::Charset, XML::Parser, available at <ulink url="http://www.cpan.org">CPAN</ulink>.</para>
	  </listitem>
	</itemizedlist>
	<para>The mentioned websites offer plenty of support as web documents or with mailing lists, so it should be possible to figure out how to do a basic install for these suites.</para>
      </sect3>
      <sect3>
	<title>Libraries</title>
	<itemizedlist>
	  <listitem>
	    <para>The <ulink url="http://sourceforge.net/projects/libdbi">libdbi library</ulink> and headers, along with the <ulink url="http://sourceforge.net/projects/libdbi-drivers">libdbi-drivers</ulink> package. Please follow the Cygwin-specific instructions that accompany both packages to build and install the software. Prebuilt binaries for both libdbi and libdbi-drivers are available <ulink url="http://libdbi.sourceforge.net/downloads/">here</ulink>.</para>
	  </listitem>
	  <listitem>
	    <para>If you need the BibTeX import filter, you'll also want to have the <ulink url="http://www.ctan.org/tex-archive/biblio/bibtex/utils/btOOL/">btparse</ulink> library. This builds out of the tarball on Cygwin.</para>
	  </listitem>
	</itemizedlist>
      </sect3>
    </sect2>
    <sect2>
      <title>Installation from the sources</title>
      <note>
	<para>Depending on the permission settings, you may have to run the installation steps proper (as opposed to the build steps) as an administrator.</para>
      </note>
      <procedure>
	<step performance="required">
	  <para>Unpack the sources in a convenient directory: <command moreinfo="none">tar -xzf refdb-x.y.z.tar.gz</command> (the exact filename depends on the version).</para>
	</step>
	<step performance="optional">
	  <para>If you do not want to build in the source directory, create an empty build directory.</para>
	</step>
	<step performance="required">
	  <para>Change into the new <filename class="directory" moreinfo="none">refdb-x.y.z</filename> source directory or into your separate build directory.</para>
	</step>
	<step performance="required">
	  <para>
	    <command moreinfo="none">./configure --help</command>
	  </para>
	  <para>This command will display a list of things you can customize. If you build in a separate directory, use the relative path to <filename moreinfo="none">configure</filename> in the source directory. Some important options are:</para>
	  <note>
	    <para>All paths and URLs in the following options should be entered without a trailing slash.</para>
	  </note>
	  <variablelist>
	    <varlistentry>
	      <term>--prefix=PREFIX</term>
	      <listitem>
		<para>By default, all files will be installed in the <filename class="directory" moreinfo="none">/usr/local</filename> tree. Use this option to use a different install root, e.g. <filename class="directory" moreinfo="none">/usr</filename> or <filename class="directory" moreinfo="none">/opt</filename>.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>--datadir=DIR</term>
	      <listitem>
		<para>The data files will be installed in <filename class="directory" moreinfo="none">/usr/local/share/refdb</filename> unless you use this option. The data will be installed in the directory <filename class="directory" moreinfo="none">DIR/refdb</filename>. That is, specifying "--datadir=/usr/local/share" is equivalent to the default behaviour. The configuration variable <varname>refdblib</varname> (which will be automatically generated in the example configuration files) must point to the RefDB data directory.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>--sysconfdir=DIR</term>
	      <listitem>
		<para>The global configuration files will be installed in <filename class="directory" moreinfo="none">/usr/local/etc/refdb</filename> unless you specify a different directory here.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>--with-libdbi-lib=DIR</term>
	      <listitem>
		<para>Use this option to specify the directory that contains the libdbi library if it is not in the default library path.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>--with-expat-lib=DIR</term>
	      <listitem>
		<para>Use this option to specify the directory that contains the expat library if it is not in the default library path.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>--with-btparse-lib=DIR</term>
	      <listitem>
		<para>Use this option to specify the directory that contains the btparse library if it is not in the default library path.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>--with-sgml-declaration=PATH</term>
	      <listitem>
		<para>Specify the full path to a suitable SGML declaration for your SGML files. If this option is not used, RefDB will use its own copy of <filename moreinfo="none">docbook.dcl</filename> stolen from the DocBook DTD distribution. This SGML declaration also works for a variety of other DTDs.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>--with-xml-declaration=PATH</term>
	      <listitem>
		<para>Specify the full path to <filename moreinfo="none">xml.dcl</filename> which is the SGML declaration for XML files. If this option is not used, RefDB will use its own copy of <filename moreinfo="none">xml.dcl</filename> which should work just fine.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>--with-docbook-xsl=PATH</term>
	      <listitem>
		<para>Specify the full path to the root directory of the DocBook XSL stylesheets.</para>
		<note>
		  <para>This option is required only on systems that do not maintain XML catalogs. If your system is set up properly to resolve public identifiers like those in the XSL stylesheets by XML catalogs, leave out this option. <command moreinfo="none">configure</command> checks whether the required stylesheets are accessible, so watch out for error messages. If the stylesheets can't be found, either install them, fix your catalogs, or use this option to hardcode the path.</para>
		</note>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>--with-docbook-xsl-ns=PATH</term>
	      <listitem>
		<para>Specify the full path to the root directory of the DocBook XSL-NS (for DocBook V5.0 and later) stylesheets.</para>
		<note>
		  <para>This option is required only on systems that do not maintain XML catalogs. If your system is set up properly to resolve public identifiers like those in the XSL stylesheets by XML catalogs, leave out this option. <command moreinfo="none">configure</command> checks whether the required stylesheets are accessible, so watch out for error messages. If the stylesheets can't be found, either install them, fix your catalogs, or use this option to hardcode the path.</para>
		</note>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>--with-tei-xsl=PATH</term>
	      <listitem>
		<para>Specify the full path to the root directory of the TEI XSL stylesheets for P4.</para>
		<note>
		  <para>As mentioned above for the DocBook stylesheets, use this option only if your catalogs cannot resolve the public identifiers properly. The <ulink url="http://www.tei-c.org">TEI Consortium</ulink> ships <ulink url="http://sourceforge.net/project/showfiles.php?group_id=106328&amp;package_id=141124">tei-xsl-5.2.9.zip</ulink> which contains the stylesheets for both p4 and p5. The root directory which you want to specify here is the directory which contains the p4 and p5 subdirectories, e.g. <filename class="directory" moreinfo="none">/usr/local/share/xsl/tei-xsl-5.2.9</filename>.</para>
		</note>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>--with-tei-xsl-ns=PATH</term>
	      <listitem>
		<para>Specify the full path to the root directory of the TEI XSL stylesheets for P5.</para>
		<note>
		  <para>As mentioned above for the DocBook stylesheets, use this option only if your catalogs cannot resolve the public identifiers properly. The <ulink url="http://www.tei-c.org">TEI Consortium</ulink> ships <ulink url="http://sourceforge.net/project/showfiles.php?group_id=106328&amp;package_id=141124">tei-xsl-5.2.9.zip</ulink> which contains the stylesheets for both p4 and p5. The root directory which you want to specify here is the directory which contains the p4 and p5 subdirectories, e.g. <filename class="directory" moreinfo="none">/usr/local/share/xsl/tei-xsl-5.2.9</filename>.</para>
		</note>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>--with-classpath-root=PATH</term>
	      <listitem>
		<para>The refdbxml script assumes that all Java classes for the Java parsers and xslt engines are stored in a class repository, i.e. all in the same directory. Specify this directory with this option. If you keep the relevant Java classes in different directories, either create symlinks or customize refdbxml manually.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>--with-var-dir=PATH</term>
	      <listitem>
		<para>Use this option to specify a directory where refdbd can write its PID file (a file containing the process ID). By default, <filename class="directory" moreinfo="none">/var/run</filename> will be used.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>--with-log-dir=PATH</term>
	      <listitem>
		<para>Use this option to specify a directory where RefDB programs can write log files to, if logging is directed to a custom file. By default, <filename class="directory" moreinfo="none">/var/log</filename> will be used.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>--with-main-db=dbname</term>
	      <listitem>
		<para>RefDB uses one main database to store citation styles and other stuff. There is exactly one such database per installation with the default name <filename moreinfo="none">refdb</filename>. You may have to change this name if you want to run two different versions of RefDB in parallel, or if you're not free to choose your database name. Although the main database name is configurable at runtime, you should use this option to initialize your <filename>refdbdrc</filename> configuration file, as it allows the <link linkend="refentry-refdb-init">refdb-init</link> script to use the proper database name.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>--with-db-dir</term>
	      <listitem>
		<para>Selects the directory which holds SQLite/SQLite3 databases</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>--with-trang-jar</term>
	      <listitem>
		<para>Specifies the full path to the jar file of the <ulink url="http://www.thaiopensource.com/relaxng/trang.html">trang</ulink> tool. You need this tool if you build RefDB from SVN sources, but not if you build from a tarball.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>--disable-docs</term>
	      <listitem>
		<para>RefDB ships with prebuilt docs. However, if you build a SVN version, or if the documentation is otherwise screwed up, you may have to build them. Building the docs from the sources requires a couple of extra tools. You can use this configure switch to build the rest of RefDB without having to install these tools.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>--disable-clients</term>
	      <listitem>
		<para>Use this switch if you want to build and install only the application server <filename>refdbd</filename>. This is mainly targeted at package builders.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>--disable-server</term>
	      <listitem>
		<para>Use this switch if you want to build and install only the clients but not the application server. This is mainly targeted at package builders.</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	  <para>Finally, run <command moreinfo="none">./configure</command> with any options that you need. If you build in a separate directory, use the relative path to <filename moreinfo="none">configure</filename> in the source directory. A complete set of options might look like this if you use PostgreSQL:</para>
	  <screen format="linespecific">
	    <prompt moreinfo="none">$~ </prompt>
	    <userinput moreinfo="none">./configure --with-refdb-url=http://yourbox.com/refdb --with-db-server=pgsql --with-var-dir=/var/run \
	    --with-log-dir=/var/log --with-libdbi-dir=/uar/local/lib --with-docbook-xsl=/usr/local/share/sgml/stylesheets/docbook \
	    --with-tei-xsl=/usr/local/share/xsl/tei</userinput>
	  </screen>
	</step>
	<step performance="required">
	  <para>Run <command moreinfo="none">make</command>. This will create the executables and adapt scripts and other files to your local installation.</para>
	</step>
	<step performance="required">
	  <para><command moreinfo="none">make install</command> will copy the application server and the clients to <filename class="directory" moreinfo="none">/usr/local/bin</filename> and the data files to <filename class="directory" moreinfo="none">/usr/local/share/refdb</filename> unless you chose different directories in the configure step.</para>
	</step>
	<step performance="required">
	  <para>To finish the installation, please follow the instructions in the section <link linkend="sect1-set-up-database">Finishing the RefDB installation</link> below.</para>
	</step>
      </procedure>
      <para>Now you have everything in place to use the RefDB clients and the application server from the command line. To install the application server as a service, the following additional steps are necessary:</para>
      <procedure id="procedure-installservice">
	<step performance="required">
	  <para>Install the service with the command <command moreinfo="none">cygrunsrv -I refdbd -p /usr/local/bin/refdbd -a '-s'</command> (adapt the paths to your local installation if necessary).</para>
	</step>
	<step performance="required">
	  <para>Start the service with the command <command moreinfo="none">cygrunsrv -S refdbd</command>. To stop the service, use the command <command moreinfo="none">cygrunsrv -E refdbd</command>. If you prefer, you can also start and stop the service with Windows' own tools: Either use the system control panel or use the commands <command moreinfo="none">net start refdbd</command> and <command moreinfo="none">net stop refdbd</command>.</para>
	</step>
      </procedure>
      <para>With this setup, the service will be automatically started at system startup. See <command moreinfo="none">cygrunsrv --help</command> for additional options.</para>
    </sect2>
    <sect2 id="sect2-install-cygwin-bin">
      <title>Installation of prebuilt binaries</title>
      <para>If you decide to grab the prebuilt binaries, the installation will be a little bit faster. The binaries are accompanied by a copy of libexpat. Please make sure to read the aptly named <filename moreinfo="none">Readme</filename> files as they may have newer or additional information.</para>
      <procedure>
	<step performance="required">
	  <para>Unpack the archive in the root directory (<filename class="directory" moreinfo="none">/</filename>) with the command <command moreinfo="none">tar -xzf refdb-cygwin-bin-x.y.z.tar.gz</command> (the exact archive name depends on the version you use). This will extract the files into the <filename class="directory" moreinfo="none">/usr/local</filename> hierarchy. The binaries and scripts go to <filename class="directory" moreinfo="none">/usr/local/bin</filename>, the Document Type Definitions, stylesheets, styles and example configuration files go to <filename class="directory" moreinfo="none">/usr/local/share/refdb</filename> and its subdirectories.</para>
	</step>
	<step performance="required">
	  <para>Unpack the prebuilt binaries for both libdbi and libdbi-drivers, available <ulink url="http://libdbi.sourceforge.net/downloads/">here</ulink>, in the very same way.</para>
	</step>
	<step performance="required">
	  <para>Add <filename moreinfo="none">/usr/local/share/refdb/refdb.cat</filename> to your <envar>SGML_CATALOG_FILES</envar> environment variable.</para>
	</step>
	<step performance="required">
	  <para>Create the configuration files in <filename class="directory" moreinfo="none">/usr/local/etc</filename>. Sample configuration files with a <filename moreinfo="none">.example</filename> extension are created in the same directory during the installation. Provide personalized copies for the user's home directories as needed.</para>
	</step>
	<step performance="required">
	  <para>To install refdbd as a service, follow the instructions <link linkend="procedure-installservice">above</link>.</para>
	</step>
      </procedure>
    </sect2>
  </sect1>
  <sect1>
    <title>Installation on Windows&#x00A0;95/98/ME</title>
    <para>Most of the things said for Windows&#x00A0;NT/2000/XP are applicable as well for Windows&#x00A0;95/98/ME. The main difference is that the latter operating systems do not support the idea of a daemon or service. The closest thing you can do to running a service is to put a shortcut to refdbd into the startup folder. This is not much of a problem if you run the RefDB clients on the same computer as refdbd. However, Windows&#x00A0;95/98/ME are not suitable to handle RefDB requests from other computers because refdbd will not run if nobody is logged in.</para>
  </sect1>
  <sect1>
    <title>Other operating systems</title>
    <para>RefDB has not been ported to other operating systems yet. As no esoteric features of the C language are used, you may just try to run <command moreinfo="none">./configure [options] &amp;&amp; make</command> and see what happens. Chances are that it either works or can be convinced to work with just a few modifications. If you manage to run RefDB on a platform not described here, a short notice with the porting instructions would be greatly appreciated.</para>
  </sect1>
  <sect1 id="sect1-set-up-database">
    <title id="sect1-title-set-up-database">Finishing the RefDB installation</title>
    <para>This step is necessary for all platforms. You have to create some databases for RefDB to start with and you should make the RefDB SGML/XML support files known to your system. In most cases you will prefer to use a script provided with RefDB which performs all things required for a first-time installation. If you need more precise control, you'll also find instructions below how to set up RefDB manually.</para>
    <sect2>
      <title>Using the interactive setup script</title>
      <para>The interactive script <link linkend="refentry-refdb-init"><command>refdb-init</command></link> must be run with root permission as it tries to fiddle with a couple of files that a regular user should not have write permission for. After starting the script, it will collect a few answers from you about your intended setup. It will also perform a couple of sanity checks. After this stage is completed, you will be asked to positively confirm whether or not your system should be modified. Therefore it is safe to dry-run this script in order to decide whether you prefer the script over the <link linkend="sect2-manual-setup">manual installation</link>.</para>
    <para>The script creates the main database, the refdbd and refdba configuration files, loads the available styles, creates a reference database and a database user account. All that is left to do manually is to take care of the <link linkend="sect3-catalog-files">SGML catalog file</link>.</para>
    </sect2>
    <sect2 id="sect2-manual-setup">
      <title>Manual setup</title>
      <sect3>
	<title>Configuration files</title>
	<para>Now is the time to create the global configuration files described in the <link linkend="sect1-mystery-init-files">configuration file</link> section. Create these files in <filename class="directory" moreinfo="none">/usr/local/etc/refdb</filename> (or whatever you chose during configuration). It is recommended to copy and modify the commented example configuration files in the same directory. These files are installed with the suffix ".example" to avoid overwriting existing configuration files. All required paths are automatically configured during the installation, so these files are a good starting point for your local modifications.</para>
	<para>The <filename>refdbdrc</filename> configuration file can be copied from one of the templates <filename>refdbdrc.mysql.example</filename>, <filename>refdbdrc.pgsql.example</filename>, <filename>refdbdrc.sqlite.example</filename>, or <filename>refdbdrc.sqlite3.example</filename> according to your choice of the database engine.</para>
      </sect3>
      <sect3>
	<title>Configuring your database server</title>
	<para>The default installation of all supported database engines should be just fine for running RefDB. However, in some cases a little extra work is needed.</para>
	<sect4>
	  <title>MySQL</title>
	  <para>The MySQL engine earlier than version 4.1 supports only one character encoding per server instance. The default encoding is ISO-8859-1, aka Latin-1. If you prefer a different encoding, you have to configure the server at startup. Either use the <command moreinfo="none">mysqld</command> command-line option <option>--default-character-set=charset</option>, or add a "default-character-set=charset" entry to a suitable MySQL configuration file. A list of available encodings is usually installed as <filename moreinfo="none">/usr/local/share/mysql/charsets/Index</filename>. In MySQL versions 4.1 and later each database (in fact, each table) may have one of various character encodings.</para>
	  <para>For security reasons many default installation allow only local connections. If refdbd has to connect to the database server from a different box, make sure to remove the <option>--skip_networking</option> option from the MySQL start script or from the appropriate MySQL configuration file.</para>
	</sect4>
	<sect4>
	  <title>PostgreSQL</title>
	  <para>Most default installations of this database server allow only local Unix sockets connections due to security concerns. However, the refdbd application server will always talk to the database server via a TCP/IP connection. Please make sure to start <command moreinfo="none">postmaster</command> with the <option>-i</option> command line option to switch on TCP/IP support.</para>
	</sect4>
	<sect4>
	<title>SQLite</title>
	<para>The embedded database engine SQLite (versions 2.x) supports two character encodings as a compile-time option: ISO-8859-1 (Latin-1) and UTF-8. The former is the default if you don't use any configure options and if you use prebuilt binaries. If you need Unicode support, you'll have to recompile SQLite using the proper configure switch.</para>
	<para>SQLite version 3.0 and higher uses UTF-8 as the default encoding which is just fine for the purposes of RefDB.</para>
	</sect4>
      </sect3>
      <sect3>
	<title>Creating the databases</title>
	<para>The RefDB database contains common information that is shared by all reference databases. The following sections explain the database engine-specific steps. In all cases you have two options: The recommended way is to let <command>refdbd</command> handle the installation, but for special needs there is also a description how to set up the databases using the database engine clients.</para>
	<sect4>
	  <title>MySQL</title>
	  <para>As mentioned above, the recommended way to create or update the main database is to run the following command from your root account:</para>
	  <screen format="linespecific">
	    <prompt moreinfo="none">~$ </prompt>
	    <userinput moreinfo="none">refdbd -a -u username -w password</userinput>
	  </screen>
	  <para>Specify the username and password of your database administrator account.</para>
	  <para>If the default setup described above does not suit your needs, please use the following procedure instead to set up the main database.</para>
	  <note>
	    <para>If <filename moreinfo="none">mysqld</filename> (the MySQL database server) is installed on a remote box or if the security settings require it, you may have to use the <option>-h <replaceable>hostname</replaceable></option> and/or the <option>-u <replaceable>username</replaceable></option>/<option>-p <replaceable>password</replaceable></option> options to run the <filename moreinfo="none">mysql</filename> client as shown below (most fresh MySQL installations use "root" with no password as the default database administrator). <filename moreinfo="none">mysqld</filename> needs to be up and running and you need the appropriate permissions, of course. See the <application moreinfo="none">MySQL</application> documentation for further details.</para>
	  </note>
	  <para>Instead of using <command>refdbd</command>, you can also use the hard way and create the main database using your database engine client:</para>
	  <itemizedlist>
	    <listitem>
	      <para>In a command line window, run the following command to create the database "refdb":</para>
	      <screen format="linespecific">
		<prompt moreinfo="none">~$ </prompt>
		<userinput moreinfo="none">mysql -u root -e "CREATE DATABASE refdb"</userinput>
	      </screen>
	    </listitem>
	    <listitem>
	      <para>Then create the tables and fill in the data. For MySQL older than 4.1, run:</para>
	      <screen format="linespecific">
		<prompt moreinfo="none">~$ </prompt>
		<userinput moreinfo="none">mysql -u root refdb &lt; /usr/local/share/refdb/sql/refdb.dump.mysql</userinput>
	      </screen>
	      <para>For MySQL 4.1 and later, run this instead:</para>
	      <screen format="linespecific">
		<prompt moreinfo="none">~$ </prompt>
		<userinput moreinfo="none">mysql -u root refdb &lt; /usr/local/share/refdb/sql/refdb.dump.mysql41</userinput>
	      </screen>
	      <para>Adapt the path to the script accordingly if you configured RefDB to put the data directory somewhere else.</para>
	      <para>The above command will create the tables using the MyISAM engine. This is the fastest of the supported engines, but it does not support transactions. If you prefer to use the InnoDB engine instead, use this command:</para>
	      <screen format="linespecific">
		<prompt moreinfo="none">~$ </prompt>
		<userinput moreinfo="none">sed 's/MyISAM/InnoDB/' &lt; /usr/local/share/refdb/sql/refdb.X.dump.mysql41|mysql -u root refdb</userinput>
	      </screen>
	      <para>Use the highest dump file number 'X' shipped with your current RefDB version. See the <ulink url="http://www.mysql.com">MySQL documentation</ulink> for further information about the table engines available with MySQL.</para>
	    </listitem>
	  </itemizedlist>
	</sect4>
	<sect4>
	  <title>PostgreSQL</title>
	  <para>You must run the following command either from your root account, or from a special database administrator account (depending on your local PostgreSQL installation). Run this command to let <command>refdbd</command> create the main database:</para>
	  <screen format="linespecific">
	    <prompt moreinfo="none">~$ </prompt>
	    <userinput moreinfo="none">refdbd -a -u username -w password</userinput>
	  </screen>
	  <para>Specify the username and password of your database administrator account.</para>
	  <para>If the default setup described above does not suit your needs, please use the following procedure instead to set up the main database.</para>
	  <note>
	    <para>Your PostgreSQL administrator accound may not have the privileges to write to the PID file. In that case, add something like <option>-P /var/tmp/refdbd.pid</option> to the command line mentioned above. If <filename moreinfo="none">postmaster</filename> (the PostgreSQL database server) is installed on a remote box or if the security settings require it, you may have to use the <option>-h <replaceable>hostname</replaceable></option> and/or the <option>-U <replaceable>username</replaceable></option> options to run the <filename moreinfo="none">psql</filename> client as shown below (most fresh PostgreSQL installations on Unix-style systems use "pgsql" with no password as the default database administrator. The Cygwin port of PostgreSQL uses the name of whoever installed the package, usually "Administrator". On Debian you need to be logged in as user "postgres": first <command moreinfo="none">su root</command>, then <command moreinfo="none">su postgres</command>). <filename moreinfo="none">postmaster</filename> needs to be up and running and you need the appropriate permissions, of course. See the <application moreinfo="none">PostgreSQL</application> documentation for further details.</para>
	  </note>
	  <para>Instead of using <command>refdbd</command>, you can also create the main database using your database engine client:</para>
	  <itemizedlist>
	    <listitem>
	      <para>In a command line window, run the command:</para>
	      <screen format="linespecific">
		<prompt moreinfo="none">~$ </prompt>
		<userinput moreinfo="none">createdb -U pgsql -E UNICODE refdb</userinput>
	      </screen>
	      <para>The data that you will import in the following steps are UTF-8 data. If you wish to use a different encoding, convert the dump file and adapt the above command accordingly.</para>
	    </listitem>
	    <listitem>
	      <para>Then run this command:</para>
	      <screen format="linespecific">
		<prompt moreinfo="none">~$ </prompt>
		<userinput moreinfo="none">psql -U pgsql refdb &lt; /usr/local/share/refdb/sql/refdb.X.dump.pgsql</userinput>
	      </screen>
	      <para>Use the highest dump file number 'X' shipped with your current RefDB version. Adapt the path to the script accordingly if you configured RefDB to put the data directory somewhere else. This SQL script will generate the necessary table definitions and fill in a few values. PostgreSQL will notice you that it is going to truncate a few identifier names. It is safe to ignore these messages.</para>
	    </listitem>
	    <listitem>
	      <para>Access control works through user groups. To be able to access the main database, create a RefDB user group like this:</para>
	      <screen format="linespecific">
		<prompt moreinfo="none">~$ </prompt><userinput moreinfo="none">psql -U pgsql refdb -c "CREATE GROUP refdbuser"</userinput>
		<prompt moreinfo="none">~$ </prompt><userinput moreinfo="none">psql -U pgsql refdb -c "GRANT SELECT ON CITSTYLE, POSITIONS, REFSTYLE, SEPARATORS, t_journal_words, t_meta TO GROUP refdbuser"</userinput>
	      </screen>
	    </listitem>
	  </itemizedlist>
	</sect4>
	<sect4>
	  <title>SQLite</title>
	  <para>Run the following command from your root account to let <command>refdbd</command> create the main database:</para>
	  <screen format="linespecific">
	    <prompt moreinfo="none">~$ </prompt>
	    <userinput moreinfo="none">refdbd -a</userinput>
	  </screen>
	  <para>If the default setup described above does not suit your needs, please use the following procedure instead to set up the main database.</para>
	  <itemizedlist>
	    <listitem>
	      <para>The default database directory is <filename moreinfo="none">/usr/local/var/lib/refdb/db</filename>. RefDB will look here unless you selected a different data directory when configuring the application. If you want to keep your databases somewhere else, use the <varname>dbpath</varname> variable in <filename moreinfo="none">refdbdrc</filename> and modify the following instructions accordingly.</para>
	      <screen format="linespecific">
		<prompt moreinfo="none">~$ </prompt>
		<userinput moreinfo="none">cd /usr/local/var/lib/refdb/db</userinput>
	      </screen>
	    </listitem>
	    <listitem>
	      <para>Run the following command to create the database and load the data:</para>
	      <screen format="linespecific">
		<prompt moreinfo="none">~$ </prompt>
		<userinput moreinfo="none">sqlite refdb &lt; /usr/local/share/refdb/sql/refdb.X.dump.sqlite</userinput>
	      </screen>
	      <para>Use the highest dump file number 'X' shipped with your current RefDB version.</para>
	    </listitem>
	  </itemizedlist>
	</sect4>
      </sect3>
      <sect3 id="sect3-catalog-files">
	<title>The SGML/XML support files</title>
	<para>The RefDB package comes with a few additional scripts and stylesheets for the creation of bibliographies. These files are installed in the package data directory (usually <filename class="directory" moreinfo="none">/usr/local/share/refdb</filename>) and its subdirectories, but you should spend a little time to integrate them into your SGML system.</para>
	<para>To this end, add the catalog file <filename moreinfo="none">/usr/local/share/refdb/refdb.cat</filename> to your <envar>SGML_CATALOG_FILES</envar> environment variable. This is a master catalog with CATALOG directives for all catalog files supplied by RefDB.</para>
      </sect3>
      <sect3>
	<title>The shell scripts</title>
	<para>The RefDB shell scripts and Perl scripts were installed in <filename class="directory" moreinfo="none">/usr/local/bin</filename> unless you chose a different install root during configure. As RefDB attempts to insert the correct settings during the build process, it should not be necessary to manually customize these scripts. If you still want to fiddle with the settings, the variables are clearly marked within a <quote>user-customizable section</quote> at the top of each script.</para>
	<note>
	  <para>If you want to use a Java XSL processor with the <filename moreinfo="none">refdbxml</filename> script, you'll have to check the value of <varname>CLASSPATH</varname> in the script. The value must match the actual location of your <filename moreinfo="none">.jar</filename> files and the current versions you've installed.</para>
	</note>
      </sect3>
    </sect2>
  </sect1>
  <sect1>
    <title>Testing your installation</title>
    <para>Now that you got this far, you surely want to see whether your setup actually works. To this end, you may want to run the following tests and see what happens. For your convenience you should perform this test in a graphical environment running at least two console windows.</para>
    <procedure>
      <step performance="required">
	<para>For our first tests it is desirable to have debug information directly available. Therefore you should start refdbd from the root account with some special parameters. Before going ahead you should make sure that you do not have a refdbd process already running, e.g. because you've setup your system to start that daemon at system startup. The following command will kill any refdbd processes. It will do no harm if no such process is running.</para>
	<screen format="linespecific">
	  <prompt moreinfo="none">#~ </prompt>
	  <userinput moreinfo="none">refdbctl stop</userinput>
	</screen>
	<para>If you see an error message saying <quote>refdbctl: command not found</quote> then your installation failed or your <envar>PATH</envar> environment variable is not set properly.</para>
      </step>
      <step performance="required">
	<para>Now that we know that there is no other refdbd process around, we'll start a fresh one with special properties: We'll run it in a separate xterm as a standalone application and have it write debug information to stderr. This way, RefDB will be slow, but we directly see what's going on.</para>
	<screen format="linespecific">
	  <prompt moreinfo="none">#~ </prompt>
	  <userinput moreinfo="none">refdbd -s -e 0 -l 7</userinput>
	</screen>
	<note>
	  <para>If you try to access refdbd from a different box, you should also use the <option>-I</option> switch to allow remote connections.</para>
	</note>
	<para>refdbd should print some diagnostic information about its startup process and then wait for clients to connect. You may experience problems at this point if the access rights do not allow refdbd to create its PID file. This is why we run the test process as root, but if you plan to set up RefDB for use with a different account, this is a good time to check and try out these access rights. You may use the <option>-P</option> option to provide the path to a PID file that you have write access to in order to run refdbd from an unprivileged account.</para>
	<para>refdbd checks the availability of libdbi database drivers during the startup procedure. The following messages indicate a problem with libdbi:</para>
	<variablelist>
	  <varlistentry>
	    <term>error while loading shared libraries: libdbi.so.0: cannot open shared object file: no such file or directory</term>
	    <listitem>
	      <para>This is a common problem if you build your system from packages, but have to build some libraries (like libdbi, as shown here) from the sources. libdbi and most other autotools-based programs are installed into <filename class="directory">/usr/local</filename> by default. On some systems (like Debian, Ubuntu) the linker does not peek into <filename class="directory">/usr/local/lib</filename> for shared objects. To fix this, please add <filename class="directory">/usr/local/lib</filename> to <filename>/etc/ld.so.conf</filename> and run <command>ldconfig</command>(8), or configure the libraries to install into <filename class="directory">/usr/lib</filename> instead. See <command>./configure --help</command> for further instructions.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>Unable to initialize libdbi! Make sure you specified a valid driver directory</term>
	    <listitem>
	      <para>You should see a few lines before this message which libdbi driver directory refdbd attempted to use. Either the default directory is not where the drivers are, or you specified an incorrect driver directory.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>Initialized libdbi, but no drivers were found!</term>
	    <listitem>
	      <para>The libdbi library was not able to locate or properly load at least one database driver. Please check the libdbi installation and make sure you've installed at least one database driver. Remember that on most systems the libdbi-drivers package is distributed separately from the libdbi package which contains only the framework, but no drivers. This error also occurs if you install driver versions which are too old for the libdbi framework.</para>
	    </listitem>
	  </varlistentry>
	</variablelist>
	<para>If refdbd successfully loads libdbi, it will list the available database drivers. Make sure the driver for the database engine you use is listed.</para>
      </step>
      <step performance="required">
	<para>Now switch to a different xterm and start the refdba client. The client can basically run from any user account, but the username and password settings have to be those of a database administrator. We're talking about that username and password that you would provide to the command line client of your database server (<command moreinfo="none">mysql</command> or <command moreinfo="none">psql</command> for MySQL and PostgeSQL, respectively) for administrative tasks. The username and password settings are either provided by the corresponding configuration file <filename moreinfo="none">~/.refdbarc</filename>, or by using the command line options <option>-u &lt;dbadmin&gt;</option> <option>-p &lt;dbadmin-password&gt;</option>. In the first case, that is if you set up your configuration file properly, you can just say:</para>
	<screen format="linespecific">
	  <prompt moreinfo="none">#~ </prompt>
	  <userinput moreinfo="none">refdba</userinput>
	</screen>
	<para>In the second case you have to use this instead:</para>
	<screen format="linespecific">
	  <prompt moreinfo="none">#~ </prompt>
	  <userinput moreinfo="none">refdba -u &lt;dbadmin&gt; -w &lt;dbadmin-passwd&gt;</userinput>
	</screen>
	<para>In both cases the client should start up and wait for your commands with a friendly prompt.</para>
      </step>
      <step performance="required">
	<para>At first you might try and see whether the RefDB programs read their configuration files properly. To this end, first run the following refdba command:</para>
	<screen format="linespecific">
	  <prompt moreinfo="none">refdba: </prompt>
	  <userinput moreinfo="none">set</userinput>
	</screen>
	<para>This will list the current settings of all configuration variables. Make sure these values are what you want. The most important variables are: username and passwd (you won't see the value of the latter for security reasons, though), as well as the host name or IP address of the box that runs refdbd. As we currently run both the server and the client on the same box, please make sure that the value of serverip is "127.0.0.1".</para>
      </step>
      <step performance="required">
	<para>Now try to send a command to the server. We use a command that does not require database access, but it will tell us whether we can connect to the server properly:</para>
	<screen format="linespecific">
	  <prompt moreinfo="none">refdba: </prompt>
	  <userinput moreinfo="none">viewstat</userinput>
	</screen>
	<para>Several things can happen. If you get several lines of output, telling you about the database server used and about a few refdbd variables, you're fine. This output may look like the following:</para>
	<programlisting format="linespecific">You are served by: RefDB 0.9.4
Client IP: 127.0.0.1
Connected via pgsql driver (dbd_pgsql v0.7.1)
to: PostgreSQL 7.2.1 on i386-portbld-freebsd4.3, compiled by GCC 2.95.3
serverip: localhost
timeout: 180
dbs_port: 5432
logfile: /home/markus/prog/refdb/pseudotest/log/refdbd.log
logdest: 0
loglevel: 7
remoteadmin: off
pidfile: /home/markus/refdbd.pid</programlisting>
	<para>If you get the following message instead: <quote>could not establish server connection</quote>, check that refdbd is still running and that the serverip setting in refdba is correct. If you try to access refdbd from a remote box, make sure the server was started with the <option>-I</option> option. The error may also result from the fact that you failed to create the common database <filename moreinfo="none">refdb</filename> or that you did not use the appropriate database server administrator username and password when starting refdba. Finally, your system may lack the runtime client library of the database server.</para>
	<para>The error message <quote>failed to connect to database server</quote> shows that your client can talk to refdbd, but that in turn can't talk to the database server. This may be due to incorrect username/password settings or incorrect permissions with the database servers that support user authentication. If you use SQLite as the database engine, you may have specified an incorrect database directory.</para>
	<para>A third possible outcome of this test is the message "main database too old or corrupt". Sometimes this is just what it says, e.g. if you upgraded to a newer version without re-creating the main database although the <filename>UPGRADING</filename> file told you to do so. However, the most likely reason is an incorrect setting in the <filename>refdbdrc</filename> config file. Please check that the <varname>dbserver</varname> variable matches the database engine that you created the main database for. The default is sqlite.</para>
      </step>
    </procedure>
    <para>This is all it takes to test the basic functionality of your setup. Everything beyond this is either site-specific setup or mere usage of the tools. Please peruse the manual, especially the hints about getting your <link linkend="sect-database-server-access-control">database access rights</link> correct.</para>
  </sect1>
  <sect1 id="sect-install-sru">
    <title>SRU support</title>
    <para>In addition to its native clients, RefDB also supports optional read access through a web-based search protocol called <ulink url="http://www.loc.gov/standards/sru/">SRU</ulink> (Search and Retrieve via URL). There are two options to enable SRU access. We'll first describe a CGI script which is the preferred way but requires a running web server on your system. The subsequent section describes a simpler standalone server for testing purposes and for single-user access.</para>
    <sect2 id="sect-srucgi">
      <title>Setting up SRU support as a CGI program</title>
      <para>In order to provide SRU services at your site, you need to add a <ulink url="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI</ulink> script to your web server. The following instructions assume that you use <ulink url="http://httpd.apache.org/">Apache</ulink> as your web server. However, the CGI script will work just fine with any other web server that provides CGI support.</para>
      <sect3 id="sect-configure-apache">
	<title>Configure your web server</title>
	<para>If your web server is already set up to run CGI scripts, you might be all set to run the SRU CGI script as well. If you're not sure, follow the instructions below and check whether the your configuration file already has the relevant entries.</para>
	<para>The Apache web server uses a configuration file called <filename>httpd.conf</filename>. On many systems this file is located in <filename class="directory">/usr/local/etc/apache</filename>. Locate the section starting with "&lt;IfModule mod_alias.c&gt;" and make sure it declares a CGI directory:</para>
	<programlisting>
    ScriptAlias /cgi-bin/ "/usr/local/www/cgi-bin/"
	</programlisting>
	<para>You can choose a different directory, but the directory listed here must exist and be accessible from the account the web server runs in (often "www" or "nobody").</para>
	<para>Now you have to allow the execution of CGI scripts in that directory:</para>
	<programlisting>
    &lt;Directory "/usr/local/www/cgi-bin"&gt;
        AllowOverride None
        Options ExecCGI
        Order allow,deny
        Allow from all
    &lt;/Directory&gt;
	</programlisting>
	<para>Finally, you have to restart your web browser to let these changes take effect:</para>
	<screen><prompt>~# </prompt><userinput>apachectl restart</userinput></screen>
      </sect3>
      <sect3 id="sect-install-cgi-script">
	<title>Install the SRU CGI script</title>
	<para>First you need to make sure the <filename class="directory">/cgi-bin/</filename> directory configured above exists and has the proper permissions. Local habits may vary, but you should see something like this:</para>
	<screen><prompt>~# </prompt><userinput>ls -ld /usr/local/www/cgi-bin</userinput>
drwxr-xr-x  2 root  wheel  512 Mar 13 14:56 cgi-bin
	</screen>
	<note>
	  <para>In the Apache default installation <filename class="directory">/usr/local/www/cgi-bin</filename> is a symbolic link to an example CGI directory. Remove the symlink and create a real directory with the appropriate ownership and permissions instead.</para>
	</note>
	<para>Now copy the <filename>scripts/refdbsru</filename> CGI script into that directory and make it executable for all:</para>
	<screen><prompt>~# </prompt><userinput>cp refdbsru /usr/local/www/cgi-bin</userinput>
<prompt>~# </prompt><userinput>chmod a+x /usr/local/www/cgi-bin/refdbsru</userinput>
	</screen>
	<para>All SRU replies are XML files. This is just fine if the requesting agent is a program that intends to further process the data, or to store them somewhere. If the requesting agent is a web browser with a human being in front of it, the plain XML output is a bit hard on the eyes though. It is recommended to provide XSLT stylesheets which can render the XML output in a human-readable HTML format (most current web browsers support XSLT these days). These stylesheets are used by default, unless a user provides the URL of a stylesheet of his own.</para>
	<para>Unless you already have a designated folder for system-wide stylesheets, just create one, and make sure it is readable:</para>
	<screen><prompt>~# </prompt><userinput>mkdir -p /usr/local/www/data/styles</userinput>
<prompt>~# </prompt><userinput>chmod a+r /usr/local/www/data/styles</userinput>
	</screen>
	<para>Now copy the example stylesheets shipped with RefDB (installed in <filename class="directory">/usr/local/share/refdb/sru</filename>) into that directory:</para>
	<screen><prompt>~# </prompt><userinput>cp refdbsru.xsl mods.xsl risx.xsl refdbsru.css /usr/local/www/data/styles</userinput>
	</screen>
	<para>Needless to say, you can tweak all these stylesheets to your heart's content.</para>
	<para>Finally you should provide a configuration file called <filename>refdbsrurc</filename> which usually goes into <filename class="directory">/usr/local/etc/refdb/</filename>. You'll find a preconfigured example file in the same directory which you can copy and edit. Make sure the <varname>xslurl</varname> variable points to the <filename>refdbsru.xsl</filename> file that you've just installed. The value of this variable is an absolute or relative URL in the filesystem of the web server. If your setup is as described above, <replaceable>/styles/refdbsru.xsl</replaceable> will work just fine. It is recommended to set the variables starting with <varname>zeerex_</varname> to meaningful values. These values determine part of the output of the <command>explain</command> SRU command and are supposed to provide the users of your site with useful information about your SRU service.</para>
      </sect3>   
      <sect3 id="sect-tune-cgi-script">
	<title>Tune the SRU CGI script</title>
	<para>From refdbd's point of view, the refdbsru CGI script is just another client. The script therefore requires a similar configuration file like the other clients, and it needs a database account to work with. For the configuration of the script, see the <link linkend="refentry-refdbsru">refdbsru reference</link>.</para>
	<para>As SRU provides only read access to your databases, it is recommended to create a separate database account for SRU accesses which all SRU users share. If you specify these values in the configuration files, the SRU users will not have to provide any login information. You may want to restrict that account to read access only using the appropriate switch of the <link linkend="app-a-command-adduser">adduser</link> command.</para>
      </sect3>
      <sect3 id="sect-test-cgi-script">
	<title>Test the SRU CGI script</title>
	<para>Open your favourite web browser and enter the following URL:</para>
	<screen>localhost/cgi-bin/refdbsru</screen>
	<para>You should now receive an XML document that describes the RefDB SRU service. If you receive a web server error instead, retrace your steps above and make sure you have restarted the web server before testing. If nothing else helps, please peruse the documentation of your web server. The appropriate document for Apache is the <ulink url="http://httpd.apache.org/docs/2.0/howto/cgi.html">CGI HowTo</ulink>.</para>
	<para>Finally, you should advertize the new service on your web site. Provide a link to "&lt;hostname&gt;/cgi-bin/refdbsru" along with some instructions how to use SRU, as explained in the <link linkend="chapter-sru">user manual</link>.</para>
      </sect3>
    </sect2>
    <sect2 id="sect-srustandalone">
      <title>Setting up SRU support using a standalone web server</title>
      <para>RefDB also provides a standalone web server to run the SRU service. All you need to do in terms of "installation" is to create or edit the SRU configuration file that the standalone server shares with the <link linkend="sect-srucgi">CGI application</link>. See also the <link linkend="refentry-refdb-sruserver">refdb-sruserver reference</link>. Then start the SRU server like this:</para>
      <screen><prompt>~# </prompt>[perl] refdb-sruserver</screen>
      <para>The server will run in the foreground until you kill it with <keycombo><keycap>Ctrl</keycap><keycap>c</keycap></keycombo>. Now point your web browser to:</para>
      <screen>localhost:8080</screen>
      <para>As you can see, the SRU server uses the non-standard port 8080 so it does not interfere with any regular web server. This also means that the standalone SRU server is usually not accessible from a remote computer unless you configure your firewall appropriately. However, as long as you connect locally you should receive the output of the SRU explain command.</para>
    </sect2>
  </sect1>
  <sect1 id="sect-install-php">
    <title>Install the PHP interface</title>
    <para>If you want to provide interactive access to your RefDB databases through the web, consider installing the PHP web interface. This web frontend provides a convenient way to perform the most common user tasks, like running queries or adding datasets.</para>
    <sect2 id="sect-php-prerequisites">
      <title>Prerequisites</title>
      <para>Please check the following prerequisites on your computer before attempting to install the PHP interface</para>
      <variablelist>
	<varlistentry>
	  <term>Web server</term>
	  <listitem>
	    <para>Any web server that is capable of running PHP scripts. If you don't run a web server anyway, <ulink url="http://httpd.apache.org">Apache</ulink> is always a good choice to start with. Both versions 1.3.x and 2.x will work just fine.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>PHP interpreter</term>
	  <listitem>
	    <para>You need <ulink url="http://www.php.net">PHP5</ulink>, the older PHP4 won't do. When building PHP, make sure to configure the software appropriately so the php5 Apache module gets built. If you install a prebuilt package, you may have to select an extra package that contains the appropriate module for your web server.</para>
	    <para>With the exception of session support, the RefDB PHP interface relies solely on core features of PHP5. You may therefore have to install PHP5 session support separately. However, on some systems like FreeBSD, "core" does not mean "it's there". If the PHP5 core is split into several packages, you may also have to install DOM, XML, and XSL support separately.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>
    <sect2 id="sect-php-apacheconfig">
      <title>Web server configuration</title>
      <para>The following instructions assume that you use Apache as your web server. The configuration file is usually <filename>/etc/apache/httpd.conf</filename> or <filename>/usr/local/etc/apache/httpd.conf</filename>.</para>
      <itemizedlist>
	<listitem>
	  <para>Locate the section "Dynamic Shared Object (DSO) Support". Check if the php5 module is loaded anyway. If not, add a line like the following:</para>
	  <programlisting>
LoadModule php5_module    libexec/apache/libphp5.so
	  </programlisting>
	</listitem>
	<listitem>
	  <para>The subsequent section in the config file needs to be updated too if you had to add the php5 module:</para>
	  <programlisting>
AddModule mod_php5.c
	  </programlisting>
	</listitem>
	<listitem>
	  <para>Further down there should be a section containing Aliases. Create a new one within this section like this:</para>
	  <programlisting>
    Alias /refdb/ "/usr/local/share/refdb/www/"

    &lt;Directory "/usr/local/share/refdb/www"&gt;
        AllowOverride None
        Order allow,deny
        Allow from all
        AddType application/x-httpd-php .php .phtml
    &lt;/Directory&gt;
	  </programlisting>
	  <para>The paths point to the files that RefDB installs with all other shared files. If you intend to customize or modify the interface, you can copy the files to a directory in your home folder and change the directories in the config file accordingly.</para>
	</listitem>
	<listitem>
	  <para>Finally you'll have to let the Apache server re-read it's configuration file:</para>
	<screen><prompt>~# </prompt><userinput>apachectl restart</userinput></screen>
	</listitem>
      </itemizedlist>
    </sect2>
    <sect2 id="sect-php-test">
      <title>Test your PHP interface</title>
      <para>To see the PHP interface in action, first make sure that the RefDB application server is running:</para>
	<screen><prompt>~# </prompt><userinput>refdbctl start</userinput></screen>
	<para>Now start your web browser and point it to:</para>
	<screen>localhost/refdb/</screen>
	<para>Please note the trailing slash! Now you should be greeted by the login screen.</para>
    </sect2>
  </sect1>
</chapter>