Skip to Content
RELAX NG
book

RELAX NG

by Eric van der Vlist
December 2003
Intermediate to advanced
506 pages
12h 26m
English
O'Reilly Media, Inc.
Content preview from RELAX NG

Documentation

After this long introduction to annotation syntax, it is time to explore applications of annotations. The first application of annotations is for documentation. The issue of generating documentation from schemas, much like the problem of generating documentation from code, is a long-running problem with three different schools of thought:

  • The documentation and the schema are stored separately. In this case, there is nothing specific to documenting RELAX NG schemas, and this technique is beyond the scope of this book.

  • The schema can be embedded in the documentation: proponents of “Literate Programming” are fans of this approach. It will be presented in Chapter 14.

  • The documentation can be embedded within the schema: I’ll cover this approach in this section.

You’ve seen the technical basis of how these annotations can be included in RELAX NG schemas. Generating documentation from these annotations is mainly a matter of writing an XSLT transformation to extract them and then formatting the annotations according to your needs. I won’t be going through the details of XSLT transformations, but the following examples are good candidates for these kinds of transformation.

Comments

This example uses simple comments:

   <define name="author-element">
     <!-- Definition of the author element -->
     <element name="author">
       <attribute name="id"/>
       <ref name="name-element"/>
       <ref name="born-element"/>
       <optional>
         <ref name="died-element"/>
       </optional>
     </element>
   </define>

which is equivalent to: ...

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.

Read now

Unlock full access

More than 5,000 organizations count on O’Reilly

AirBnbBlueOriginElectronic ArtsHomeDepotNasdaqRakutenTata Consultancy Services

QuotationMarkO’Reilly covers everything we've got, with content to help us build a world-class technology community, upgrade the capabilities and competencies of our teams, and improve overall team performance as well as their engagement.
Julian F.
Head of Cybersecurity
QuotationMarkI wanted to learn C and C++, but it didn't click for me until I picked up an O'Reilly book. When I went on the O’Reilly platform, I was astonished to find all the books there, plus live events and sandboxes so you could play around with the technology.
Addison B.
Field Engineer
QuotationMarkI’ve been on the O’Reilly platform for more than eight years. I use a couple of learning platforms, but I'm on O'Reilly more than anybody else. When you're there, you start learning. I'm never disappointed.
Amir M.
Data Platform Tech Lead
QuotationMarkI'm always learning. So when I got on to O'Reilly, I was like a kid in a candy store. There are playlists. There are answers. There's on-demand training. It's worth its weight in gold, in terms of what it allows me to do.
Mark W.
Embedded Software Engineer

You might also like

How to Develop a Great Digital Strategy

How to Develop a Great Digital Strategy

Jeanne W. Ross, Cynthia M. Beath, Ina M. Sebastian
Broadband Optical Access Networks

Broadband Optical Access Networks

Leonid G. Kazovsky, Ning Cheng, Wei-Tao Shaw, David Gutierrez, Shing-Wa Wong
The Hidden Cost of AI-Assisted Creativity

The Hidden Cost of AI-Assisted Creativity

Léonard Boussioux, Anil Doshi, Oliver Hauser, Kartik Hosanagar
XML Hacks

XML Hacks

Michael Fitzgerald

Publisher Resources

ISBN: 0596004214Errata Page