Are there recommended formal ways of documenting the formats of XML
files?  I don't just mean a validating schema, but something that
would let human understand how to compose the files?
-- 
Canadian Mind Products, Roedy Green.
http://mindprod.com Java custom programming, consulting and coaching.

Roedy Green <my_email_is_posted_on_my_website@munged.invalid> writes:
>Are there recommended formal ways of documenting the formats of XML
>files?  I don't just mean a validating schema, but something that
>would let human understand how to compose the files?

  A question on XML would be on-topic in comp.text.xml.

  For an example of a specification of an XML application, see:

http://www.w3.org/TR/xhtml2/

"Stefan Ram" <ram@zedat.fu-berlin.de> wrote in message 
news:XML-20060420221758@ram.dialup.fu-berlin.de...
> Roedy Green <my_email_is_posted_on_my_website@munged.invalid> writes:
>>Are there recommended formal ways of documenting the formats of XML
>>files?  I don't just mean a validating schema, but something that
>>would let human understand how to compose the files?
>
[...]
>
>  For an example of a specification of an XML application, see:
>
> http://www.w3.org/TR/xhtml2/

    He asked for something that a *HUMAN* could understand. =P

    Seriously though, whenever I've encountered good documentation for XML 
file formats, they were usually in one of twoforms:

    (1) a XSD schema with <!-- embedded comments --> describing each element 
declaration and what they would be used for.
    (2) an adhoc, plain text (or HTML) file describing each element and what 
they would be used for.

    - Oliver 

> Are there recommended formal ways of documenting the formats of XML
> files?  I don't just mean a validating schema, but something that
> would let human understand how to compose the files?

One way is to use a style sheet to format as a treeview the XML data.

http://www.rgagnon.com/javadetails/java-0451.html

You see a sample at : http://www.rgagnon.com/examples/web2.xml
if your browser supports XML/XSL transformation (IE do, Netscape or FIrefox 
don't).

Bye.
-- 
Real Gagnon  from  Quebec, Canada
* Looking for Java or PB code examples ? Visit Real's How-to  
* http://www.rgagnon.com/howto.html

On Thu, 20 Apr 2006 20:14:23 GMT, Roedy Green
<my_email_is_posted_on_my_website@munged.invalid> wrote:

>Are there recommended formal ways of documenting the formats of XML
>files?  I don't just mean a validating schema, but something that
>would let human understand how to compose the files?

What's a "format" ? Just a Schema, structure and data typing?  Or
something more, heading towards an ontology?   You'll be using XML
Schema and possibly OWL too. Both of these have reasonable scope for
annotation metadata. Typically a simple XSLT stylesheet is used to
present these in a more human-friendly form.

You can also look at smart editors for these formats. Protege from
stanford.edu is well worth a look at it   (also read the "ontology 101"
paper and the "Protege pizza tutorial" from Manchester)

On Thu, 20 Apr 2006 21:33:25 GMT, "Oliver Wong" <owong@castortech.com>
wrote:
>    Seriously though, whenever I've encountered good documentation for XML 
>file formats, they were usually in one of twoforms:
>
>    (1) a XSD schema with <!-- embedded comments --> describing each element 
>declaration and what they would be used for.
>    (2) an adhoc, plain text (or HTML) file describing each element and what 
>they would be used for.

I second that.
And the most convenient way to view XSD schema I found is to open it
in XMLSpy and use its Schema/WSDL graphic view. Makes good prints as
well.

                Domchi