[ docbook-Feature Requests-1446009 ] man: admonition tags should be handled inline

[SourceForge.net <no...@so...>]

Feature Requests item #1446009, was opened at 2006-03-09 08:18
Message generated for change (Comment added) made by xmldoc
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=373750&aid=1446009&group_id=21935

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: XSL
Group: output: manpages
>Status: Closed
Resolution: None
Priority: 3
Submitted By: Daniel Leidert (dleidert)
Assigned to: Michael Smith (xmldoc)
Summary: man: admonition tags should be handled inline

Initial Comment:
The current handling of admonition tags result in the
following example:

|\fBImportant\fR
|
|note ...

This needs a lot of space and it fails, if the
admonition tag is part of the <para> element, which is
valid. In this case, the result looks like this:

| ... .RS .Sh "Important" ... note ...

In my opninion, using these tags as inline element,
looks better:

... \fBImportant:\fR ... note ...

It needs less space and IMHO looks more handy. The
snippet I used is:

<xsl:template match="caution|important|note|tip|warning">
<xsl:text>&#10;&#10;\fB</xsl:text>
<xsl:value-of select="translate (substring (name(.), 1,
1), 'cintw', 'CINTW')" />
<xsl:value-of select="substring (name(), 2)" />
<xsl:if test="title">
<xsl:text>:\fR </xsl:text>
<xsl:value-of select="title[1]"/>
</xsl:if>
<xsl:text>:\fR </xsl:text>
<xsl:apply-templates/>
<xsl:text>&#10;</xsl:text>
</xsl:template>

I'm sorry, that this is only the customized template
from the 1.68.1 release of docbook.xsl (but an adaption
to 1.69.1 should be easy).

Regards, Daniel

----------------------------------------------------------------------

>Comment By: Michael Smith (xmldoc)
Date: 2006-04-13 20:09

Message:
Logged In: YES 
user_id=118135

see #1448629

http://sourceforge.net/tracker/index.php?func=detail&aid=
1448629&group_id=21935&atid=373750


----------------------------------------------------------------------

Comment By: Michael Smith (xmldoc)
Date: 2006-04-13 20:07

Message:
Logged In: YES 
user_id=118135




----------------------------------------------------------------------

Comment By: Daniel Leidert (dleidert)
Date: 2006-03-09 21:57

Message:
Logged In: YES 
user_id=1102637

https://sourceforge.net/tracker/index.php?func=detail&aid=
1446282&group_id=21935&atid=373747: Thanks. The fix works.

----------------------------------------------------------------------

Comment By: Daniel Leidert (dleidert)
Date: 2006-03-09 21:27

Message:
Logged In: YES 
user_id=1102637

This would be nice.

PS: I will test the fix soon.

----------------------------------------------------------------------

Comment By: Michael Smith (xmldoc)
Date: 2006-03-09 20:05

Message:
Logged In: YES 
user_id=118135

Daniel,

I will consider adding inline admon titles as an option.
The reason I generally prefer to output all titles
on separate lines is that many users don't actually view
man pages on terminals that support boldface. So they
actually see the bold text rendered in the same weight
as the rest of the body text. So the titles potentially
just get "lost" in the midst of the rest of the text.

Particularly in the case of admonitions, which are
intended by their nature to "stand out" from the rest of
the text, I have some strong misgivings about having
them rendered and inline or "run in" heads.

As far as what you mention about the rendering of
admonitions failing if an admonition tag is part of
a <para> element, that was indeed a bug. I opened up
a bug report for it:

  https://sourceforge.net/tracker/index.php?func=detail&aid=
1446282&group_id=21935&atid=373747

And I just checked in a fix. If possible, please run your
test case with the latest snapshot and let me know if it
still fails for you.

  --Mike


----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=373750&aid=1446009&group_id=21935