[oXygen-user] Schema documentation from specific root element

[Mark Baker]

I think it should be noted that there is a big difference between schema
documentation and doctype documentation.

* A schema may define 0, 1, or many root elements, and therefore 0, 1, or
many document types. Multiple document types defined by the same schema may
have nothing in common with each other.

* A document type may contain elements defined in one or more schemas, and
even allow content that is not governed by any schema. For instance, a
particular document type may allow the use of MathML or SVG within the
document. The documentation of any one schema, therefore, would not
constitute documentation for the entire document type.

* A document type may reuse a complex type defined in a schema at different
points in a document type while assigning substantially different document
semantics to that type in each of the locations in which it is used.

Schema documentation tools necessarily follow the structure of schemas. They
describe the structure of the schemas themselves, but the structures of the
document types defined by the schemas may be much more complex and varied
than the structures of the schemas themselves (or vice versa -- a complex
schema may define a simple document type). Generating schema documentation
from one root element of a schema, therefore, is not at all equivalent to
creating document type documentation for documents that have that root
element.

We produce a lot of document type references. We have two different document
type reference composition and build processes for different types of
document. (Data oriented document types and text oriented document types are
significantly different in their documentation needs.) Schema documentation,
generated by standard schema documentation tools, as good as some of them
are, would not come close to meeting our user's needs. 

I think you may need to figure out if what you really need is document type
documentation, rather than schema documentation. If so, you will need a
different process to create it.

Mark

> -----Original Message-----
> From:  
> [mailto:] On Behalf Of Ingo Freitag
> Sent: May 20, 2010 12:07 PM
> To: 
> Subject: Re: [oXygen-user] Schema documentation from specific 
> root element
> 
> Hi,
> 
> thank you for your quick answer.
> 
> The best solution would be something complete automatic, but 
> it is also possible, that I remove the other root elements before.
> 
> But one problem is, that the schema uses global types (simple 
> and complex) very intensive, which means for me to manually 
> remove all those elements as well.
> This is a huge work. 
> 
> I already read in former posts, that you were asked to add a 
> function to 'clean' a schema from unused types and other elements.
> In my case such a function would do the trick very well :) So 
> my vote to implement it as soon as possible.
> 
> Best regards,
> 
> Ingo
> 
> -----Original Message-----
> From: Adrian Buza [mailto:]
> Sent: Thursday, May 20, 2010 10:47 AM
> To: Ingo Freitag
> Cc: 
> Subject: Re: [oXygen-user] Schema documentation from specific 
> root element
> 
> Hello,
> 
> The schema documentation tool is not contextual, it generates 
> the documentation for the entire schema so I'm afraid you 
> cannot simply generate the documentation starting from a 
> given root element.
> 
> But there may be a few options that could help you break it 
> down into smaller parts.
> For example if you generate HTML you can split the output in 
> multiple files by component(in the Output tab). Other than 
> that there are the generic filters from the Settings tab, but 
> I'm not sure if they're useful to you in this case.
> 
> There's also the possibility to trim the schema and remove 
> the unwanted root elements before generating the 
> documentation, but I'm guessing you were looking for 
> something automatic to do this.
> 
> Regards,
> Adrian Buza
> Oxygen XML Editor support
> 
> Ingo Freitag wrote:
> > Hi,
> >
> > I have a very huge schema file with several root elements included.
> > Now I want to create a documentation out of one of those 
> root elements only.
> >
> > Is this somehow possible?
> > Of course all linked and referenced types shall also be 
> included in the documentation.
> >
> > Ingo