source: template/template.xml@ 7a65888

10.0 10.1 11.0 8.2 8.3 8.4 9.0 9.1 basic bdubbs/svn elogind ken/refactor-virt lazarus perl-modules qt5new trunk xry111/git-date xry111/git-date-for-trunk xry111/git-date-test
Last change on this file since 7a65888 was 7a65888, checked in by Pierre Labastie <pieere@…>, 4 years ago

Add recommendations for runtime dependencies and for referring to packages,
which are not dependencies, in template

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/trunk/BOOK@19206 af4574ff-66df-0310-9fd7-8a98e5e911e0

  • Property mode set to 100644
File size: 13.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 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 you commit, IFF you set the properties:
32 first, svn add path/to/thisfile.xml and then
33 svn propset svn:mime-type text/plain path/to/thisfile.xml and
34 svn propset svn:keywords "Date LastChangedBy" path/to/thisfile.xml -->
35 <othername>$LastChangedBy$</othername>
36 <date>$Date$</date>
37 </sect1info>
38
39 <!-- No other tags inside any title.
40 Use Title Case in All Titles -->
41 <title>TEMPLATE-&TEMPLATE-version;</title>
42
43 <indexterm zone="TEMPLATE">
44 <primary sortas="a-TEMPLATE">TEMPLATE</primary>
45 </indexterm>
46
47 <!--Required section-->
48 <sect2 role="package">
49 <title>Introduction to TEMPLATE</title>
50
51 <para>
52 The <application>TEMPLATE</application> package contains...
53 This is useful for...
54 </para>
55
56 <!-- if it builds but hasn't been tested: -->
57 &lfs8?_built;
58 <!-- if it works: -->
59 &lfs8?_checked;
60
61 <bridgehead renderas="sect3">Package Information</bridgehead>
62 <itemizedlist spacing="compact">
63 <listitem>
64 <para>
65 Download (HTTP): <ulink url="&TEMPLATE-download-http;"/>
66 </para>
67 </listitem>
68 <listitem>
69 <para>
70 Download (FTP): <ulink url="&TEMPLATE-download-ftp;"/>
71 </para>
72 </listitem>
73 <listitem>
74 <para>
75 Download MD5 sum: &TEMPLATE-md5sum;
76 </para>
77 </listitem>
78 <listitem>
79 <para>
80 Download size: &TEMPLATE-size;
81 </para>
82 </listitem>
83 <listitem>
84 <para>
85 Estimated disk space required: &TEMPLATE-buildsize;
86 </para>
87 </listitem>
88 <listitem>
89 <para>
90 Estimated build time: &TEMPLATE-time;
91 </para>
92 </listitem>
93 </itemizedlist>
94
95 <!-- As required -->
96 <bridgehead renderas="sect3">Additional Downloads</bridgehead>
97 <itemizedlist spacing="compact">
98 <listitem>
99 <para>
100 Required patch:
101 <ulink url="&patch-root;/TEMPLATE-&TEMPLATE-version;-patch_name-patch_version.patch"/>
102 </para>
103 </listitem>
104 </itemizedlist>
105
106 <bridgehead renderas="sect3">TEMPLATE Dependencies</bridgehead>
107
108 <bridgehead renderas="sect4">Required</bridgehead>
109 <para role="required">
110 <xref linkend="BLFS_DEPENDENCY"/> <!-- notice no period as this is not
111 a sentence. If there are more than two, they must be separated by commas
112 with the last member having "and" in front of it. The use of a serial
113 comma is preferred (a comma after the next to last member before the
114 "and"). BLFS_DEPENDENCY should be an "id" attribute defined somewhere
115 in the book (usually in a <sect1>). -->
116 <xref role="runtime" linkend="RUNTIME_DEPENDENCY"/> (runtime)
117 <!-- Specifying that a dependency is a runtime one, may avoid circular
118 dependencies. Add role="runtime" to help jhalfs -->
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 <xref> before <ulink>.-->
141 <!-- See above how to refer to another package, which is not a
142 dependency. -->
143 </para>
144
145 <para condition="html" role="usernotes">
146 User Notes: <ulink url="&blfs-wiki;/TEMPLATE"/>
147 </para>
148 </sect2>
149
150 <!-- Optional section for packages that need a specific kernel
151 configuration-->
152 <sect2 role="kernel" id="TEMPLATE-kernel">
153 <title>Kernel Configuration</title>
154
155 <para>
156 Enable the following options in the kernel configuration and recompile the
157 kernel if necessary:
158 </para>
159
160<!-- Spaces are significant in <screen> sections -->
161<screen><literal>Master section ---&gt;
162 Subsection ---&gt;
163 [*] Required parameter [CONFIG_REQU_PAR]
164 &lt;*&gt; Required parameter (not as module) [CONFIG_REQU_PAR_NMOD]
165 &lt;*/M&gt; Required parameter (could be a module) [CONFIG_REQU_PAR_MOD]
166 &lt;*/M/ &gt; Optional parameter [CONFIG_OPT_PAR]
167 [ ] Incompatible parameter [CONFIG_INCOMP_PAR]
168 &lt; &gt; Incompatible parameter (even as module) [CONFIG_INCOMP_PAR_MOD]</literal></screen>
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 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 section. Use one of the two mentions below about a test
195 suite, delete the line that is not applicable. Of course, if the
196 test suite uses syntax other than 'make check', revise the
197 line to reflect the actual syntax to run the test suite -->
198
199 <para>
200 This package does not come with a test suite.
201 </para>
202
203 <para>
204 To test the results, issue: <command>make check</command>.
205 </para>
206
207 <para>
208 Now, as the <systemitem class="username">root</systemitem> user:
209 </para>
210
211<screen role="root"><userinput>make install</userinput></screen>
212 </sect2>
213
214 <!--Optional section-->
215 <sect2 role="commands">
216 <title>Command Explanations</title>
217
218 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
219 href="../../xincludes/static-libraries.xml"/>
220
221 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
222 href="../../xincludes/gtk-doc-rebuild.xml"/>
223
224 <para>
225 <command>COMMAND</command>: This command does something.
226 </para>
227
228 <para>
229 <parameter>--PARAMETER</parameter>: This parameter does something
230 mandatory for BLFS purposes. It will be in the instructions above. It is
231 not optional and is why it is listed as a parameter and not an option.
232 </para>
233
234 <para>
235 <option>--OPTION</option>: This option does something optionally per the
236 user's desires. It is not listed in the instructions above, but instead,
237 is listed here because many (some) readers may want to include it.
238 </para>
239 </sect2>
240
241 <sect2 role="using">
242 <title>Using TEMPLATE</title>
243
244 <para>
245 Stuff about how to use TEMPLATE to do something. This section is rarely
246 used.
247 </para>
248 </sect2>
249
250 <!--Optional section-->
251 <sect2 role="configuration">
252 <title>Configuring TEMPLATE</title>
253
254 <sect3 id="TEMPLATE-config">
255 <title>Config Files</title>
256 <para>
257 <filename>~/.Configfilename1</filename> and
258 <filename>/etc/path/Configfilename2</filename> <!-- notice no period as this is not a sentence-->
259 </para>
260
261 <indexterm zone="TEMPLATE TEMPLATE-config">
262 <primary sortas="e-AA.Configfilename1">~/.Configfilename1</primary>
263 </indexterm>
264
265 <indexterm zone="TEMPLATE TEMPLATE-config">
266 <primary
267 sortas="e-etc-path-Configfilename2">/etc/path/Configfilename2</primary>
268 </indexterm>
269 </sect3>
270
271 <sect3><title>Configuration Information</title>
272
273 <para>
274 Blah blah blah about config.
275 </para>
276
277<screen><userinput>USER CONFIG COMMANDS</userinput></screen>
278
279<screen role="root"><userinput>ROOT CONFIG COMMANDS</userinput></screen>
280
281 <!-- File creation. Add the appropriate <indexterm> block if needed.-->
282 <para>
283 Create the file .... for ...
284 </para>
285
286<screen role="root"><userinput>cat &gt;&gt; /PATH/FILENAME &lt;&lt; "EOF"
287<literal># Begin FILENAME
288
289TEXT
290
291# End FILENAME</literal>
292EOF</userinput></screen>
293 </sect3>
294
295 <sect3 id="TEMPLATE-init">
296 <title>Boot Script</title>
297
298 <para>
299 To automatically start the <command>TEMPLATE</command> daemon when the
300 system is rebooted, install the
301 <filename>/etc/rc.d/init.d/TEMPLATE</filename> bootscript from the
302 <xref linkend="bootscripts" revision="sysv"/>
303 <xref linkend="systemd-units" revision="systemd"/> package as the
304 <systemitem class="username">root</systemitem> user:
305 </para>
306
307 <indexterm zone="TEMPLATE TEMPLATE-init">
308 <primary sortas="f-TEMPLATE">TEMPLATE</primary>
309 </indexterm>
310
311<screen role="root"><userinput>make install-TEMPLATE</userinput></screen>
312 </sect3>
313 </sect2>
314
315 <!--Required section-->
316 <sect2 role="content">
317 <title>Contents</title>
318
319 <segmentedlist>
320 <segtitle>Installed Program(s)</segtitle>
321 <segtitle>Installed Librar(y,ies)</segtitle>
322 <segtitle>Installed Director(y,ies)</segtitle>
323
324 <!-- If there were no programs, libraries, or directories created, then
325 we would list the section as "None". However, a decision must have
326 been made to change the "None" to just removing the whole section
327 because I've noticed that many packages have had the "None"
328 removed and the section completely removed as well. The reasoning
329 was that by putting "None", it appears as we know there are none.
330 Without anything it appears as we are not sure. -->
331
332 <seglistitem>
333 <seg>
334 PROGRAM1, PROGRAM2 and PROGRAM3.
335 </seg>
336 <seg>
337 libLIBRARY1.so, libLIBRARY2.so and libLIBRARY3.so.
338 </seg>
339 <seg>
340 /etc/TEMPLATE, /usr/include/TEMPLATE, /usr/lib/TEMPLATE,
341 /usr/share/TEMPLATE-&TEMPLATE-version;,
342 /usr/share/doc/TEMPLATE-&TEMPLATE-version; and
343 /var/lib/TEMPLATE.
344 </seg>
345 </seglistitem>
346 </segmentedlist>
347
348 <variablelist>
349 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
350 <?dbfo list-presentation="list"?>
351 <?dbhtml list-presentation="table"?>
352
353 <!-- If the program or library name conflicts (is the same) as the
354 package name, add -prog or -lib to the varlistentry entity id
355 and the 2nd entry of the indexterm zone entity -->
356
357 <varlistentry id="PROGRAM1">
358 <term><command>PROGRAM1</command></term>
359 <listitem>
360 <para>
361 does this ..... (end the sentence with a period).
362 </para>
363 <indexterm zone="TEMPLATE PROGRAM1">
364 <primary sortas="b-PROGRAM1">PROGRAM1</primary>
365 </indexterm>
366 </listitem>
367 </varlistentry>
368
369 <varlistentry id="PROGRAM2">
370 <term><command>PROGRAM2</command></term>
371 <listitem>
372 <para>
373 does this ..... (end the sentence with a period).
374 </para>
375 <indexterm zone="TEMPLATE PROGRAM2">
376 <primary sortas="b-PROGRAM2">PROGRAM2</primary>
377 </indexterm>
378 </listitem>
379 </varlistentry>
380
381 <varlistentry id="libLIBRARY1">
382 <term><filename class="libraryfile">libLIBRARY1.so</filename></term>
383 <listitem>
384 <para>
385 contains functions that ..... (end the sentence with a period).
386 </para>
387 <indexterm zone="TEMPLATE libLIBRARY1">
388 <primary sortas="c-libLIBRARY1">libLIBRARY1.so</primary>
389 </indexterm>
390 </listitem>
391 </varlistentry>
392 </variablelist>
393 </sect2>
394</sect1>
Note: See TracBrowser for help on using the repository browser.