sitefaqlet SiteDocClan  <h1>Writeup Formatting Tips</h1> The following are recommendations for making sure your posts are as readable as possible. We <b>strongly</b> encourage you abide by these recommendations. <dl> <dt><h3>The three most important words in posting</h3></dt> <dd>Preview, Preview, Preview. Even though, in most cases, you [id://17557|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 <i>before</i> you finally hit Submit. (In your [id://786919|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.)</dd> <dt><a name="codetags"></a><h3>Put <c><code>...</code></c> tags around your code and data</h3></dt> <dd><p> 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 <b>Code Listing Settings</b> section of your [id://450961].) As with HTML <c><PRE></c> tags, line breaks will occur wherever you put them; in fact, all text — including HTML tags, such as <c><br></c> — will be displayed as text, exactly as you typed it. </p><p> If you use tabs to indent your code, consider converting them to 2 or 3 spaces before posting. Also, people prefer if your code <i>is</i> 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 [doc://perlstyle]. You might also consider running your code through [http://perltidy.sourceforge.net|perltidy]. </p><p> Note that <code><c></code> is an alias for <c><code></c>. It's convenient to have this alias, because it lets you write <c><code></c> literally in a message or post if you need to, by writing <tt><c><code></c></tt>. Conversely, you can write <code><c></code> by writing <tt><code><c></code></tt> </p></dd> <dt><h3>Carriage returns are stripped</h3></dt> <dd>All carriage returns are ignored in posts except within <c><code></c> sections. Use a <c><br></c> or a <c><br/></c> to get a line-break and a <c><p></c> tag to get a paragraph break.</dd> <dt><a name="para"></a><h3>Long paragraphs are boring</h3></dt> <dd>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?</dd> <dt><a name="readmore"></a><h3>Use <c><readmore></c> tags in long posts</h3></dt> <dd><p> <c><readmore>...</readmore></c> 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 <c><readmore>...</readmore></c> 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 [id://92975|consideration]. </p><p> Here's how <c><readmore>...</readmore></c> tags behave:<br/> If a node has a chunk of text with <c><readmore>...</readmore></c> tags around it, that chunk will display normally (i.e. as if there were no <c><readmore>...</readmore></c> tags) <b>only</b> when that node is being viewed directly. That is, when the user has navigated to that specific node.<br/> In any other places where that node's contents may be viewed, the <c><readmore>...</readmore></c>-enclosed chunks will <i>not</i> 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.) </p><p> There are numerous places where a node is rendered with its <c><readmore></c> chunks hidden, including: <ul> <li> On the main page of the site section it's in (e.g. [id://479|SoPW]), if it's a root post </li> <li> In the thread view under a root post, if it's not </li> <li> On the [id://131|Front Page] </li> <li> In [id://28877] </li> </ul> </p><p> As an exercise, take a look at this example: [id://297408]. 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 [id://297408], where the data chunk is displayed fully. </p><p> You can specify your own link text if you don't like "Read more...": <code> <readmore title="See the code"> . . . </readmore> </code> </p><p> If a <c><readmore></c> tag does not have a corresponding <c></readmore></c> tag, PerlMonks will automatically insert the closing tag at the very end of the post. However, you should not rely on this "feature". </p><p> Readmore tags cannot be nested. </p><p> Developers' Note: When a node containing <c><readmore></c> is viewed in its full, expanded form, the tags are converted to <c> <div class='readmore'> </div> </c> </p> <a name="spoiler"></a> <p> As an alternative, if you want certain content in your node to be hidden even when that node is viewed directly, you can use <c><spoiler>...</spoiler></c> tags. For example, when posting a solution to a puzzle, you should use <c><spoiler>...</spoiler></c> tags as a courtesy to your fellow monks who may not have solved it yet. </p> </dd> <dt><a name="entities"></a><h3>Special characters quick reference:</h3></dt> <dd>Outside of <c><code></c> tags, some characters may need to be represented by entities: <table border="1"> <th>Character</th><th>Entity</th> <tr><td>&</td><td>&amp;</td> <tr><td><</td><td>&lt;</td> <tr><td>></td><td>&gt;</td> <tr><td>[</td><td>&#91;</td> <tr><td>]</td><td>&#93;</td> </table> </dd> <dt><h3>Some HTML tags are allowed in writeups</h3></dt> <dd>Most of the basic formatting tags are allowed. Read [id://29281] for the exact gory details. Alternately, [id://674668] provides examples of how commonly used tags are actually rendered and guidance for those not familiar with html.<br> You can't post <c><script></c> tags. <br> 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. </dd> <dt><h3>Link wisely</h3></dt> <dd>There exist several forms of shortcuts for efficiently linking to other resources, both inside and outside the Monastery. See [id://43037]</dd> <dt><h3>Don't get carried away</h3></dt> <dd>While basic formatting tags are allowed, don't be too fancy. Try to stick to just <b><tt><b></tt> for bold</b> and <i><c><i></c> for italics</i>. 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 <c><font></c> tags. Almost any use of <c><font></c> tags will be wrong for at least some users, so you shouldn't use them. At all. The only reason <c><font></c> 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 <c><spoiler></c> tags. </dd> <dt><h3>If you're not sure...</h3></dt> <dd>If you're not sure if something will look the way you want it to, use the Preview. Repeat after me: Preview, Preview, Preview.</dd> </dl> <hr/><i>Back to the [PerlMonks FAQ]</i>