[Linux-ha-dev] Formatting of agent man pages

[Holger Teutsch]

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


-------------- next part --------------
A non-text attachment was scrubbed...
Name: ra2refentry.xsl.diff
Type: text/x-patch
Size: 2271 bytes
Desc: not available
Url : http://lists.linux-ha.org/pipermail/linux-ha-dev/attachments/20110210/225eca76/attachment.bin