<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd" [

  <!ENTITY dhfirstname "<firstname>Frank</firstname>">
  <!ENTITY dhsurname   "<surname>Thomas</surname>">
  <!ENTITY dhusername  "Frank S. Thomas">
  <!ENTITY dhemail     "<email>fst@debian.org</email>">
  <!ENTITY dhpackage   "dctrl2xml">
  <!ENTITY dhcommand   "<command>dctrl2xml</command>">
  <!ENTITY dhdate      "<date>20 August 2010</date>">

  <!ENTITY debian      "<productname>Debian</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
]>

<!--
  This is the manual page for dctrl2xml.

  This file is licensed under the terms of the GNU General Public License,
  Version 3 or any later version published by the Free Software Foundation.

  Copyright © 2005, 2007-2008, 2010 Frank S. Thomas <fst@debian.org>
-->

<refentry>
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;  
    </author>
    <copyright>
      <year>2005</year>
      <year>2007</year>
      <year>2008</year>
      <year>2010</year>
      <holder>&dhusername;</holder>
    </copyright>
    &dhdate;
  </refentryinfo>

  <refmeta>
    <refentrytitle>dctrl2xml</refentrytitle>
    <manvolume>1</manvolume>
  </refmeta>

  <refnamediv>
    <refname>dctrl2xml</refname>
    <refpurpose>Debian control data to XML converter</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      &dhcommand;
      <group>
        <arg>-x</arg>
        <arg>-j</arg>
      </group>
      <group>
        <arg>-f <replaceable>FILE</replaceable></arg>
      </group>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>
    <para>&dhcommand; is a tool that converts Debian control data into an XML
      representation. It can be used to convert data which is normally found
      in debian/control, .changes, .dsc, Packages, Sources, and similar files
      to XML. </para>
    <para>For most fields &dhcommand; just uses the field name as element name
      and the field data as element content. For other fields, such as package
      interrelationship fields (Depends, Build-Depends, etc.) or the Files
      field in .changes or Sources files, &dhcommand; additionally parses
      their field data to represent it in a more fine-structured form.</para>
  </refsect1>

  <refsect1>
    <title>OPTIONS</title>
    <para>For a full summary of options, run &dhcommand;
      <option>--help</option>.</para>

    <variablelist>
      <varlistentry>
        <term><option>--version</option></term>
        <listitem>
          <para>Show dctrl2xml's version number.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-h</option>, <option>--help</option></term>
        <listitem>
          <para>Show help about options.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-f <replaceable>FILE</replaceable></option>,
          <option>--file=<replaceable>FILE</replaceable></option></term>
        <listitem>
          <para>Read Debian control data from file
            <replaceable>FILE</replaceable> instead of standard input.
            <replaceable>FILE</replaceable> can be either a plain text file or
            a gzip, bzip2 or ZIP file.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-x</option>, <option>--xml</option></term>
        <listitem>
          <para>Output Debian control data as XML (default).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-j</option>, <option>--json</option></term>
        <listitem>
          <para>Output Debian control data as JSON.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>EXAMPLES</title>
    <variablelist>
      <varlistentry>
        <term>
          <userinput>dctrl2xml -f /var/lib/dpkg/available</userinput>
        </term>
        <listitem>
          <para>Convert the whole 
            <citerefentry>
              <refentrytitle>dpkg</refentrytitle>
              <manvolnum>1</manvolnum>
            </citerefentry> available file to XML and print it to standard
            output. This is a typical stress test for &dhcommand;.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <userinput>apt-cache show hello build-essential |
            dctrl2xml</userinput>
        </term>
        <listitem>
          <para>Convert the package records of the hello and build-essential
            packages to XML and print it to standard output. This is an
            example of how &dhcommand; can be used in pipes where it reads the
            control data from standard input.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <userinput>apt-cache showsrc hello | dctrl2xml | xmllint
            --format -</userinput>
        </term>
        <listitem>
          <para>This is similar to the above example, except that the
            <citerefentry>
              <refentrytitle>xmllint</refentrytitle>
              <manvolnum>1</manvolnum>
            </citerefentry> tool (which is in the libxml2-utils Debian
            package) is used to reformat and reindent &dhcommand;'s output to
            make it more human readable and that the source package records of
            the hello package are used.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <userinput>apt-cache showsrc hello | dctrl2xml -j</userinput>
        </term>
        <listitem>
          <para>In this example hello's source package record is printed as
            JSON instead of XML.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>deb-control</refentrytitle>
        <manvolnum>5</manvolnum>
      </citerefentry>
      <!--
        http://lists.debian.org/debian-mentors/2005/01/msg00058.html
        http://lists.debian.org/debian-mentors/2006/09/msg00089.html
      -->
    </para>
  </refsect1>

  <refsect1>
    <title>AUTHOR</title>
    <para>Written by &dhusername; &dhemail;.</para>
  </refsect1>

</refentry>
