Hi docs@!
I have been thinking a way to inform users about our best practices when
finding inconsistencies in the docs, namely checking CHANGES and Bugzilla
first. Most of the times occasional users (or even experienced ones) tend
to forget where the changelog is, if httpd uses bugzilla or not, etc.. so
it would be great in my opinion to add a "reminder" in our manual pages.
The attached patch will add a little section in the right column (right
below "See also") to provide the aforementioned links.
Position, wording, etc.. can be changed of course, this email is only meant
to discuss the idea. If you don't like it, just state it out loud and I'll
drop it :)
Let me know your thoughts!
Luca
Index: docs/manual/style/lang/en.xml
===================================================================
--- docs/manual/style/lang/en.xml (revision 1738540)
+++ docs/manual/style/lang/en.xml (working copy)
@@ -71,6 +71,7 @@
<message id="uppercase">ABCDEFGHIJKLMNOPQRSTUVWXYZ</message>
<message id="name-section">NAME</message>
<message id="hyphenation"></message>
+ <message id="foundabug">Bugfix checklist:</message>
<!-- Used in description box for directives -->
<message id="syntax">Syntax</message>
Index: docs/manual/style/xsl/manualpage.xsl
===================================================================
--- docs/manual/style/xsl/manualpage.xsl (revision 1738540)
+++ docs/manual/style/xsl/manualpage.xsl (working copy)
@@ -38,12 +38,12 @@
<xsl:attribute name="class">no-sidebar</xsl:attribute>
</xsl:if>
- <xsl:call-template name="top"/>
+ <xsl:call-template name="top"/>
<div id="page-content">
<xsl:call-template name="retired" />
- <div id="preamble">
+ <div id="preamble">
<h1>
<xsl:value-of select="title"/>
</h1>&lf;
@@ -52,7 +52,7 @@
<xsl:apply-templates select="summary" />
</div>&lf; <!-- /#preamble -->
-
+
<xsl:if test="(not($is-chm) and count(section) > 1) or seealso">
<div id="quickview">
<xsl:if test="not($is-chm) and count(section) > 1">
@@ -81,6 +81,15 @@
</li>
</ul>
</xsl:if>
+ <h3>
+ <xsl:value-of select="$message[@id='foundabug']" />
+ </h3>
+ <ul class="seealso">
+ <li><a
href="http://httpd.apache.org/dev/dist/CHANGES_2.4";>
+ httpd 2.4 Changelog</a></li>
+ <li><a href="https://bz.apache.org/bugzilla/query.cgi";>
+ httpd Bugzilla</a></li>
+ </ul>
</div>&lf; <!-- /#quickview -->
</xsl:if>
Index: docs/manual/style/xsl/moduleindex.xsl
===================================================================
--- docs/manual/style/xsl/moduleindex.xsl (revision 1738540)
+++ docs/manual/style/xsl/moduleindex.xsl (working copy)
@@ -33,7 +33,7 @@
<xsl:call-template name="head"/>&lf;
<body id="module-index">
- <xsl:call-template name="top"/>
+ <xsl:call-template name="top"/>
<div id="page-content">
<xsl:call-template name="retired" />
@@ -75,7 +75,7 @@
<h3>
<xsl:value-of select="$message
[@id='seealso']" />
- </h3>&lf;
+ </h3>&lf;
<ul class="seealso">&lf;
<xsl:for-each select="seealso">
@@ -85,6 +85,15 @@
</xsl:for-each>
</ul>
</xsl:if> <!-- /seealso -->
+ <h3>
+ <xsl:value-of select="$message[@id='foundabug']" />
+ </h3>
+ <ul class="seealso">
+ <li><a
href="http://httpd.apache.org/dev/dist/CHANGES_2.4";>
+ httpd 2.4 Changelog</a></li>
+ <li><a href="https://bz.apache.org/bugzilla/query.cgi";>
+ httpd Bugzilla</a></li>
+ </ul>
</div> <!-- /#quickview -->
</xsl:if>&lf; <!-- have sidebar -->
@@ -172,7 +181,7 @@
[@id='othermodules']" />
</a>
</h2>&lf;
-
+
<xsl:variable name="modules"
select="document(document($allmodules)/modulefilelist/modulefile)
/modulesynopsis[status!='MPM' and
@@ -204,7 +213,7 @@
<xsl:call-template name="bottom" />&lf;
</body>
</html>
-</xsl:template>
+</xsl:template>
<!-- /moduleindex -->
@@ -305,7 +314,7 @@
<!-- expression below: -->
<!--
substring-before(
- substring-after($translist,
+ substring-after($translist,
concat('- ', translate(modulename,
$lowercase, $uppercase),
' ')
Index: docs/manual/style/xsl/synopsis.xsl
===================================================================
--- docs/manual/style/xsl/synopsis.xsl (revision 1738540)
+++ docs/manual/style/xsl/synopsis.xsl (working copy)
@@ -265,6 +265,15 @@
</li>
</ul>
</xsl:if>
+ <h3>
+ <xsl:value-of select="$message[@id='foundabug']" />
+ </h3>
+ <ul class="seealso">
+ <li><a
href="http://httpd.apache.org/dev/dist/CHANGES_2.4";>
+ httpd 2.4 Changelog</a></li>
+ <li><a href="https://bz.apache.org/bugzilla/query.cgi";>
+ httpd Bugzilla</a></li>
+ </ul>
</div> <!-- /#quickview -->
</xsl:if>&lf; <!-- have sidebar -->
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscr...@httpd.apache.org
For additional commands, e-mail: docs-h...@httpd.apache.org
