Writeup Formatting Tips
The following are recommendations for making sure your posts are as readable as possible. We strongly encourage you abide by these recommendations.
The three most important words in posting
- Preview, Preview, Preview.
Even though, in most cases, you can edit your node after it has
some sections of the site do not allow this, so be sure that
everything is looking how you want others to see it before
you finally hit Submit.
(In your User Settings you can switch
off the forced preview. But don't. Even the most experienced monks
still preview before posting.
Your humble author has previewed up to eight
times on some posts, just to make sure it would look right.)
Put <code>...</code> tags around your code and data
This will make PerlMonks render them in a monospaced font and
allow your code to be easily extracted (via the 'download code' link).
Perhaps more importantly, it imposes a "smart wrapping" feature on the
text. (See the Code Listing Settings section of your Display Settings.)
As with HTML <PRE> tags, line breaks
will occur wherever you put them; in fact, all text — including HTML tags,
such as <br> — will be displayed as text, exactly as you typed it.
If you use tabs to indent your code, consider converting them
to 2 or 3 spaces before posting. Also, people prefer if your code is
indented and as tidy as possible. If you're not sure if you code in an acceptably tidy style, compare it to the recommendations in perlstyle.
You might also consider running your code through perltidy.
Note that <c> is an alias for <code>.
It's convenient to have this alias, because it lets you write
<code> literally in a message or post if you need to,
by writing <c><code></c>.
Conversely, you can write <c> by writing
Carriage returns are stripped
- All carriage returns are ignored in posts except within <code>
sections. Use a <br> or a <br/> to get a line-break and a <p> tag to get a
Long paragraphs are boring
- Think about the posts that you read. You probably steer clear of ones that
contain solid blocks of text unless you know you're interested in the content.
When you write your post consider: would I read this when scanning through
Use <readmore> tags in long posts
<readmore>...</readmore> tags are used to elide (hide) large chunks of a post, such as long sections of code. If your post is "very long" — say, more than two screen heights — you should identify any parts that can be hidden, and put <readmore>...</readmore> tags around each one. Posts in which this rule of courtesy is ignored are subject to being edited by the janitors. So please, take care of this yourself, and avoid the shame of consideration.
Here's how <readmore>...</readmore> tags behave:
If a node has a chunk of text with <readmore>...</readmore> tags around it, that chunk will display normally (i.e. as if there were no <readmore>...</readmore> tags) only when that node is being viewed directly. That is, when the user has navigated to that specific node.
In any other places where that node's contents may be viewed, the <readmore>...</readmore>-enclosed chunks will not be visible, but will be replaced with a link saying "Read more...".
(That link really just takes the user to the normal full display of that node.)
There are numerous places where a node is rendered with its <readmore> chunks hidden, including:
- On the main page of the site section it's in (e.g. SoPW), if it's a root post
- In the thread view under a root post, if it's not
- On the Front Page
- In Nodes to consider
As an exercise, take a look at this example: Re: Generalizing Code: Generating Unique Permutations.
You see that huge chunk of data? If you navigate up to the
node's parent (the thread's root post), you won't see that data
blob in that node, where it's displayed as a child of the root.
Instead, you see the "Read more..." link. Now, if you click
that link, it takes you right back to Re: Generalizing Code: Generating Unique Permutations,
where the data chunk is displayed fully.
You can specify your own link text if you don't like "Read more...":
<readmore title="See the code"> . . . </readmore>
If a <readmore> tag does not have a corresponding </readmore> tag, PerlMonks will automatically insert the closing tag at the very end of the post. However, you should not rely on this "feature".
Readmore tags cannot be nested.
Developers' Note: When a node containing <readmore> is viewed in its full, expanded form, the tags are converted to
As an alternative, if you want certain content in your node to be hidden even when that node is viewed directly, you can use <spoiler>...</spoiler> tags.
For example, when posting a solution to a puzzle, you should use
<spoiler>...</spoiler> tags as a courtesy to your fellow monks
who may not have solved it yet.
Special characters quick reference:
- Outside of <code> tags, some characters may need to be represented
Some HTML tags are allowed in writeups
- Most of the basic formatting tags are allowed.
Read Perl Monks Approved HTML tags for the exact gory details. Alternately, Markup in the Monastery provides examples of how commonly used tags are actually rendered and guidance for those not familiar with html.
You can't post <script> tags.
Please be sure to keep in mind the comments in this document under the
section "Don't get carried away" when you are deciding what tags to use.
- There exist several forms of shortcuts for efficiently linking to other resources, both inside and outside the Monastery. See What shortcuts can I use for linking to other information?
Don't get carried away
- While basic formatting tags are allowed, don't be too fancy. Try to stick to
just <b> for bold and <i> for italics.
If you get too obnoxious with your formatting, you may even run the risk of
incurring some downvotes from your audience.
This is particularly true for <font> tags.
Almost any use of <font> tags will be wrong for at least some users,
so you shouldn't use them. At all.
The only reason <font> is allowed is for backwards compatibility.
If you want to obscure some text for some reason (like the punchline for a joke,
or the answer to a tricky question) then you should use <spoiler> tags.
If you're not sure...
- If you're not sure if something will look the way you want it to, use
the Preview. Repeat after me: Preview, Preview, Preview.
Back to the PerlMonks FAQ