source: template/template.xml@ bbcb12d

12.0 12.1 ken/TL2024 ken/tuningfonts lazarus plabs/newcss python3.11 rahul/power-profiles-daemon renodr/vulkan-addition trunk xry111/llvm18
Last change on this file since bbcb12d was a1bb0d9, checked in by Xi Ruoyao <xry111@…>, 12 months ago

template: Modify "User Notes" to "Editor Notes" and comment it out
  • Property mode set to 100644
File size: 15.1 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 nearer integer if greater than 10, to one
18 decimal if less than 10, and should be "less than 0.1 SBU" if
19 less than 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 systems
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
31 <!-- No other tags inside any title.
32 Use Title Case in All Titles
33 (i.e., Capitalize Everything
34 *Except* Articles, Short Prepositions,
35 and Coordinating Conjunctions.-->
36 <title>TEMPLATE-&TEMPLATE-version;</title>
37
38 <indexterm zone="TEMPLATE">
39 <primary sortas="a-TEMPLATE">TEMPLATE</primary>
40 </indexterm>
41
42 <!--Required section-->
43 <sect2 role="package">
44 <title>Introduction to TEMPLATE</title>
45
46 <para>
47 The <application>TEMPLATE</application> package contains...
48 This is useful for...
49 </para>
50
51 <!-- if it builds but hasn't been tested: -->
52 &lfs1?_built;
53 <!-- if it works: -->
54 &lfs1?_checked;
55
56 <bridgehead renderas="sect3">Package Information</bridgehead>
57 <itemizedlist spacing="compact">
58 <listitem>
59 <para>
60 Download (HTTP): <ulink url="&TEMPLATE-download-http;"/>
61 </para>
62 </listitem>
63 <listitem>
64 <para>
65 Download (FTP): <ulink url="&TEMPLATE-download-ftp;"/>
66 </para>
67 </listitem>
68 <listitem>
69 <para>
70 Download MD5 sum: &TEMPLATE-md5sum;
71 </para>
72 </listitem>
73 <listitem>
74 <para>
75 Download size: &TEMPLATE-size;
76 </para>
77 </listitem>
78 <listitem>
79 <para>
80 Estimated disk space required: &TEMPLATE-buildsize;
81 </para>
82 </listitem>
83 <listitem>
84 <para>
85 Estimated build time: &TEMPLATE-time;
86 </para>
87 </listitem>
88 </itemizedlist>
89
90 <!-- As required -->
91 <bridgehead renderas="sect3">Additional Downloads</bridgehead>
92 <itemizedlist spacing="compact">
93 <listitem>
94 <para>
95 Required patch:
96 <ulink url="&patch-root;/TEMPLATE-&TEMPLATE-version;-patch_name-patch_version.patch"/>
97 </para>
98 </listitem>
99 </itemizedlist>
100
101 <bridgehead renderas="sect3">TEMPLATE Dependencies</bridgehead>
102
103 <bridgehead renderas="sect4">Required</bridgehead>
104 <para role="required">
105 <xref linkend="BLFS_DEPENDENCY"/> <!-- notice no period as this is not
106 a sentence. If there are more than two, they must be separated by commas
107 with the last member having "and" in front of it. The use of a serial
108 comma is preferred (a comma after the next to last member before the
109 "and"). BLFS_DEPENDENCY should be an "id" attribute defined somewhere
110 in the book (usually in a <sect1>). -->
111 <xref role="runtime" linkend="RUNTIME_DEPENDENCY"/> (runtime)
112 <!-- Specifying that a dependency is a runtime one may avoid circular
113 dependencies. Add role="runtime" to help jhalfs -->
114 </para>
115
116 <!-- It may be nice to have a separate section for runtime dependencies.
117 Do it as follows. -->
118 <bridgehead renderas="sect4">Required at runtime</bridgehead>
119 <para role="required">
120 <xref role="runtime" linkend="RUNTIME_DEPENDENCY"/>
121 </para>
122
123 <!-- As required -->
124 <bridgehead renderas="sect4">Recommended</bridgehead>
125 <para role="recommended">
126 <xref linkend="BLFS_DEPENDENCY"/> <!-- notice no period as this is not
127 a sentence. See above for the use of "and" and commas. Normally, neither
128 required nor recommended dependencies should be <ulink>. -->
129 <xref linkend="ANOTHER_RECOMMENDED_DEP"/> (required if building
130 <xref role="nodep" linkend="SOME_FANCY_PACKAGE"/>) <!-- You may need
131 to refer to another package, which is not a dependency. Use the role
132 attibute with value "nodep". -->
133 <!-- See above for runtime dependencies -->
134 </para>
135
136 <!-- As required -->
137 <bridgehead renderas="sect4">Optional</bridgehead>
138 <para role="optional">
139 <xref linkend="BLFS_DEPENDENCY"/> and
140 <ulink url="http://www.some.url/">EXTERNAL DEPENDENCY</ulink>
141 <!-- notice no period as this is not a sentence. See above for the use
142 of commas and "and". The order should be <xref> before <ulink>.-->
143 <!-- See above for references to another package which is not a
144 dependency. -->
145 </para>
146
147 <!-- Only use this if you want to note something in the wiki
148 <para condition="html" role="usernotes">
149 Editor Notes: <ulink url="&blfs-wiki;/TEMPLATE"/>
150 </para>
151 -->
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 configuration 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 that 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 <!-- Optional paragraph. Use one of the two formats below about the test
214 suite; delete the line that is not applicable. Of course, if the
215 test suite uses syntax other than 'make check', revise the
216 line to reflect the actual syntax to run the test suite -->
217
218 <para>
219 This package does not come with a test suite.
220 </para>
221
222 <para>
223 To test the results, issue: <command>make check</command>.
224 </para>
225
226 <!-- Sometimes, more complex instructions are needed for running tests, or
227 they need to be run as root. They can then be put inside screen
228 tags using the remap="test" attribute as in the following example: -->
229
230 <para>
231 If you want to run the tests, first create some needed files:
232 </para>
233
234<screen remap="test"><userinput>make prepare-tests</userinput></screen>
235
236 <para>
237 Then run the tests as the <systemitem class="username">root</systemitem>
238 user:
239 </para>
240
241<screen role="root" remap="test"><userinput>make tests</userinput></screen>
242
243 <para>
244 Now, as the <systemitem class="username">root</systemitem> user:
245 </para>
246
247<screen role="root"><userinput>make install</userinput></screen>
248
249 <!-- Optional paragraph for documentation that has been generated using
250 optional/external packages: -->
251
252 <para>
253 If you have built the optional documentation, install it as the
254 <systemitem class="username">root</systemitem> user:
255 </para>
256
257<screen role="root"
258 remap="doc"><userinput>install -vdm 755 /usr/share/doc/template-&template-version; &amp;&amp;
259mv doc/* /usr/share/doc/template-&template-version;</userinput></screen>
260 </sect2>
261
262 <!--Optional section-->
263 <sect2 role="commands">
264 <title>Command Explanations</title>
265
266 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
267 href="../../xincludes/static-libraries.xml"/>
268
269 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
270 href="../../xincludes/gtk-doc-rebuild.xml"/>
271
272 <para>
273 <command>COMMAND</command>: This command does something.
274 </para>
275
276 <para>
277 <parameter>--PARAMETER</parameter>: This parameter does something
278 mandatory for BLFS purposes. It will be in the instructions above. It is
279 not optional and is why it is listed as a parameter and not an option.
280 </para>
281
282 <para>
283 <option>--OPTION</option>: This option does something optionally per the
284 user's desires. It is not listed in the instructions above, but instead,
285 is listed here because many (some) readers may want to include it.
286 </para>
287 </sect2>
288
289 <!--Optional section-->
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 if 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 with (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.