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
|
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Rarian Scrollkeeper Compatibility</title>
</head>
<body>
<p><a href="index.xhtml">return to index</a></p>
<h1>Rarian Scrollkeeper Compatibility</h1>
<p>In addition to its new (and better) meta-data format, Rarian also
provides backwards compatibility for scrollkeeper. This section
outlines the basics of scrollkeeper files and how to use them. Don't
expect too much though.</p>
<p><strong>Note</strong>: If you are using GNOME, it is strongly
recommended that you use <em>gnome-doc-utils</em>, which is described
on <a
href="http://live.gnome.org/GnomeDocUtilsCreateNew">live.gnome.org</a>.</p>
<h2>Scrollkeeper Meta-data files</h2>
<p>Scrollkeeper uses <em>omf</em> files, which are XML based. The
main text elements that are of interest are:</p>
<dl>
<dt>title</dt>
<dd>The title of the document</dd>
<dt>description</dt>
<dd>The description of the document (the blurb that appears in table
of contents)</dd>
<dt>creator</dt>
<dd>The creator of the documentation</dd>
<dt>maintainer</dt>
<dd>The person that currently looks after the documentation</dd>
<dt>type</dt>
<dd>The type of the documentation ("user's guide" etc.)</dd>
<dt>date</dt>
<dd>The last revision date of the documentation</dd>
</dl>
<p>Other fields that have attributes:</p>
<dl>
<dt><em>node</em></dt>
<dd><em>attributes</em>: what is does</dd>
<dt>version</dt>
<dd>identifier: Who knows?,<em> date</em>: As the date field</dd>
<dt>subject</dt>
<dd><em>category</em>: Which category the document belongs to. A list of
categories can be found on <a
href="http://scrollkeeper.sourceforge.net/documentation/categories.html">
the scrollkeeper website</a></dd>
<dt>format</dt>
<dd><em>mime</em>: the mime type of the document, <em>dtd</em>: the dtd of the document
(like "-//OASIS//DTD DocBook XML V4.3//EN")</dd>
<dt>identifier</dt>
<dd><em>url</em>: The URI of the actual documentation (bet you were wondering
where that was, weren't you?)</dd>
<dt>language</dt>
<dd><em>code</em>: The language code describing the language the document
described by the meta-data is in..</dd>
<dt>relation</dt>
<dd><em>seriesid</em>: The unique scrollkeeper seriesid. Can be generated
using the <em>scrollkeeper-gen-seriesid</em> program.</dd>
<dt>rights</dt>
<dd><em>type</em>: The license the documentation is available under,
<em>license.version</em>: The specific version of the license, <em>holder</em>: Who
actually holds the license.</dd>
</dl>
<h2>Example scrollkeeper file</h2>
<pre>
<?xml version="1.0" encoding="utf-8"?>
<omf>
<resource>
<creator>The Professor <theprof@example.com></creator>
<maintainer>The Professor <theprof@example.com></maintainer>
<title>The Beanstalk User Guide</title>
<date>June 2021</date>
<version identifier="The Beanstalk User Guide v1.0" date="June 2021"/>
<subject category="GNOME|Desktop"/>
<description>
Beanstalks are big and may, if you're very, very lucky, lead to
golden eggs.
</description>
<type>user's guide</type>
<format mime="application/xhtml+xml" dtd="-//W3C//DTD XHTML 1.0 Strict//EN"/>
<identifier url="beanstalk.xhtml"/>
<language code="C"/>
<relation seriesid="ceae33be-2a60-11dc-9e02-e1e3ec1cb44f"/>
<rights type="GNU FDL" license.version="1.1" holder="The Professor"/>
</resource>
</omf>
</pre>
<p>Basically, it's easier to copy this example and modify it to suit
your needs than to try and write your own.</p>
<p>Normally, the name of your omf files (after installation) should
be <package name>-<langcode>.omf. Before installation,
you can name it whatever you want. However, I'd recommend:</p>
<pre><package name>-<langcode>.omf.in</pre>
<p>So for the beanstalk example, the distributed file (in source
archives, i.e. to allow people to install it anywhere) would be:</p>
<pre>beanstalk-C.omf.in</pre>
<p>Which is then converted using <em>scrollkeeper-preinstall</em>,
described below.</p>
<h2>Installing documentation</h2>
<p>Scrollkeeper installation is a little ... quirky. First, copy
your actual documentation to where you want. To install the
meta-data, fist run <em>scrollkeeper-preinstall</em> using the
arguments like:</p>
<pre>scrollkeeper-preinstall <installed doc name> <current omf name> <new omf name></pre>
<p>For example, for the beanstalk manual, this might look like:</p>
<pre>scrollkeeper-preinstall /usr/share/beanstalk/manual/C/beanstalk.xhtml beanstalk-pre-C.omf beanstalk-C.omf</pre>
<p>After that, you can now copy the newly generated omf file into
<prefix>/share/omf/<name>/ where <name> is generally
the name of your package. Repeat this procedure for each language.</p>
<p>Afterward, you can now run <em>scrollkeeper-update</em>. This has
a few options you must specify to get the correct behaviour. This
will need some tweaking, but in general:</p>
<pre>scrollkeeper-update -o <prefix>/share/omf</pre>
<p>Should get you reasonably close. (If using Rarian, this will be
sufficient).</p>
<p>And that's it. You'll probably want to put this stuff in your
makefiles. I have no idea how to do all this. I'd recommend looking
for other packages that use scrollkeeper and adapt their stuff. (It's
like the old autoconf joke - only 2 people have ever written a
configure.in, everyone else just copies them)</p>
</body>
</html>
|
