blob: 517739eac7a617d43f90245954618baf7e81351d (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
|
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id: tutorial.xml,v 1.3 2007/06/23 05:24:16 pfrields Exp $ -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!-- *************** Bring in Fedora entities *************** -->
<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "fdp-entities.ent">
%FEDORA-ENTITIES-EN;
]>
<chapter id="ch-tutorial">
<title>The Layout of a Tutorial</title>
<para>In this chapter, you will find an example of a very short tutorial
as used by the &FDP;. This example is specific to the way the Docs
Project uses DocBook XML. The example consists of a set of files
used to hold the content and metadata for the tutorial.</para>
<section id="sn-tutorial-article">
<title>The Article</title>
<indexterm>
<primary>tutorial layout</primary>
<secondary>article</secondary>
</indexterm>
<para>Below is a sample article:</para>
<screen><![CDATA[<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % FEDORA-ENTITIES SYSTEM "fdp-entities.ent">
%FEDORA-ENTITIES;
]>
<article id="sample-tutorial" lang="en_US">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
href="fdp-info.xml"/>
<section id="some-section">
<title>Some Section</title>
<para>
This is an example section. You can nest sections or make
additional sections as needed.
</para>
<warning>
<title>Warning</title>
<para>
Example of an admonition.
</para>
</warning>
</section>
<index id="generated-index"/>
</article>
]]></screen>
</section>
<section id="sn-tutorial-metadata">
<title>The Metadata</title>
<indexterm>
<primary>tutorial layout</primary>
<secondary>metadata</secondary>
</indexterm>
<para>The <filename>rpm-info.xml</filename> file contains all the
required metadata for the document. This metadata includes title,
authorship, licensing, and revision history. <xref
linkend="ex-rpminfo"/> illustrates the content of this
file:</para>
<example id="ex-rpminfo">
<title>Example <filename>rpm-info.xml</filename> File</title>
<programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE rpm-info PUBLIC "-//Fedora//DTD Docs RPM-INFO V1.0//EN"
"http://docs.fedoraproject.org/dtds/rpm-info.dtd">
<rpm-info>
<colophon>
<worker surname="Smith" firstname="John" othername="Q."
id="JohnSmith" email="jsmith@example.com"
wholename="John Q. Smith" initials="JS"/>
</colophon>
<author worker="JohnSmith"/>
<license>
<rights>OPL</rights>
<version>1.0</version>
</license>
<copyright>
<year>2006</year>
<holder>John Q. Smith</holder>
</copyright>
<title>My Tutorial</title>
<desc>A tutorial about something important</desc>
<changelog order="newest-first">
<revision date="2006-06-01" number="0.1" role="doc">
<author worker="JohnSmith"/>
<details>First draft</details>
</revision>
</changelog>
</rpm-info>]]></programlisting>
</example>
<para>If you are not familiar with XML editing, copy and paste this
file from an existing module and then edit the values for the
various elements as appropriate. Consult &FDP; members and help
channels for more assistance if needed.</para>
</section>
</chapter>
|
