source: template/template.xml

trunk
Last change on this file was 36746be, checked in by Pierre Labastie <pierre.labastie@…>, 3 months ago

Update the comment about $Date$ in template

  • Property mode set to 100644
File size: 15.0 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!-- Place this in the packages.ent file
8 <!ENTITY TEMPLATE-version "">
9 -->
10
11 <!ENTITY TEMPLATE-download-http "http://">
12 <!ENTITY TEMPLATE-download-ftp "ftp://">
13 <!ENTITY TEMPLATE-md5sum "MD5 sum">
14 <!ENTITY TEMPLATE-size "?? MB">
15 <!ENTITY TEMPLATE-buildsize "?? MB">
16 <!ENTITY TEMPLATE-time "?? SBU">
17<!-- SBU should be rounded to integer if greater than 10, to one
18 decimal if below 10, and should be "less than 0.1 SBU" if
19 below 0.1. If the SBU without parallelisation is too long,
20 it is acceptable to give the value "with parallelism=N", where
21 N is the number of threads used. Note that some build system
22 automatically fix N equal to the number of available CPU cores
23 on the machine. -->
24]>
25
26<!-- Try to keep the indentation used in this file-->
27<sect1 id="TEMPLATE" xreflabel="TEMPLATE-&TEMPLATE-version;">
28 <?dbhtml filename="TEMPLATE.html"?>
29
30 <sect1info>
31 <!-- this part gets updated when rendering the book on rivendell.
32 In your local copy, it is just $Date$ -->
33 <date>$Date$</date>
34 </sect1info>
35
36 <!-- No other tags inside any title.
37 Use Title Case in All Titles -->
38 <title>TEMPLATE-&TEMPLATE-version;</title>
39
40 <indexterm zone="TEMPLATE">
41 <primary sortas="a-TEMPLATE">TEMPLATE</primary>
42 </indexterm>
43
44 <!--Required section-->
45 <sect2 role="package">
46 <title>Introduction to TEMPLATE</title>
47
48 <para>
49 The <application>TEMPLATE</application> package contains...
50 This is useful for...
51 </para>
52
53 <!-- if it builds but hasn't been tested: -->
54 &lfs1?_built;
55 <!-- if it works: -->
56 &lfs1?_checked;
57
58 <bridgehead renderas="sect3">Package Information</bridgehead>
59 <itemizedlist spacing="compact">
60 <listitem>
61 <para>
62 Download (HTTP): <ulink url="&TEMPLATE-download-http;"/>
63 </para>
64 </listitem>
65 <listitem>
66 <para>
67 Download (FTP): <ulink url="&TEMPLATE-download-ftp;"/>
68 </para>
69 </listitem>
70 <listitem>
71 <para>
72 Download MD5 sum: &TEMPLATE-md5sum;
73 </para>
74 </listitem>
75 <listitem>
76 <para>
77 Download size: &TEMPLATE-size;
78 </para>
79 </listitem>
80 <listitem>
81 <para>
82 Estimated disk space required: &TEMPLATE-buildsize;
83 </para>
84 </listitem>
85 <listitem>
86 <para>
87 Estimated build time: &TEMPLATE-time;
88 </para>
89 </listitem>
90 </itemizedlist>
91
92 <!-- As required -->
93 <bridgehead renderas="sect3">Additional Downloads</bridgehead>
94 <itemizedlist spacing="compact">
95 <listitem>
96 <para>
97 Required patch:
98 <ulink url="&patch-root;/TEMPLATE-&TEMPLATE-version;-patch_name-patch_version.patch"/>
99 </para>
100 </listitem>
101 </itemizedlist>
102
103 <bridgehead renderas="sect3">TEMPLATE Dependencies</bridgehead>
104
105 <bridgehead renderas="sect4">Required</bridgehead>
106 <para role="required">
107 <xref linkend="BLFS_DEPENDENCY"/> <!-- notice no period as this is not
108 a sentence. If there are more than two, they must be separated by commas
109 with the last member having "and" in front of it. The use of a serial
110 comma is preferred (a comma after the next to last member before the
111 "and"). BLFS_DEPENDENCY should be an "id" attribute defined somewhere
112 in the book (usually in a <sect1>). -->
113 <xref role="runtime" linkend="RUNTIME_DEPENDENCY"/> (runtime)
114 <!-- Specifying that a dependency is a runtime one, may avoid circular
115 dependencies. Add role="runtime" to help jhalfs -->
116 </para>
117
118 <!-- It may be nice to have a separate section for runtime dependencies.
119 Do it as follows. -->
120 <bridgehead renderas="sect4">Required at runtime</bridgehead>
121 <para role="required">
122 <xref role="runtime" linkend="RUNTIME_DEPENDENCY"/>
123 </para>
124
125 <!-- As required -->
126 <bridgehead renderas="sect4">Recommended</bridgehead>
127 <para role="recommended">
128 <xref linkend="BLFS_DEPENDENCY"/> <!-- notice no period as this is not
129 a sentence. See above for the use of "and" and commas. Normally, neither
130 required nor recommended dependencies should be <ulink>. -->
131 <xref linkend="ANOTHER_RECOMMENDED_DEP"/> (required if building
132 <xref role="nodep" linkend="SOME_FANCY_PACKAGE"/>) <!-- You may need
133 to refer to another package, which is not a dependency. Use the role
134 attibute with value "nodep". -->
135 <!-- See above for runtime dependencies -->
136 </para>
137
138 <!-- As required -->
139 <bridgehead renderas="sect4">Optional</bridgehead>
140 <para role="optional">
141 <xref linkend="BLFS_DEPENDENCY"/> and
142 <ulink url="http://www.some.url/">EXTERNAL DEPENDENCY</ulink>
143 <!-- notice no period as this is not a sentence. See above for the use
144 of commas and "and". The order should <xref> before <ulink>.-->
145 <!-- See above how to refer to another package, which is not a
146 dependency. -->
147 </para>
148
149 <para condition="html" role="usernotes">
150 User Notes: <ulink url="&blfs-wiki;/TEMPLATE"/>
151 </para>
152 </sect2>
153
154 <!-- Optional section for packages that need a specific kernel
155 configuration-->
156 <sect2 role="kernel" id="TEMPLATE-kernel">
157 <title>Kernel Configuration</title>
158
159 <para>
160 Enable the following options in the kernel configuration and recompile the
161 kernel if necessary:
162 </para>
163
164<!-- Spaces are significant in <screen> sections -->
165<screen><literal>Master section ---&gt;
166 Subsection ---&gt;
167 [*] Required parameter [CONFIG_REQU_PAR]
168 &lt;*&gt; Required parameter (not as module) [CONFIG_REQU_PAR_NMOD]
169 &lt;*/M&gt; Required parameter (could be a module) [CONFIG_REQU_PAR_MOD]
170 &lt;*/M/ &gt; Optional parameter [CONFIG_OPT_PAR]
171 [ ] Incompatible parameter [CONFIG_INCOMP_PAR]
172 &lt; &gt; Incompatible parameter (even as module) [CONFIG_INCOMP_PAR_MOD]</literal></screen>
173
174 <para>
175 Select the appropriate sub-options that appear when the above options are
176 selected. As much as possible, the layout should be the same as in
177 kernel menus.
178 </para>
179
180 <indexterm zone="TEMPLATE TEMPLATE-kernel">
181 <primary sortas="d-TEMPLATE">TEMPLATE</primary>
182 </indexterm>
183 </sect2>
184
185 <!--Required section-->
186 <sect2 role="installation">
187 <title>Installation of TEMPLATE</title>
188
189 <para>
190 Install <application>TEMPLATE</application> by running the following
191 commands:
192 </para>
193
194<!-- Spaces are significant in <screen> sections -->
195<screen><userinput>./configure --prefix=/usr --disable-static &amp;&amp;
196make</userinput></screen>
197
198 <!-- Optional paragraph. Add it when some instructions for building
199 documentation need optional or external packages. The remap="doc"
200 attribute signals those kind of instructions. Note: instructions
201 for generating documentation that can be built with
202 recommended/required/LFS book packages may be included in the
203 same block as configure and make. -->
204
205 <para>
206 If you have installed <xref linkend="optional-dep"/>, you can build
207 the documentation (or additional formats of the documentation) by issuing: </para>
208
209<screen remap="doc"><userinput>make -C doc pdf</userinput></screen>
210
211 <!-- adjust the instructions as needed. -->
212
213
214 <!-- Optional paragraph. Use one of the two mentions below about a test
215 suite, delete the line that is not applicable. Of course, if the
216 test suite uses syntax other than 'make check', revise the
217 line to reflect the actual syntax to run the test suite -->
218
219 <para>
220 This package does not come with a test suite.
221 </para>
222
223 <para>
224 To test the results, issue: <command>make check</command>.
225 </para>
226
227 <!-- Sometimes, more complex instructions are needed for running tests, or
228 they need to be run as root. They can then be put inside screen
229 tags using the remap="test" attribute as in the following example: -->
230
231 <para>
232 If you want to run the tests, first create some needed files:
233 </para>
234
235<screen remap="test"><userinput>make prepare-tests</userinput></screen>
236
237 <para>
238 Then run the tests as the <systemitem class="username">root</systemitem>
239 user:
240 </para>
241
242<screen role="root" remap="test"><userinput>make tests</userinput></screen>
243
244 <para>
245 Now, as the <systemitem class="username">root</systemitem> user:
246 </para>
247
248<screen role="root"><userinput>make install</userinput></screen>
249 </sect2>
250
251 <!-- Optional paragraph for documentation that has been generated using
252 optional/external packages: -->
253
254 <para>
255 If you have built the optional documentation, install it as the
256 <systemitem class="username">root</systemitem> user:
257 </para>
258
259<screen role="root"
260 remap="doc"><userinput>install -vdm 755 /usr/share/doc/template-&template-version; &amp;&amp;
261mv doc/* /usr/share/doc/template-&template-version;</userinput></screen>
262
263 <!--Optional section-->
264 <sect2 role="commands">
265 <title>Command Explanations</title>
266
267 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
268 href="../../xincludes/static-libraries.xml"/>
269
270 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
271 href="../../xincludes/gtk-doc-rebuild.xml"/>
272
273 <para>
274 <command>COMMAND</command>: This command does something.
275 </para>
276
277 <para>
278 <parameter>--PARAMETER</parameter>: This parameter does something
279 mandatory for BLFS purposes. It will be in the instructions above. It is
280 not optional and is why it is listed as a parameter and not an option.
281 </para>
282
283 <para>
284 <option>--OPTION</option>: This option does something optionally per the
285 user's desires. It is not listed in the instructions above, but instead,
286 is listed here because many (some) readers may want to include it.
287 </para>
288 </sect2>
289
290 <sect2 role="using">
291 <title>Using TEMPLATE</title>
292
293 <para>
294 Stuff about how to use TEMPLATE to do something. This section is rarely
295 used.
296 </para>
297 </sect2>
298
299 <!--Optional section-->
300 <sect2 role="configuration">
301 <title>Configuring TEMPLATE</title>
302
303 <sect3 id="TEMPLATE-config">
304 <title>Config Files</title>
305 <para>
306 <filename>~/.Configfilename1</filename> and
307 <filename>/etc/path/Configfilename2</filename> <!-- notice no period as this is not a sentence-->
308 </para>
309
310 <indexterm zone="TEMPLATE TEMPLATE-config">
311 <primary sortas="e-AA.Configfilename1">~/.Configfilename1</primary>
312 </indexterm>
313
314 <indexterm zone="TEMPLATE TEMPLATE-config">
315 <primary
316 sortas="e-etc-path-Configfilename2">/etc/path/Configfilename2</primary>
317 </indexterm>
318 </sect3>
319
320 <sect3><title>Configuration Information</title>
321
322 <para>
323 Blah blah blah about config.
324 </para>
325
326<screen><userinput>USER CONFIG COMMANDS</userinput></screen>
327
328<screen role="root"><userinput>ROOT CONFIG COMMANDS</userinput></screen>
329
330 <!-- File creation. Add the appropriate <indexterm> block if needed.-->
331 <para>
332 Create the file .... for ...
333 </para>
334
335<screen role="root"><userinput>cat &gt;&gt; /PATH/FILENAME &lt;&lt; "EOF"
336<literal># Begin FILENAME
337
338TEXT
339
340# End FILENAME</literal>
341EOF</userinput></screen>
342 </sect3>
343
344 <sect3 id="TEMPLATE-init">
345 <title>Boot Script</title>
346
347 <para>
348 To automatically start the <command>TEMPLATE</command> daemon when the
349 system is rebooted, install the
350 <filename>/etc/rc.d/init.d/TEMPLATE</filename> bootscript from the
351 <xref linkend="bootscripts" revision="sysv"/>
352 <xref linkend="systemd-units" revision="systemd"/> package as the
353 <systemitem class="username">root</systemitem> user:
354 </para>
355
356 <indexterm zone="TEMPLATE TEMPLATE-init">
357 <primary sortas="f-TEMPLATE">TEMPLATE</primary>
358 </indexterm>
359
360<screen role="root"><userinput>make install-TEMPLATE</userinput></screen>
361 </sect3>
362 </sect2>
363
364 <!--Required section-->
365 <sect2 role="content">
366 <title>Contents</title>
367
368 <segmentedlist>
369 <segtitle>Installed Program(s)</segtitle>
370 <segtitle>Installed Librar(y,ies)</segtitle>
371 <segtitle>Installed Director(y,ies)</segtitle>
372
373 <!-- If there were no programs, libraries, or directories created, then
374 we would list the section as "None". However, a decision must have
375 been made to change the "None" to just removing the whole section
376 because I've noticed that many packages have had the "None"
377 removed and the section completely removed as well. The reasoning
378 was that by putting "None", it appears as we know there are none.
379 Without anything it appears as we are not sure. -->
380
381 <seglistitem>
382 <seg>
383 PROGRAM1, PROGRAM2 and PROGRAM3<!-- no period here since it is not
384 a sentence -->
385 </seg>
386 <seg>
387 libLIBRARY1.so, libLIBRARY2.so and libLIBRARY3.so<!-- no period here
388 since it is not a sentence -->
389 </seg>
390 <seg>
391 /etc/TEMPLATE, /usr/include/TEMPLATE, /usr/lib/TEMPLATE,
392 /usr/share/TEMPLATE-&TEMPLATE-version;,
393 /usr/share/doc/TEMPLATE-&TEMPLATE-version; and
394 /var/lib/TEMPLATE<!-- no period here
395 since it is not a sentence -->
396 </seg>
397 </seglistitem>
398 </segmentedlist>
399
400 <variablelist>
401 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
402 <?dbfo list-presentation="list"?>
403 <?dbhtml list-presentation="table"?>
404
405 <!-- If the program or library name conflicts (is the same) as the
406 package name, add -prog or -lib to the varlistentry entity id
407 and the 2nd entry of the indexterm zone entity -->
408
409 <varlistentry id="PROGRAM1">
410 <term><command>PROGRAM1</command></term>
411 <listitem>
412 <para>
413 does this ..... (no period at the end)
414 </para>
415 <indexterm zone="TEMPLATE PROGRAM1">
416 <primary sortas="b-PROGRAM1">PROGRAM1</primary>
417 </indexterm>
418 </listitem>
419 </varlistentry>
420
421 <varlistentry id="PROGRAM2">
422 <term><command>PROGRAM2</command></term>
423 <listitem>
424 <para>
425 does this ..... (no period at the end)
426 </para>
427 <indexterm zone="TEMPLATE PROGRAM2">
428 <primary sortas="b-PROGRAM2">PROGRAM2</primary>
429 </indexterm>
430 </listitem>
431 </varlistentry>
432
433 <varlistentry id="libLIBRARY1">
434 <term><filename class="libraryfile">libLIBRARY1.so</filename></term>
435 <listitem>
436 <para>
437 contains functions that ..... (no period at the end)
438 </para>
439 <indexterm zone="TEMPLATE libLIBRARY1">
440 <primary sortas="c-libLIBRARY1">libLIBRARY1.so</primary>
441 </indexterm>
442 </listitem>
443 </varlistentry>
444 </variablelist>
445 </sect2>
446</sect1>
Note: See TracBrowser for help on using the repository browser.