[pmwiki-users] preformatted text

Patrick R. Michaud pmichaud at pobox.com
Fri Aug 12 00:15:38 CDT 2005


It's often come up that we would like to have a good markup for 
representing verbatim text (monospace text, escaped from all wiki 
formatting).  The current markup for this is space+[=...=], as in

     [=
    Here is some monospace text.  Note
    the space before the initial bracket+equals.
    =]

Essentially this is just the "lines beginning with space are 
preformatted text" rule applied to escaped text.  Unfortunately,
it has a couple of often-described drawbacks:
  - it's not obvious to new authors
  - there's not a way to start preformatted text immediately at
    the left margin, the first line must either contain a space, or
    is a blank line.

I don't propose to eliminate or change the current space+[=...=]
markup, but in working on the documentation we definitely need
an alternative.  Here are some proposals:

1.  Change [@...@] to mean "preformatted text" if the ... portion
contains a newline.  Currently [@...@] is essentially the same as
@@[=...=]@@, which generates <code>...</code> in the HTML output.
The [@...@] markup is very useful for writing markup examples;
i.e., to display "[[WikiWord]]" in monospaced text, an author can
write [@[[WikiWord]]@] instead of the ugly and cumbersome 
@@[=[[WikiWord]]=]@@.

However, new authors are often surprised by [@...@] when it contains
multiple lines -- the newlines are folded into a single output line
(as @@[=...=]@@ would do), whereas many authors expect the result 
to have the newlines preserved in preformatted text.

So, perhaps we can reduce author surprise and add our needed markup
by saying that [@...@] around text with newlines results in a
<pre>...</pre> block instead of <code>...</code>.  We can also
be smart about parsing initial and closing newlines, thus the
two items below would both generate three lines of monospace output,
with no blank lines on either side:

    [@Here is some
    monospaced text
    spread across multiple lines.@]

    [@
    Here is some
    monospaced text
    spread across multiple lines
    @]


2.  Introduce explicit (:pre:) ... (:preend:) directives.  Another 
possibility is to just introduce explicit directives for
preformatted text.  The only qualm I have with this is that it
can look a little more verbose than I'd like -- especially the
"(:preend:)" part.

    (:pre:)
    Here is some 
    monospaced text
    spread across multiple lines.
    (:preend:)


3.  Try to create preformatted div wikistyles.  I've played with this
a bit, but it again becomes an issue of dealing with initial and
trailing newlines.  The best I can come up with so far is

    >>pre<< Here is some
    monospaced text
    spread across multiple lines
    >><<

One disadvantage of the div wikistyle is that it probably cannot
be easily used in tables.

Thoughts, suggestions...?

Pm




More information about the pmwiki-users mailing list