Beefy Boxes and Bandwidth Generously Provided by pair Networks
Think about Loose Coupling
 
PerlMonks  

Writeup Formatting Tips

by SiteDocClan
on Jun 11, 2000 at 04:06 UTC ( #17558=sitefaqlet: print w/ replies, xml ) Need Help??

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 been submitted, 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 <code><c></code>

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 paragraph break.

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 a page?

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

<div class='readmore'> </div>

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 by entities:
CharacterEntity
&&amp;
<&lt;
>&gt;
[&#91;
]&#93;

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.

Link wisely

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
Log In?
Username:
Password:

What's my password?
Create A New User
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others lurking in the Monastery: (9)
As of 2014-08-21 20:29 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    The best computer themed movie is:











    Results (143 votes), past polls