This work was done in trunk to allow the new mod_md's directive
names <ManagedDomain> and ManagedDomain in the same doc page (without
triggering any validate-xml/xhtml error). Subsequently this also helped
for SSLPolicy and <SSLPolicy>. All the aforementioned Directives
have not been backported yet, but these commits are needed behorehand to
allow a smoother backport procedure.
I explicitly reverted the changes to sections.xml for this backport since
they mention the above directives, not yet available in 2.4.x and hence
probably confusing for users.
Building the documentation after these changes yield to a no-op as expected.
I also tried to copy mod_md's documentation from trunk and it renders nicely.
Merge r1805189, r1805193, r1805372, r1805376, r1805189, r1806443 from trunk:
synopsis.xsl: do not render two times the same
directive HTML if more than one
directive share the same name.
This has happened when mod_md.xml was introduced,
and the following directives shared the same name:
* ManagedDomain
* <ManagedDomain>
With the current code each time that a node needs
to be rendered it will emit a duplicate, ending up
in the above example with 4 sections rather than two.
Uniqueness of sections will be ensured by the HTML
elements ids, to avoid errors before committing for
example (accidental duplicates, etc..).
common|synopsis.xsl: rename directive type=sections id generation
This commits is a follow up of r1805189 and it is meant
to allow directives with the same name but different type
to coexist in the same document without triggering errors
while executing validate-xhtml.
For example: mod_md.xml recently introduced the following:
* ManagedDomain
* <ManagedDomain> (this one is type=section)
In my opinion this is a perfectly valid use case and it should
be allowed/handled correctly by the doc generation process/validation.
In order to avoid clashing the directive ids will get a suffix
called "section" if type=section will be present as param.
Quicklinks, <directive> links have been updated to the new
scheme to avoid dandling pointers in the doc.
Comments/reviews are welcome, if I left something behind
please let me know.
doc xsl/dtd: introduce idtype attribute for directivesynopsis
In r1805193 synopsis.xsl was changed to allow two directives
of different type (like <SSLPolicy> and SSLPolicy) to share
the same name but have different ids (and please validate-xml/xhtml).
The downside of this action was that all the quicklinks to
existing directive sections (like <If>, <VirtualHost>, etc..)
were changed, possibly breaking external clients already
referencing them.
This change introduces a new attribute in the directivesynopsis
DTD, namely 'idtype', that will be appended to 'name'
in the id generation by synopsis.xsl. This will rollback
link names to their previous values and will allow documentators
to fine tune directivesynopsis sections as they need
(for example we have recently introduced mod_md's
ManagedDomain/<ManagedDomain>, and modssl's SSLPolicy/<SSLPolicy>).
This approach seems more precise and less invasive to me.
Of course the name of the attribute can be changed later on
to whatever term would fit best, the main concern for me at
the moment is to restore the trunk documentation to its previous
state.
common.dtd: add idtype attribute to directive
This change completes r1805372 and also fixes
links generation for <ManageDomain> and <SSLPolicy>
in sections.xml
synopsis.xsl: do not render two times the same
directive HTML if more than one
directive share the same name.
This has happened when mod_md.xml was introduced,
and the following directives shared the same name:
* ManagedDomain
* <ManagedDomain>
With the current code each time that a node needs
to be rendered it will emit a duplicate, ending up
in the above example with 4 sections rather than two.
Uniqueness of sections will be ensured by the HTML
elements ids, to avoid errors before committing for
example (accidental duplicates, etc..).
synopsis.xsl: fix broken translation builds
This commit is a follow up of r1805189, in which
a new logic was added to allow to repeat a directive
name only if its type is different (like SSLPolicy
and <SSLPolicy>). The change broken french translations
since the $this variable, containing the translated
sections, was not used anymore.
The XPath code could surely be improved, but it seems
more pressing to allow our translators to get back
to their daily work without interference.
build.sh validate-* worked fine, as well as the build.sh fr
translation.
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@
1816378 13f79535-47bb-0310-9956-
ffa450edef68
outdated (true) #IMPLIED>
<!ELEMENT directive (#PCDATA)>
-<!-- name attribute is preferred over contents when generating links -->
+<!-- name attribute is preferred over contents when generating links,
+ and idtype is used to disambiguate two directives sharing the
+ same name but with different type (for example section and non-section).
+-->
<!ATTLIST directive module CDATA #IMPLIED
type CDATA #IMPLIED
+ idtype CDATA #IMPLIED
status CDATA #IMPLIED
name CDATA #IMPLIED >
<!ELEMENT description %Inline;>
-<!ATTLIST directivesynopsis type CDATA #IMPLIED
- location CDATA #IMPLIED >
+<!--
+ idtype is appended to the directive name when generating links to allow
+ a directive of type section to share the name with another directive.
+ The attribute type could have been (re)used instead but it would have broken
+ pre-existing links.
+-->
+<!ATTLIST directivesynopsis type CDATA #IMPLIED
+ idtype CDATA #IMPLIED
+ location CDATA #IMPLIED >
<!ELEMENT syntax %Inline;>
<xsl:variable name="lowerdirective">
<xsl:choose>
<xsl:when test="@name">
- <xsl:value-of select="normalize-space(translate(@name,
- $uppercase, $lowercase))" />
+ <xsl:value-of select="normalize-space(concat(translate(@name,
+ $uppercase, $lowercase),@idtype))" />
</xsl:when>
<xsl:otherwise>
- <xsl:value-of select="normalize-space(translate(.,
- $uppercase, $lowercase))" />
+ <xsl:value-of select="normalize-space(concat(translate(.,
+ $uppercase, $lowercase),@idtype))" />
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
/modulesynopsis/directivesynopsis">
<xsl:sort select="name" />
<xsl:variable name="lowername"
- select="translate(name, $uppercase,
- $lowercase)" />
+ select="concat(translate(name, $uppercase,
+ $lowercase),@idtype)" />
<xsl:choose>
<xsl:when test="not(@location)">
<xsl:sort select="name" />
<xsl:choose>
<xsl:when test="$this[name=current()/name]">
- <xsl:apply-templates select="$this[name=current()/name]" />
+ <!-- A directive name is allowed to be repeated if its type
+ is different. There is currently only one allowed type
+ to set, namely 'section', that represents
+ directive/containers like <DirectiveName>.
+ The following check is needed to avoid rendering
+ multiple times the same content when a directive name
+ is repeated.
+ -->
+ <xsl:choose>
+ <xsl:when test="current()[@type='section']">
+ <xsl:apply-templates select="$this[name=current()/name and @type='section']" />
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:apply-templates select="$this[name=current()/name and not(@type='section')]" />
+ </xsl:otherwise>
+ </xsl:choose>
</xsl:when>
<xsl:otherwise>
<xsl:apply-templates select=".">
<xsl:call-template name="toplink" />&lf;
<div class="directive-section">
+ <!-- Concatenate the Directive name with its type to allow
+ a directive to be referenced multiple times
+ with different types -->
<xsl:variable name="lowername"
- select="translate(name, $uppercase, $lowercase)" />
-
+ select="concat(translate(name, $uppercase, $lowercase),@idtype)" />
+ <xsl:variable name="directivename" select="concat(name,@idtype)" />
<!-- Directive heading gets both mixed case and lowercase -->
<!-- anchors, and includes lt/gt only for "section" directives -->
<h2>
</xsl:otherwise>
</xsl:choose>
- <a id="{name}" name="{name}">
+ <a id="{$directivename}" name="{$directivename}">
<xsl:if test="@type='section'"><</xsl:if>
<xsl:value-of select="name" />
<xsl:if test="@type='section'">></xsl:if>
</xsl:when>
<xsl:otherwise>
- <a id="{name}" name="{name}">
+ <a id="{$directivename}" name="{$directivename}">
<xsl:if test="@type='section'"><</xsl:if>
<xsl:value-of select="name" />
<xsl:if test="@type='section'">></xsl:if>
projects / apache / commitdiff