File: Adding_Code_Samples.xml

package info (click to toggle)
publican 4.3.2-3
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, bullseye, buster
  • size: 18,280 kB
  • sloc: perl: 13,081; xml: 11,558; makefile: 169; sh: 29; python: 29
file content (94 lines) | stat: -rw-r--r-- 4,752 bytes parent folder | download | duplicates (3)
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
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section [
<!ENTITY % BOOK_ENTITIES SYSTEM "Users_Guide.ent">
%BOOK_ENTITIES;
<!ENTITY % sgml.features "IGNORE">
<!ENTITY % xml.features "INCLUDE">
<!ENTITY % DOCBOOK_ENTS PUBLIC "-//OASIS//ENTITIES DocBook Character Entities V4.5//EN" "/usr/share/xml/docbook/schema/dtd/4.5/dbcentx.mod">
%DOCBOOK_ENTS;
]>
<section conformance="117" version="5.0" xml:id="sect-Publican-Users_Guide-Adding_code_samples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
	<info>
		<title>Adding code samples</title>

	</info>
	 <para>
		If your book contains code samples, place them in a directory named <filename>extras/</filename> in your source language directory and use an <tag>&lt;xi:include&gt;</tag> to pull the code file into the XML structure of your document. <application>Publican</application> does not parse any files that it finds in the <filename>extras/</filename> directory as XML.
	</para>
	 <para>
		Certain characters are reserved in XML, in particular, <literal>&amp;</literal> and <literal>&lt;</literal>. If you insert code samples directly into the XML of your document, you must escape these characters, either by marking them as <literal>CDATA</literal> or by replacing them with entities (&amp;amp; and &amp;lt; respectively).<footnote> <para>
			Refer to section 2.4 "Character Data and Markup" in the XML 1.0 standard, available from <uri xlink:href="http://www.w3.org/TR/2008/REC-xml-20081126/" xmlns:xlink="http://www.w3.org/1999/xlink">http://www.w3.org/TR/2008/REC-xml-20081126/</uri>.
		</para>
		 </footnote> If you place these files in the <filename>extras/</filename> directory, you do not need to escape these characters. This approach saves time, reduces the chances of introducing errors into either the document XML or the code itself, and makes future maintenance of the document and the code easier.
	</para>
	 <para>
		To include a code sample from the <filename>extras/</filename> directory in your document, follow this procedure:
	</para>
	 <procedure conformance="118">
		<step>
			<para>
				Create the extras directory
			</para>
			 
<screen><prompt>$</prompt> <command>mkdir <filename>en-US/extras</filename></command></screen>

		</step>
		 <step>
			<para>
				Copy the code file to the extras directory
			</para>
			 
<screen><prompt>$</prompt> <command>cp <filename>~/samples/foo.c en-US/extras/.</filename></command></screen>

		</step>
		 <step>
			<para>
				<tag>xi:include</tag> the sample file in your xml file
			</para>
			 
<programlisting language="XML">&lt;programlisting&gt;
&lt;xi:include parse="text" href="extras/foo.c" xmlns:xi="http://www.w3.org/2001/XInclude" /&gt;
&lt;/programlisting&gt;</programlisting>

		</step>
		 <step>
			<para>
				You can now edit <filename>en-US/extras/foo.c</filename> in your favorite editor without having to be concerned about how it will affect the XML.
			</para>

		</step>

	</procedure>
	 <para>
		The same approach works when you want to annotate your code with callouts. For example:
	</para>
	 
<programlisting language="XML">&lt;programlistingco&gt;
	&lt;areaspec&gt;
		&lt;area id="orbit-for-parameter" coords='4 75'/&gt;
		&lt;area id="orbit-for-magnitude" coords='12 75'/&gt;
	&lt;/areaspec&gt;
	&lt;programlisting language="Fortran"&gt;&lt;xi:include parse="text" href="extras/orbit.for"
	xmlns:xi="http://www.w3.org/2001/XInclude" /&gt;&lt;/programlisting&gt;
	&lt;calloutlist&gt;
		&lt;callout id="callout-for-parameter" arearefs="orbit-for-parameter"&gt;
			&lt;para&gt;
				The &lt;firstterm&gt;standard gravitational parameter&lt;/firstterm&gt;
				(μ) is a derived value, the product of Newton's gravitational 
				constant (G) and the mass of the primary body.
			&lt;/para&gt;
		&lt;/callout&gt;
		&lt;callout id="callout-for-magnitude" arearefs="orbit-for-magnitude"&gt;
			&lt;para&gt;
				Since the mass of the orbiting body is many orders of magnitude 
				smaller than the mass of the primary body, the mass of the 
				orbiting body is ignored in this calculation.
			&lt;/para&gt;
		&lt;/callout&gt;
	&lt;/calloutlist&gt;
&lt;/programlistingco&gt;</programlisting>
	 <para>
		Note the <tag>&lt;area&gt;</tag> elements that define the position of the callouts that will appear on the code sample. The <literal>coords</literal> attributes specify a line number and a column number separated by a space. In this example, callouts are applied to lines 4 and 12 of the code, lined up with each other in column 75. Although this approach means that you might have to adjust <literal>coords</literal> attributes if you ever modify the code to which they apply, it avoids mixing XML <tag>&lt;coords&gt;</tag> tags into the code itself.
	</para>
</section>