Open Stack

You can annotate any file by using this tagging: (this example includes the xml_curl.txt file, and provides callouts for various lines – see screenshot at the end of this note)


 <example xml:id="xml_example">
        <title>cURL Command Example: XML Request and Response</title>
        <programlistingco>
            <areaspec>
                <area xml:id="xml_curl.txt.endpoint"
                    units="linecolumn" coords="1 87"/>
                <area xml:id="xml_curl.txt.content" units="linecolumn"
                    coords="4 46"/>
                <area xml:id="xml_curl.txt.accept" units="linecolumn"
                    coords="5 40"/>
                <area xml:id="xml_curl.txt.file" units="linecolumn"
                    coords="7 29"/>
                <area xml:id="xml_curl.txt.ppxml" units="linecolumn"
                    coords="7 40"/>
            </areaspec>
            <programlisting language="bash" role="gutter: false"><?db-font-size 65%?><prompt>$</prompt> <xi:include href="../samples/xml_curl.txt" parse="text"/></programlisting>
        </programlistingco>
    </example>
    <para>The example, <xref linkend="xml_example"/>, includes the
        following changes:<calloutlist>
            <callout arearefs="xml_curl.txt.endpoint">
                <para>Append <literal>.xml</literal> to the endpoint
                    in the cURL command to return an XML
                    response.</para>
            </callout>
            <callout arearefs="xml_curl.txt.content">
                <para>The <literal>Content-Type:</literal> header
                    specifies <literal>application/xml</literal>
                    instead of <literal>application/json</literal>.
                </para>
            </callout>
            <callout arearefs="xml_curl.txt.accept">
                <para>The <literal>Accept:</literal> header specifies
                        <literal>application/xml</literal> instead of
                        <literal>application/json</literal>. </para>
            </callout>
            <callout arearefs="xml_curl.txt.file">
                <para>If the request requires a request body, specify
                    it in XML format. In this example, the XML body is
                    passed in the
                        <filename>server_post_req.xml</filename>
                    file.</para>
            </callout>
            <callout arearefs="xml_curl.txt.ppxml">
                <para>To pretty-print the XML output, set the <literal
                        xmlns:svg="http://www.w3.org/2000/svg"
                        xmlns:m="http://www.w3.org/1998/Math/MathML"
                        xmlns:html="http://www.w3.org/1999/xhtml"
                        xmlns:db="http://docbook.org/ns/docbook"
                        >ppxml</literal> alias, as follows: </para>
                <programlisting language="bash" role="gutter: false"><?db-font-size 50%?><prompt>$</prompt> alias ppxml='python -c "import sys, xml.dom.minidom; print xml.dom.minidom.parseString(sys.stdin.read()).toprettyxml()"'</programlisting>
                <para xmlns:svg="http://www.w3.org/2000/svg"
                    xmlns:m="http://www.w3.org/1998/Math/MathML"
                    xmlns:html="http://www.w3.org/1999/xhtml"
                    xmlns:db="http://docbook.org/ns/docbook">Then,
                    append the <literal>ppxml</literal> alias to your
                    cURL command. </para>
            </callout>
        </calloutlist></para>



[cid:BCBB9E80-38AF-4615-9FEA-18978840CE21]

Diane
----------------------------------------------
Diane Fleming
Software Developer II - US
diane.fleming at rackspace.com
Cell  512.323.6799
Office 512.874.1260
Skype drfleming0227
Google-plus diane.fleming at gmail.com

From: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>>
Date: Wednesday, February 26, 2014 1:08 PM
To: Andreas Jaeger <aj at suse.com<mailto:aj at suse.com>>
Cc: "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>>
Subject: Re: [Openstack-docs] Checking JSON/XML errors on docs.openstack.org




On Wed, Feb 26, 2014 at 12:55 PM, Andreas Jaeger <aj at suse.com<mailto:aj at suse.com>> wrote:
On 02/26/2014 03:04 PM, Jamie Hannaford wrote:
> [...]
> Following this, I've also written a script that checks every single
> piece of documentation on openstack.org<http://openstack.org> for malformed JSON/XML. Whereas
> Andreas checks during the Jenkins build process, my check allows us to
> see any pre-built documentation errors that are currently live.  Doing
> this, I've found 31 errors on the docs.openstack.org<http://docs.openstack.org> sub-domain that
> need to be corrected. The full report is attached.

Great idea! I think you run it before some changes were merged, could
you rerun it and file a bug report with these instructions, please?

I hope somebody will then fix these ;)

Agreed - although one that was identified is policy.json from the Grizzly documents, where we use annotation inline like [1] [2] [3] which then makes the json invalid. So in fixing that, we need to figure out how to annotate the policy.json file -- any ideas?

Thanks for the work here --- what a great idea for higher quality docs.

Anne

thanks,
Andreas
--
 Andreas Jaeger aj@{suse.com<http://suse.com>,opensuse.org<http://opensuse.org>} Twitter/Identica: jaegerandi
  SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126

_______________________________________________
Openstack-docs mailing list
Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org>
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140226/90219396/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: BCBB9E80-38AF-4615-9FEA-18978840CE21.png
Type: image/png
Size: 75697 bytes
Desc: BCBB9E80-38AF-4615-9FEA-18978840CE21.png
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140226/90219396/attachment-0001.png>