#330 man: Add more options for admonition output

output: manpages
XSL (399)

Output for admontions (Caution, Important, Note,
Tip, and Warning) is meant to stand out and be
noticed. But in current output, it is just
rendered with a subheading and indentation. We need
to give it greater prominence. And perhaps make it
optional, with default being greater prominenence.

I think the best way might be to use tbl(1) to render
a box around it. Another way might be to just render
a horizontal line after the admonition title. But
I think I will probably implement the boxed table
output instead.

Note that at least one user has suggested that the
current output already gives admonitions too much
prominence, and has suggested that the admonition
title should just be rendered as a "run in" head;
that is, instead, at the beginning of the
paragraph which forms the content of the admonition,
but in bold and followed by a period. That is:

*Caution*. You must be extremely careful not to...

Instead of:

You must be extremetly careful not to...

I am reluctant to add support for that "run in" style
because I think it risks making the admontions
get "lost" within the rest of the text and so not
really serving the purpose they are meant for. But
I guess I should consider whether to make that style
an option at least.


  • Michael(tm) Smith

    • priority: 5 --> 3
  • Michael(tm) Smith

    Logged In: YES

  • Michael(tm) Smith

    • summary: man: Make admonition output stand out more --> man: Add more options for admonition output
  • Michael(tm) Smith

    Logged In: YES

  • Daniel Leidert

    Daniel Leidert - 2006-04-13

    Logged In: YES

    An option for that "run in" style would be nice. But I
    already told that :). It fits, what an inline construction

    <para>[..] <emphasis role="bold">Note:</emphasis> [..]</para>

    would make. But an admonition element really fits, what I
    want to write.

    Regards, Daniel


Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:

No, thanks