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
|
KPilot PalmDoc Conduit bookmark Specification
=============================================
(c) 2003 Reinhold Kainhofer, reinhold@kainhofer.com
This document is licensed under the FDL (Free Documentation License)
as published by the FSF. Any version of the FDL can be applied
at your convenience.
The PalmDoc conduit has three ways to indicate bookmarks for a text:
-) Inline tags of the form <* bookmarkname *>
-) Endtags of the form <bookmarkname> at the end of the document
-) Regular expressions in a separate textname.bmk file
(textname.bmk ist the filename of the text with the .txt replaced by .bmk)
In the design of the .bmk file, I tried to stay close to the
syntac of MakeDocJ bookmark files, but it turned out that I
needed to extend the syntax a little. Also, MakeDocJ uses Java
RegExps, while the PalmDoc conduit uses the QRegExp, which have
some slight differences (especially concerning the ^ and $
patterns as well as backreferences). So if you used MakeDocJ,
the .bmk file syntax will be quite familiar, but you will still
have to adapt your bookmark files for Qt regular expressions
instead of Java regular expressions
1) INLINE TAGS
Whenever a tag of the form <* someText *> appears in the text,
this sequence is removed from the text, and a bookmark is set
there with the bookmark name "someText" (the part between the
<* and the *>).
2) ENDTAGS
If the text ends with tags of the form <someText>, the string
in braces is used as bookmark name, and wherever it appears in
the text, a bookmark is set.
After the > any number of whitespace is allowed, but no other
characters like letters, numbers, or punctuation. Also, inside
the braces no line break must occur. The conduit searches the
text from the end and if it finds a line break inside a <...>
sequence, the tag and everything before it is assumed to belong
to the text and doesn't form a bookmark tag.
Between endtags any number of whitespace (spaces, tabs, line
feeds etc.) is allowed.
As an example, assume you have a text ending in:
... the bad guy was punished, and they lived happily
ever after!
<Tag with
line feed>
<bad guy> <princess>
<married>
The conduit starts at the end, ignores all whitespace between
the tags, so it finds the tags "married", "princess", and "bad guy".
The "Tag with line feed" has a line feed, so it is assumed to belong
to the text.
Assume now you have a text ending in:
... the bad guy was punished, and they lived happily
ever after!
<bad guy> The End <princess>
<married>
Here, only "married" and "princess" are found as bookmarks. Because
of the letters before the "princess" tags, the search for the
bookmarks ends at the letter "d" of "The End" (the conduit starts
from the end and moves backward until it finds some text which
cannot be seen as a endtag.
3) REGULAR EXPRESSIONS IN A SEPARATE FILE
This is by far the most complex way to specify bookmarks, but
it is also the mose powerful.
If you have a text with filename "My fairy tale.txt", the
bookmarks will be specified in a file called "My fairy tale.bmk"
(just the text filename with the .txt replaced by .bmk). This
file contains the bookmark definitions, one in each line. Lines
starting with a # are seen as comments, and empty lines are also
ignored.
In the .bmk file, each bookmark line has one of the following syntaces
(I will explain all fields later on). Fields in [..] are optional:
bmkName
bmkPosition, bmkName
+, bmkPatternRegExp[, bmkNameAsString[, firstIncludedBmk[, lastIncludedBmk]]]
+, bmkPatternRegExp[, bmkNameIndexOfSubexpression[, firstIncludedBmk[, lastIncludedBmk]]]
-, bmkPatternRegExp[, bmkNameAsString]
-, bmkPatternRegExp[, bmkNameIndexOfSubexpression]
If the first field is a string, it is used as the bookmark name
and pattern to search for.
If the first field is a number, it means the position of the
bookmark, and the second field is the name of the bookmark.
If the first field is either + or -, the second field gives
a regular expression that is used to find the position of the
bookmark. If the first field is a -, the search is done only
once and only the first match will be added as bookmark. If
the first field is a +, the search is done until the regular
expression can no longer be found (the fourth and fifth fields
can be used to include only a certain range of hits). If there
is a third field, and it is a string, it gives the name of the
bookmark as a regular expression (i.e. \1 are replaced by the
first subexpression of the search, where subexpressions are
specified by round brackets in the regexp of the second field).
If there is a third field, and it is a number, it gives the index
of the subexpression of bmkPatternRegExp that is used as the
bookmark name.
If there is no third field, the whole matched text will be used
as bookmark name.
The optional fourth and fifth fields can be used to set bookmarks
only after the first few ocurrences of the regexp in the text, and
to stop the search after the expression has been found a certain
number of times.
If the PDB->PC sync is set up to store the bookmarks in a bookmark file,
it will create a file "My fairy tale.bm" (no "k") with entries of the form
position,bmkName
The .bmk file will be used if it exists, but if no .bmk file exists, the .bm file
will be used. This way you can override the bookmark settings, while
at the same time the PDB->TXT sync does not destroy your possibly
existing .bmk file.
Examples:
1) Imagine you have a line like:
frog princess
In this case, the text is searched for "frog princess", and a
bookmark is set whenever "frog princess" occurs in the text.
The name of each of these bookmarks will be "frog princess".
2) A bookmark line:
55, Bookmark at offset 55
Here, a bookmark will be set at offset 55 (55th character of
the text), and it will have the name "Bookmark at offs" (truncated
to 16 characters)
3) A bookmark line
-,Chapter \d+
causes a bookmark to be set at the first ocurrence of "Chapter XXX",
where XXX denotes one or more digits. The bookmark name will be
"Chapter XXX" (XXX replaced by the actual digits).
4) A bookmark line
+,Chapter \d+
causes bookmarks to be set wherever "Chapter XXX" (XXX being one
or more digits) appears in the text. The bookmark name will again
be "Chapter XXX", but the search does not stop after the first hit.
5) A bookmark line
+,\n\s*(Chapter \d+)\D+, 1
causes a bookmark to be set whenever a new line starts with
"Chapter XXX" (whitespace is allowed before the "Chapter"), and
uses the first subexpression in (..) as the bookmark name. If you
have a passage
Chapter 15: here it starts
The regular expression will match, so a bookmark will be set there
and the subexpression "Chapter 15" (which matches the (Chapter \d+) )
will be used as bookmark text.
6) A bookmark line
+,\n\s*Part (\d+),\1\. part
sets a bookmark whenever a line starts with "Part XXX". The XXX
will be stored as the first matched subexpression. The third field
"\1\. part" is the regular expression for the bookmark name, where
\1 is replaced by the first matched subexpression of the search (XXX
in this case). So if a line starts with " Part 17: ", the bookmark
name will be "17. part".
7) A bookmark line
+,Table (\d+): ,\1\. Tabelle,5,25
will match whenever "Table XXX: " appears in the text, and the bookmark
name will be "XXX. Tabelle". However, the fourth field means that the
first four hits are ignored (the 5th hit is the first hit to be included
as a bookmark), and the fifth field means that all further hits after the
25th will be ignored, too.
8) In law texts, I use a regular expression
+,\n *(§\.? *\d+[a-z]?\.?) +, 1
to search for all paragraphs starting like "§. 15. " or " §23 ", and set
a bookmark there using only the part from the § to the last digit or the
full stop after the last digit (the pattern between the (), in our two
cases the bookmark names will be "§. 15." and "§23" ).
|
