README
1NAME
2 Pod::XML - Module to convert POD to XML
3
4SYNOPSIS
5 use Pod::XML;
6 my $parser = Pod::XML->new();
7 $parser->parse_from_file("foo.pod");
8
9DESCRIPTION
10 This module uses Pod::Parser to parse POD and generates XML from
11 the resulting parse stream. It uses its own format, described
12 below.
13
14XML FORMAT
15 The XML format is not a standardised format - if you wish to
16 generate some standard XML format such as docbook, please use a
17 tool such as XSLT to convert between this and that format.
18
19 The format uses the namespace
20 "http://axkit.org/ns/2000/pod2xml". Do not try and request this
21 URI - it is virtual. You will get a 404.
22
23 The best way to describe the format is to show you:
24
25 <pod xmlns="http://axkit.org/ns/2000/pod2xml">
26 <head>
27 <title>The first =head1 goes in here</title>
28 </head>
29 <sect1>
30 <title>Subsequent =head1's create a sect1</title>
31 <para>
32 Ordinary paragraphs of text create a para tag.
33 </para>
34 <verbatim>
35 Indented verbatim sections go in verbatim tags.
36 </verbatim>
37 <sect2>
38 <title>=head2's go in sect2</title>
39 <para>
40 Up to =head4 is supported (despite not really being
41 supported by pod), producing sect3 and
42 sect4 respectively for =head3 and =head4.
43 </para>
44 <para>
45 Bold text goes in a <strong>strong</strong> tag.
46 </para>
47 <para>
48 Italic text goes in a <emphasis>emphasis</emphasis> tag.
49 </para>
50 <para>
51 Code goes in a <code>code</code> tag.
52 </para>
53 <para>
54 Lists (=over, =item, =back) go in list/item/itemtext
55 tags. The itemtext element is only present if the
56 =item text is <strong>not</strong> the "*" character.
57 </para>
58 </sect2>
59 </sect1>
60 </pod>
61
62 If the first =head1 is "NAME" (like standard perl modules are
63 supposed to be) it takes the next paragraph as the document
64 title. Other standard head elements of POD are left unchanged
65 (particularly, the SYNOPSIS and DESCRIPTION elements of standard
66 POD).
67
68 Pod::XML tries to be careful about nesting sect's based on the
69 head level in the original POD. Let me know if this doesn't work
70 for you.
71
72AUTHOR
73 Matt Sergeant, matt@sergeant.org
74
75SEE ALSO
76 Pod::Parser
77
78BUGS
79 There is no xml2pod.
80
81LICENSE
82 This is free software, you may use it and distribute it under
83 the same terms as Perl itself.
84
85