On Tue, 2011-02-08 at 13:29 +0100, Florian Haas wrote:
> On 2011-02-08 13:25, Holger Teutsch wrote:
> > Hi,
> > is there a way to carry over formatting (at least line breaks) from an
> > agent's meta data to the generated man page ?
> >
> > The more meaningful the description of an agent is in the meta-data the
> > less it is readable in the man page 8-) .
>
> I'd be happy to accept a patch to doc/ra2refentry.xsl :)
>
> Cheers,
> Florian
Florian,
I have a patch that preserves line breaks (in detail: it generates
<para> elements on line breaks).
e.g. SAPInstance
------------------------------ before ---------------------------
DESCRIPTION
Usually a SAP system consists of one database and at least one or more
SAP instances (sometimes called application servers). One SAP Instance
is defined by having exactly one instance profile. The instance
profiles can usually be found in the directory /sapmnt/SID/profile.
Each instance must be configured as it's own resource in the cluster
configuration. The resource agent supports the following SAP versions:
- SAP WebAS ABAP Release 6.20 - 7.30 - SAP WebAS Java Release 6.40 -
7.30 - SAP WebAS ABAP + Java Add-In Release 6.20 - 7.30 (Java is not
monitored by the cluster in that case) When using a SAP Kernel 6.40
please check and implement the actions from the section "Manual
postprocessing" from SAP note 995116 (http://sdn.sap.com). All
operations of the SAPInstance resource agent are done by using the
startup framework called SAP Management Console or sapstartsrv that was
introduced with SAP kernel release 6.40. Find more information about
the SAP Management Console in SAP note 1014480. Using this framework
defines a clear interface for the Heartbeat cluster, how it sees the
SAP system. The options for monitoring the SAP system are also much
better than other methods like just watching the ps command for running
processes or doing some pings to the application. sapstartsrv uses SOAP
messages to request the status of running SAP processes. Therefore it
------------------------------ after ----------------------------
DESCRIPTION
Usually a SAP system consists of one database and at least one or more
SAP instances (sometimes called application servers). One SAP Instance
is defined by having exactly one instance profile. The instance
profiles can usually be found in the directory /sapmnt/SID/profile.
Each instance must be configured as it's own resource in the cluster
configuration.
The resource agent supports the following SAP versions:
- SAP WebAS ABAP Release 6.20 - 7.30
- SAP WebAS Java Release 6.40 - 7.30
- SAP WebAS ABAP + Java Add-In Release 6.20 - 7.30 (Java is not
monitored by the cluster in that case)
When using a SAP Kernel 6.40 please check and implement the actions
from the section "Manual postprocessing" from SAP note 995116
(http://sdn.sap.com).
All operations of the SAPInstance resource agent are done by using the
startup framework called SAP Management Console or sapstartsrv that was
introduced with SAP kernel release 6.40. Find more information about
the SAP Management Console in SAP note 1014480. Using this framework
defines a clear interface for the Heartbeat cluster, how it sees the
SAP system. The options for monitoring the SAP system are also much
better than other methods like just watching the ps command for running
processes or doing some pings to the application. sapstartsrv uses SOAP
messages to request the status of running SAP processes. Therefore it
can actually ask a process itself what it's status is, independent from
other problems that might exist at the same time.
sapstartsrv knows 4 status colours:
- GREEN = everything is fine
- YELLOW = something is wrong, but the service is still working
-----------------------------------------------------------------
Agents that do their own "block fill" with linefeeds in <longdesc> look
more ugly of course. These LFs have to be removed. The python gui would
benefit from this as well.
In total I think the readability of the complex descriptions outweights
this temporary ugliness.
Not expert for XSL but I'm afraid a more elaborate solution requires a
richer DTD.
Regards
Holger
# HG changeset patch
# User Holger Teutsch <holger.teut...@web.de>
# Date 1297334873 -3600
# Node ID 420c917bf563adb3d296e4dc122cfa1f3804761f
# Parent 87a371f5e02cf69d1c93ae9020e398846ceca993
Med: ra2refentry.xsl: Improve readability of generated man pages
Preserve line breaks in "Description" section.
diff -r 87a371f5e02c -r 420c917bf563 doc/ra2refentry.xsl
--- a/doc/ra2refentry.xsl Wed Feb 09 13:01:59 2011 +0100
+++ b/doc/ra2refentry.xsl Thu Feb 10 11:47:53 2011 +0100
@@ -126,18 +126,50 @@
<!-- Mode Description -->
- <xsl:template match="resource-agent" mode="description">
+
+ <!-- break string into <para> elements on linefeeds -->
+
+<xsl:template name="break_into_para">
+ <xsl:param name="string" />
+
+ <xsl:variable name="lf" select="'
'" />
+ <xsl:choose>
+ <xsl:when test="contains($string, $lf)">
+ <xsl:variable name="first" select="substring-before($string, $lf)" />
+
+ <!-- skip empty lines as <para> spacing generates one -->
+
+ <xsl:if test="string-length($first) > 0">
+ <para>
+ <xsl:value-of select="$first"/>
+ </para>
+ </xsl:if>
+
+ <!-- recursively call an remaining string -->
+ <xsl:call-template name="break_into_para">
+ <xsl:with-param name="string"
+ select="substring-after($string, $lf)" />
+ </xsl:call-template>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="$string"/>
+ </xsl:otherwise>
+ </xsl:choose>
+</xsl:template>
+
+ <xsl:template match="resource-agent" mode="description">
<refsection>
<title>Description</title>
<xsl:apply-templates mode="description"/>
</refsection>
</xsl:template>
- <xsl:template match="longdesc" mode="description">
- <para>
- <xsl:apply-templates mode="description"/>
- </para>
- </xsl:template>
+ <xsl:template match="longdesc" mode="description">
+ <xsl:call-template name="break_into_para">
+ <xsl:with-param name="string" select="." />
+ </xsl:call-template>
+ <!-- xsl:apply-templates mode="description"/ -->
+ </xsl:template>
<!-- Mode Parameters -->
_______________________________________________________
Linux-HA-Dev: Linux-HA-Dev@lists.linux-ha.org
http://lists.linux-ha.org/mailman/listinfo/linux-ha-dev
Home Page: http://linux-ha.org/
