Change include cpp var name
[idzebra-moved-to-github.git] / doc / Notes
1 The secret guide to what to actually _do_ when configuring Zebra
2 ----------------------------------------------------------------
3
4 (This is a not-for-public-consumption document that airs rather too
5 much dirty laundry.  It throws up rather a lot of "why" questions, but
6 should at least solve some "what" problems.)
7
8
9 1.  Create a zebra.cfg file that specifies:
10         profilePath: .:../../tab
11         recordType: grs.sgml
12
13 2.  Add a
14         attset: whatever.att
15     for every attribute set that you want clients to be able to use in
16     queries without being told "unsupported attribute set".
17
18 3.  Add
19         tagsysno: 0
20     if you plan to generate your own unique identifiers as (for
21     example) a Zthes data-set must do.
22
23 4.  Look at the document element of your XML input files.  What is the
24     element?  Create a "something.abs" file named after the document
25     element: for example, when dealing with Zthes data, you need to
26     make "Zthes.abs" (capitalisation as specified, because that's
27     what's in the XML).  In that file, put the following lines.
28
29 5.  Add "attset whatever.att" directive for each attribute set that
30     you want to support.  Yes yes, I know you already did that in the
31     "zebra.cfg" file: this is just the way it is.
32
33 6.  Add "tagset whatever.tag" for every tag-set used by the GRS-1
34     schema you want to present to clients.
35
36 7.  Add "xpath enable" if you want clients to be able to use XPath
37     access points like this:
38         find @attr 1=/Zthes/termName sauroposeidon
39
40 8.  For each element in the GRS-1 schema specified by the profile
41     you're trying to implement, add a line that says:
42         elm (<tagSet>,<tagValue>) <elementName> !
43     for example,
44         elm (1,14) termId !
45     For elements that you don't need to be able to search, substitute
46     "-" for the "!" at the end of the line.
47
48     Nested elements (within sub-structures) look like this:
49         elm (2,30)/(4,3) relationType -
50
51 9.  For each tagset you referenced in the whatever.abs file, copy the
52     relevant file from the zebra/tab directory.  For every tag listed
53     in that file that you use, if your XML input files use a different
54     element name from what's already listed, add your element name
55     after the offical one, separated by a slash like this:
56         tag 1 title/termName string
57
58     These hacked tagset files will be used in preference to the
59     distributed one because your profilePath (see above) begins with
60     ".", the current directory.
61
62     For some profiles, you may need to create a brand new tagset file
63     because the Zebra distribution doesn't support them at all.  No
64     problem: just use an existing one as a template.
65
66 That should handle record-presentation side.  Now for searching:
67
68 10. For each attset that you referenced in the zebra.cfg and
69     whatever.abs files, either:
70         A. Copy the distributed .att file       ### Is this right?
71         B. Create a new whatever.att file
72     For every access point that you want to be able to use, change the
73     access-point name to the corresponding element-name in the input
74     XML files.
75
76 Issues:
77 * How can we set up separately access points for elements with the
78   same tagnames but at different places in the record structure?
79 * This is all a bit crap, isn't it?