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
|
#
# journal-dev - Manual
# Last modification: Sun, 2 Feb 1997 02:10:20 +0200
# Copyright (c) 1996 by Fabrizio Polacco <fpolacco@debian.org>
# see the "copyright" file.
This is a draft of the documentation on how to use the package
journal-dev to build an on-line magazine.
It is pretty verbose, 'couse my experience says that is better to give
more informations than less :-)
FREE JOURNAL - base package
Imagine you want to debianize the on-line magazine Free Journal.
You will create a base package (fj-base, for example) to install the
hierarchy tree where will be created the index(es), where you put the
images needed by the index(es) and where each issue (one debian package
for each issue) will keep its articles.
This base package will have:
- the images directory, where you will put all (and only) the images
needed by the index;
- the .indexes directory, where you will put the files "index.head" and
"index.foot" with the first and the last part of your future index.
You can take these parts out of the existing indexes of the Free
Journal. If you want to separate each issue, the head and the foot
with an horizontal rule, I suggest to put only one <hr> tag in each
issue, and one in the foot OR in the head, depending if the rule is in
the beginning or at the end of the issue's part. I recommend also to
put an appropriate declaration as the first row of the head. Like:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Draft//EN">
You can use the full latin1 character set writing the text of the
index (as any article), without annoying yourself with the html
entities. An exception are the characters "<" and "&". To use them
INSIDE of the text you have to use the entities < and & .
If you are copying an existing html yet converted to html entities,
it is better to run the utility j_html2latin that journal-dev installs
in /usr/sbin. It copies the file source (first parameter) into the
file dest (second parameter) convertig all entities back to latin1,
except the angle brackets "<", ">", the ampersand "&" and the double
quotes '"'. Doing this conversion will make easier to read (and thus
to change or correct) the text in the sources.
- the debian structure. Although this is not a debian manual, I will
show only the parts that has relevance in building the debian version
of an on-line magazine using journal-dev.
- debian/control :
Section: misc
Architecture: all
Depends: journal
Recommends: www-browser | httpd
Suggests: fj-issues
- The Suggests field lists a virtual package named after the
package you are building (fj, Free Journal, in our example) and
is an example of the virtual package names in a cooperating
group of packages as described in the Debian policy manual,
3.1.2 Dependencies and virtual packages.
- The Depends field needs a simple explanation: the journal
package builds two binaries, journal and journal-dev. The latter
is the full package, but requires libwww-perl for some scripts
that are used ONLY form within the rules of the issues, so in
the purpose of not creating an unuseful dependance from the
issues to a large library, the binary package journal is build
to install ONLY the scripts needed by pre{inst,rm} and
post{inst,rm} scripts of the issues. Thus the single dependence
of the base package on the journal (run-time) package. The
issues will depend on the base package, of course.
- The recommends field ask alternatively for the web server or a
web client. The client can access the issues using the pseudo
protocol "file:", while the web server can be used to serve the
issues to the Net, without use of a local browser (in fact most
web servers doesn't run X anyway).
- debian/rules:
- particularly this makefile should do:
- build the normal doc directory (/usr/doc/$(package)
- build the base of the hierarchy of the magazine: I use
/usr/doc/free-journal , using the full name of the magazine
instead of its initials.
- Copy in this base the directory .indexes : this can be done
creating the directory and than copying each file using the
utility j_latin2html that journal-dev installs under
/usr/sbin. This utility is the exact opposite than the
j_html2latin that I mentioned above: copy a file converting
each latin1 character into the corresponding html entity.
It doesn't convert to entities the special characters "<",
">", "&" and '"', so can be used to convert tagged text (at
the contrary of other tools that converts everything,
leaving your tags broken). For example:
#
install -d -g root -m 755 -o root $(base)/.indexes
# copy with conversion to html entity
/usr/sbin/j_latin2html .indexes/index.head $(base)/.indexes/index.head;
/usr/sbin/j_latin2html .indexes/index.foot $(base)/.indexes/index.foot;
#
- debian/postinst:
- This script should rebuild the index, even if it could seem
unuseful (we don't have any issue installed yet, so the index
will be empty) it run also during upgrade from one version of
your base package to another. It is obviuos that in these
scripts it is better to be even pedantic, and test for the
presence of everything before using it. The example:
set -e
# adds the full index
if [ -d /usr/doc/free-journal/.indexes ]
then if [ -x /usr/sbin/j_mkindex ]
then echo "Building the whole index"
/usr/sbin/j_mkindex /usr/doc/free-journal
fi
fi
- debian/prerm:
- This script have to delete the index file, if it exists, because
otherways the disinstallation stage will fail encountering a
file (index.html) that is not listed in the Contents of the
package, leaving your package half removed and the hierarchy
still existent. This will be very annoying in case of an upgrade
that changes the location of the base directory.
That's all: your base package is quite ready.
- Copy the full hierarchy creating the "original source"
(something like cp -r fj-base-1 fj-base-1.orig ), remove the
debian directory (rm -rf fj-base-1.orig/debian ) and run, as
superuser, dpkg-buildpackage from inside fj-base-1.
FREE JOURNAL - each issue
The debianization of one issue is a little more complicated, but not so
much: you have the .indexes directory, the images directory, the debian
one (obviously) and the html for the articles.
Naming convention. I have used a particular naming convention, to allow
the scripts to find the parts without using the name of the magazine.
Each issue (and thus the package) will have the name formad by the
initials of the magazine (fj in our example), two numbers of the year
(96 for example), and the number of the issue in the form nXX where XX
ranges from 00 to 99. So our example will have fj96n01, fj97n02,
fj97n03, etc.
Each index part will be idx_n??.full and idx_n??.blind, where ?? is the
number of the issue (when we will have a journal with 100 issues it will
be better to add another index scheme, because an index such that could
be unreadable :-) The .blind index is a copy of the .full index with all
its links anchors commented out, in such a way to be used in the index
when the issue has been removed, leaving the user the possibility to
consult (and search) the TOC without reinstalling each issue. At the
present moment you have to do this by hand, but in the future I will
write a script that adds this comments automatically, so the blind index
will be created by the rules script.
- .indexes In this directory you will put (write) the index of the
issue, the part that will go after index.head and before index.foot .
If this part of the index loads some image you have to decide what to
do with those images:
- If the image will be used in more indexes it is definitely
better to install it in the base package, and indicate in the
depends: field (of each issue that use that image) also the
version number of the base package in which you will put the
image.
- If the image will be used only in this issue you can install it
in the images directory under the base hierarchy creating an
hard link in the postinst (so the two files will not occupy more
room, and the remove of the issue will leave the image for the
index), but you have to remove it by hand in the postrm stage if
the user purge the issue.
- The possibility of refering to the image in the issues directory
is not usable, because after removing the issue the index (the
blind one) will still be visible, while the image directory will
be gone.
- images This directory has nothing special, as it contains only
the images needed by this issue. Is to be noted that it is better to
duplicate in this directory an image that is present also in the base
images directory, unless it is larger than few kilobytes. If you
decide to refere to an 'index' image from an article, it is better to
put a marker in the base package to impede that a future change in the
index structure or appearance will make the image disappear ...
- html In this directory you will put all the articles of the issue,
with a coupple of special files that will controll the order of the
articles and their aspect.
- html.list This file contains the ordered list of the
articles, jouined with some informations to be added to the
template. For readability purposes I have chooses the TAB as the
field separator in this file; you can't use tabs inside of a
filed.
- The first field is the name of the file. You can put here
the full name of the target file with the extension .html or
the name without extension, BUT terminated by the point.
- The second field is the string that will be put in the ALT
attribute of each anchor pointing to the file of the row.
- The third field is the title of the article, that included
between the <table> tag. In the index row, this field is a
generic title that will be put on top of each page, if you
choose do do in this way.
- The fourth field is the subtitle of the article, some kind
of type specifyer to be displayed in the page. On the index
row, this field contains the named anchor to refere in the
links back to the index, where you would have put an anchor
like <a name="fj96n01">.
- All these strings are really to be interpreted as simple
"variables" that you put in the proper place inside your
articles and/or templates and that will be substituted with
the proper values by the utility j_mkhtml . The usage
suggested here is only one of the possible use of this
mechanism, although I have tested only this, so I can't
assure that another one will work, while I can't say that
don't. Anyway, it is better that you let me know of such a
new use, so I will try not to break it in the future :-)
- The first row will contain some reference to the index:
# First row, special case:
# -1- @@index-name@@ name of index file
# -2- @@index-alt@@ ALT string used in links to index
# -3- @@heading@@ string used on top of each page
# -4- @@anchor@@ anchor name for link to index
#-----(1)----- --------(2)-------- --------(3)------- ---(4)---
../index. Indice Free Journal nr.1 fj96n01
#
- The following rows are
#
# ordered list of files:
# -1- @@filename@@ the name of the file without ext (but with dot)
# @@prev-name@@ the name of the file in the previous row
# @@next-name@@ the name of the file in the next row
# -2- @@alt@@ ALT string used in links to this file
# @@prev-alt@@ ALT string used in links to the previous file
# @@next-alt@@ ALT string used in links to the next file
# -3- @@title@@ the title of the html page
# -4- @@type@@ the type, used in subheadings
#
#-----(1)----- --------(2)-------- --------(3)-------------- ----(4)----
editor. Editoriale FJ 1: Editoriale Editoriale
lettere. Lettere FJ 1: Lettere Lettere
linux. Linux versione 2 FJ 1: Linux 2 Articoli
- html.wrapper The second special file contains the template
used to build each article of the journal. This file can be
splitted in several pieces using the @@!include <filename> @@
directive. An example is more worth than a thousand words:
@@!erase@@
@@!erase@@ html.wrapper
@@!erase@@ Last modification: Tue, 15 Oct 1996 17:00:20 EET DST
@@!erase@@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Draft//EN">
<html>
<head>
<title>@@title@@</title>
</head>
<body bgcolor="#ffffff">
@@!include html.table @@
<hr>
@@!include BODY @@
<hr>
@@!include html.table @@
</body>
</html>
the special directive @@!include BODY @@ uses the filename
listed in the first field of the html.list to discover the file
to be included. As you can see the reference to @@title@@ will
be substituted with the content of the third field from the
articles rows of the html.list file. The special directive
@@!erase@@ tells the tool to erase the row from the target. it
is useful for comments that you don't want visible on the web.
Th efile html.table, included in the example, is not required,
but is a good example on how to split the template. In this
example, the html.table is included twice, before and after the
body of the article, resulting in a header and a footer.
To complete the example I include here the full html.table file:
@@!erase@@ html.table
@@!erase@@ Last modification: Mon, 21 Oct 1996 00:58:10 +0300
<table border=0 cellpadding=10 width=100%>
<tr valign=bottom>
<td align=left width=40% colspan="1">
<font size=+3 color="#ff0000">
<i>@@heading@@</i>
</font>
<td align=center width=10% colspan="1">
<a href="@@prev-name@@"><img src="images/a_left.gif"
align=right
alt="[@@prev-alt@@]"
hspace=10
border=0
></a>
<td align=center width=10% colspan="1">
<a href="@@index-name@@"><img src="images/a_up.gif"
align=middle
alt="[@@index-alt@@]"
hspace=10
border=0
></a>
<td align=center width=10% colspan="1">
<a href="@@next-name@@"><img src="images/a_right.gif"
align=left
alt="[@@next-alt@@]"
hspace=10
border=0
></a>
<td align=right width=30% colspan="1">
<img src="images/minilogo.gif"
align=bottom
border=0
hspace=10
vspace=0
>
<font size=+3 color="#ff0000">
<i>@@type@@</i>
</font>
</td>
</tr>
</table>
This file, toghether with the values listed in the html.list
file, can build a chain of links that brings you from the first
article to the index and back.
The use of the values for @@heading@@ and @@type@@ are not
strictly these, so you can put what you want in that fields and
place the variable marker where you want, even inside of the
article's body (although I don't see any utility inside there)
- article.body Each article should be put in a file named with
the name listed in the first filed of the html.list file, with
the .body extension. It should not contain the <html>, <head>,
<title> and <body> tags.
- debian/control :
Architecture: all
Depends: fj-base
Provides: fj-issues
Each issue must depend on the base package, and must provide the
virtual package that is suggested in the base package.
- debian/rules:
- particularly this makefile should do:
- build the normal doc directory (/usr/doc/$(package)
- add the issue dir to the base of the hierarchy of the
magazine: /usr/doc/free-journal/fi96n02 , for example, and
the subdirectoryes images and .index
- Then we have to copy the images, create and install the html
files of the articles (converting the latin1 characters to
entities):
cp -r images $(issue)
/usr/sbin/j_mkhtml ./html ../$(issue)
for file in `ls .indexes/*`; do \
/usr/sbin/j_latin2html $$file $(issue)/$$file; \
done
- If the blind index is simply a full index without any
anchor, then I suggest adding this line that builds a blind
index from a full one:
sed 's/href=[^>]*>/>/g' $(issue)/.indexes/$(index).full \
>$(issue)/.indexes/$(index).blind
- debian/postinst:
- This script should copy the .full index in the .indexes
directory of the base hierarchy, eventually removing the .blind
one and then rebuild the index. It is obviuos that in these
scripts it is better to be even pedantic, and test for the
presence of everything before using it. The example:
set -e
# adds the full index
add_full_index()
{
if [ -d $journal/.indexes ]
then if [ -r $journal/$package/.indexes/$index.full ]
then echo " Installing the full index of this issue."
cp $journal/$package/.indexes/$index.full $journal/.indexes
#
if [ -r $journal/.indexes/$index.blind ]
then echo " Removing the blind index."
rm -f $journal/.indexes/$index.blind
fi
echo " Rebuilding the whole index"
/usr/sbin/j_mkindex $journal
fi
fi
}
package="fj96n01";
index="idx_n01"
journal="/usr/doc/free-journal"
if [ "$1" = "configure" ]
then add_full_index
fi
- debian/prerm:
- This script have to delete the full index and copy the .blind
one in the .indexes directory of the base hierarchy. Nothing
else, because the index will be remade in the postrm stage, when
we will know if this is a remove or a purge.
set -e
copy_blind_index()
{
# adds the blind index and removes the full index
if [ -d $journal/.indexes ]
then if [ -r $journal/$package/.indexes/$index.blind ]
then echo " Leaving a blind index for this issue."
cp $journal/$package/.indexes/$index.blind
$journal/.indexes
fi
# remove anyway
if [ -r $journal/.indexes/$index.full ]
then echo " Removing the full index."
rm -f $journal/.indexes/$index.full
fi
fi
}
package="fj96n01";
index="idx_n01"
journal="/usr/doc/free-journal"
if [ "$1" = "remove" ]
then copy_blind_index
fi
- debian/prerm:
- This is the script that make the new index with or without the
blind index of this issue.
set -e
delete_blind_index()
{
# removes the blind index
if [ -d $journal/.indexes ]
then if [ -r $journal/.indexes/$index.blind ]
then echo " Purging the index"
rm -f $journal/.indexes/$index.blind
fi
fi
}
rebuild_index()
{
if [ -d $journal/.indexes ]
then
/usr/sbin/j_mkindex $journal
fi
}
package="fj96n01";
index="idx_n01"
journal="/usr/doc/free-journal"
if [ "$1" = "remove" ]
then echo " Rebuilding the whole index"
rebuild_index
fi
if [ "$1" = "purge" ]
then delete_blind_index
echo " Rebuilding the index without the $package issue"
rebuild_index
fi
That's all, good work!
|
