source: template/template.xml

trunk
Last change on this file was ce30867, checked in by Bruce Dubbs <bdubbs@…>, 8 days ago

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