source: template/template.xml@ 0d1a1f9

ken/TL2024 trunk
Last change on this file since 0d1a1f9 was 478048f, checked in by Xi Ruoyao <xry111@…>, 7 weeks ago

template: Clean up

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