如何从Relax NG Schema中生成基本文档 [英] How can I generate basic documentation from a Relax NG Schema

问题描述

我正在尝试从Relax NG XML Schema中的注释生成非常简单的文档。例如，给出以下Relax NG：

I'm trying to generate very simple documentation from the annotations in a Relax NG XML Schema. For example, given the following Relax NG:

<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0" xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
    <start>
        <element name="topNode">
            <ref name="topNode-ref"/>
        </element>
    </start>

    <define name="topNode-ref">
        <a:documentation>This is the top of the doc.</a:documentation>
        <oneOrMore>
            <element name="level1">
                <ref name="level1-ref"/>
            </element>
        </oneOrMore>
    </define>

    <define name="level1-ref">
        <a:documentation>Here's some notes about level1.</a:documentation>
        <attribute name="att1">
            <a:documentation>Details about att1.</a:documentation>
        </attribute>
        <element name="subLevel2">
            <ref name="subLevel2-ref"/>
        </element>
    </define>

    <define name="subLevel2-ref">
        <a:documentation>Notes on subLevel2.</a:documentation>
        <attribute name="subAtt"/>
        <zeroOrMore>
            <element name="subLevel3">
                <ref name="subLevel3-ref"/>
            </element>
        </zeroOrMore>
    </define>

    <define name="subLevel3-ref">
        <a:documentation>And here is subLevel3.</a:documentation>
        <attribute name="subSubAtt"/>
    </define>
</grammar>

哪些用于验证XML文件，如：

Which would be used to valid an XML file like:

<?xml version="1.0" encoding="UTF-8"?>
<topNode>
    <level1 att1="some test">
        <subLevel2 subAtt="more text"></subLevel2>
    </level1>

    <level1 att1="quick">
        <subLevel2 subAtt="brown">
            <subLevel3 subSubAtt="fox"></subLevel3>
        </subLevel2>
    </level1>   
</topNode>

我希望能够生成列出每个元素/属性的基本XPath的文档，然后显示任何相应的文档注释。例如：

I'd like to be able to produce documentation that lists the basic XPath to each element/attribute and then display any corresponding documentation annotations. For example:

/topNode
This is the top of the doc.

/topNode/level1
Here's some notes about level1

/topNode/level1/@att1
Details about att1.

etc...

最后，我将添加更多文档关于zeroOrMore，可能的数据类型等，但是我需要首先解决这个第一步。

Eventually, I'll add in more documentation about "zeroOrMore", possible data types, etc... but I need to get this first step solved first.

我发现 Techquila RELAX-NG文档工具。我已经玩了rpg到docbook样式表，但它不做我正在寻找的。它只是单独列出元素，没有关于XPath的细节，就我所知。我不知道如何使用它作为获取输出的起点。

I've found the Techquila RELAX-NG Documentation Tools. I've played around with the rng to docbook stylesheet, but it don't do what I'm looking for. It just lists elements individually with no details about the XPath as far as I can tell. I don't see how I can use it as a starting point to get the output I'm after.

是否可能（如果是，如何？）给出了提供的RelaxNG示例，使用XSLT生成这种类型的文档输出？

Is it possible (and if so, how?) to produce this type of documentation output with XSLT given the RelaxNG example provided?

虽然XSLT是理想的，但不是必需的。我为任何可以完成工作的人开放。

While XSLT would be ideal, it's not a requirement. I'm open for anything that gets the job done.

推荐答案

这将为您的示例提供一个非常简单的语法。

This will work for a very simple grammar like your example.

<?xml version='1.0'?>
<xsl:stylesheet version="1.0" 
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:r="http://relaxng.org/ns/structure/1.0" 
    xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"
>
<xsl:output method="text" />

<xsl:template match="/">
    <xsl:apply-templates select="//r:define[a:documentation] | //r:attribute[a:documentation]" />
</xsl:template>

<xsl:template match="r:define">
    <xsl:variable name="doc" select="a:documentation" />
    <xsl:call-template name="print-path">
        <xsl:with-param name="elm" select="//r:element[r:ref/@name=current()/@name]" />
    </xsl:call-template>
    <xsl:value-of select="$doc" /><xsl:text>&#10;</xsl:text>
</xsl:template>

<xsl:template match="r:attribute">
    <xsl:variable name="doc" select="a:documentation" />
    <xsl:call-template name="print-path">
        <xsl:with-param name="elm" select="//r:element[r:ref/@name=current()/ancestor::r:define/@name]" />
        <xsl:with-param name="path" select="concat('/@',@name)" />
    </xsl:call-template>
    <xsl:value-of select="$doc" /><xsl:text>&#10;</xsl:text>
</xsl:template>

<xsl:template name="print-path">
    <xsl:param name="elm" />
    <xsl:param name="path" />

    <xsl:variable name="parent" select="//r:ref[@name=$elm/ancestor::r:define/@name]/ancestor::r:element" />
    <xsl:message><xsl:value-of select="$elm/@name" /></xsl:message>
    <xsl:choose>
        <xsl:when test="$parent">
            <xsl:call-template name="print-path">
                <xsl:with-param name="elm" select="$parent" />
                <xsl:with-param name="path" select="concat('/',$elm/@name,$path)" />
            </xsl:call-template>
        </xsl:when>
        <xsl:otherwise>
            <xsl:value-of select="concat('/',$elm/@name,$path)" /><xsl:text>&#10;</xsl:text>            
        </xsl:otherwise>
    </xsl:choose>
</xsl:template>

</xsl:stylesheet>

这篇关于如何从Relax NG Schema中生成基本文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！