Update: 20080318 Faqlet created; Markup in the Monastery
Significant Update: 20080314 1400 GMT
As of 18 Mar 08, ww's scratchpad Markup in the Monastery has the latest version of this proposal (for a faqlet, tut or whatever on PM markup). The comments from other Monks remain well worth reading, but please address defects in the version in my pad via msg to SiteDocClan. The <readmore> contains an earlier version for comparison.
The content below the rule is offered for review, critiques, improvement and possible future adoption as a faqlet to augment the information in Perl Monks Approved HTML tags.
Among the comments sought are those relating to accuracy, readability (including the phrasing and markup), PM doctrine and necessity.
<readmore> begins here and continues through the rest of this node. (If you're looking at this where the readmore tags are ineffective, apologies for failing to find a way to spare you the original. :-)
Update (2008-03-08 0250 GMT): I've made some corrections/updates, thanks to errors and gobbledeygook in the previous version caught by planetscape. TY, p'scape! They're not specifically marked in the draft below, as I haven't figured out a way to do so without making the text (even?) harder to read.
I'll take a shot at another draft in a day or three, after more Monks have an opportunity to comment. I know I'll be doing my best to adopt/modify that draft in order to incorporate almut's and blokhead's observations, some additional notes from The Dragon and notes from others.
Markup in the Monastery
These are the minimal basics for use in posting an easily readable node (SOPW, your Scratch Pad etc.). PM markup code is NOT entirely w3c html 4.01 standard nor is it XHTML, so even if you're expert please scan these notes. Following these tips will allow you to show your content clearly and legibly. Making the content itself clear (and "reasonable" by our local standards) is left as an exercise for the student, so please see On asking for help and Writeup Formatting Tips
Textual content:
Ordinary paragraphing is accomplished with <p>...</p> tags, which (imprecisely) allow you to have your text appear in what may be called "conventional" paragraphs; that is with blank lines between paragraphs. That's highly recommended, as it makes your node easier to read.
Create links (especially those to nodes at PM) using [target] rather than with <a href=...>. The target inside the square brackets may be a node's title or its id://(number). Optionally, you can override the target's title with your chosen alternate by adding |(some word or phrase) after the id or title and before closing the square brackets.
For example, [Super Search|Did you try to find that here?] will render as Did you try to find that here?. More extensive and sophisticated information can be found in What shortcuts can I use for linking to other information?.
Lists can be either ordered (decimal numbered - using Roman numerals or letters is beyond the scope of this note) or unordered (bulleted). One of each follows; first the ordered list, created with
<ol>
<li>line 1 of list</li>
<li>line 2 of list</li>
<li>and so on</li>
</ol>:
- line 1 of list
- line 2 of list
- and so on
The unordered list uses <ul>...</ul> around the list item tags:
- line 1 of list
- line 2 of list
- and so on
If you find it necessary (and you should make every effort to ensure it is NOT) to create a very long post, please use <readmore> ... </readmore> tags. Should your post make it to the front page, the readmore segment collapses to a link by which the interested reader can see the entire post.
<b>...</b> can be used to enclose words, phrases or sentences you want to have appear in <b>boldface</b>. As a courtesy, do NOT abuse this... and use the preview function to check. Similarly, <i>...</i> can be used to <i>italicize</i> content.
<tt>...</tt> tags surrounding a word or phrase (commonly, a single key word or symbol) causes that word or phrase to be rendered in something akin to a system font; eg: key words within the surrounding text.
Heading tags, <h3>...</h3>, and smaller (through <h6>) may be used. Head tags, unsurprisingly, cause their content to render as headlines. For example
<h4>A headline<h4>
<h6>A smaller headline</h6>
Any <hn> ... </hn> tag pair can be thought of as implying line breaks above and below (absent manipulation with css or other techniques far beyond the scope of this reply). Please note that <h1> and <h2> are deprecated here.
<blockquote>...<blockquote> is used to indent a (brief, please) segment of your text and works like this:
<blockquote>This is a blockquote. Note that it is indented both left and right and offset top and bottom by a blank line. The only reason this blockquote rambles on so verbosely is to ensure that regardless of the witdth of the viewer's browser window, there are multiple lines inside the blockquote. Note also that it is permissable to include some other textual markup inside the blockquote.<p>For example, a two paragraph blockquote can be created this way. Again, this is padded with enough non-substantive verbiage to make it wrap in most (I hope) user's browser windows.</p></blockquote>
Nesting: Check for proper nesting. For example, if you open a paragraph tag, close it before using a blockquote pair or, for just one other example, before beginning a code segment. And that leads us directly to the next important pair of tags.
Posting Your Code
Use code tags, <c>...</c> (and <code>...</code>), to post code and data. Doing so preserves your indentation, blank lines and those symbols (such as <, [ and so on, for which use of character-entities is conventional elsewhere.
A typical use would be to cut'n'paste your code into a PM node Code tags cause the code (or data) they enclose to appear in a distinguishable font. If you have turned on line-numbering in the section on "Code Listing Setings" in Display Settings the code lines will be numbered. The following is inside <c>...</c> tags.
#!/usr/bin/perl use warnings; use strict; use (some module); if (some condition) { do something; and something more; # with a comment to make this a very, very lon +g line which will wrap in many browser windows, absent a gigundo moni +tor and so on. If you don't have auto code wrap on in "code," you'll +see a red plus sign and a lack of line number on the continuations af +ter wrapping is performed (sometimes at unfortunate points, as can be + seen in this instance, if you don't have auto code wrap turned on. } else { &whatever; # Note below } sub whatever { do something; }
Note the download link, above. It appears after each stand-alone code block and allows readers to retrieve the code or data, without the line numbers.
Note that in line 11 the "&" did NOT have to be written as a character entity (&).
Tags You Should NOT Use
The <pre> ...</pre> pair may look, at first blush, like an alternative to code tags... BUT DON'T USE IT HERE chiefly because <pre> tags will not wrap lines that are too long for the viewer's browser window.
Inserting a <br> tag forces a newline at the point at which it's inserted, but is deprecated in the Monastery. Using <div.../div> tags is NOT deprecated, but unless you're expert in .html, you probably shouldn't use them here.
<font (something="something")> ... </font> tags are frowned upon. Don't use them except in extraordinary circumstances.
Finally, read carefully the hints which appear below the text entry box, when you're creating a node, for the character entities with which you must be careful outside of code tags: less than, greater than, square brackets (which should be used for links here, rather than <a href="...</a>) and so on.
Miscellaneous
For those who wish to check or change their settings, use Display Settings while logged in. And please -- in the section of the same node pertaining to "HTML Related Options" -- consider turning on (checking) the "enforce" and setting "Reporting Level" and its "Preview" to the max values; respectively, 3 and 4. If you do so, they'll tell you quite clearly when you omit a required tag and help when you bork nesting rules.
Most of the tags discussed above should be used in pairs, (that is,
(open) ...
(close). While some of the other tags addressed in this node will DWIM even if you fail to close them, the bold, italic and <tt> tags will not, nor will some "block level" tags like <ol>.
A table listing all PM-approved html and arguments is available for those who wish to delve deeper.
This node is intended as a 60 second introduction to markup used here. In the interest of brevity and simplicity, some statements above are oversimplified... and some do NOT apply to the CB, for which see PerlMonks Approved Chatter HTML Tags.