Beefy Boxes and Bandwidth Generously Provided by pair Networks Joe
Perl-Sensitive Sunglasses
 
PerlMonks  

RFC: Monastery Markup Introduction

by ww (Bishop)
on Mar 07, 2008 at 18:59 UTC ( #672852=monkdiscuss: print w/ replies, xml ) Need Help??

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. :-)

This is an expanded and edited version of my reply to Need examples for PerlMonks HTML Tags, from which I have attempted to remove those of my personal prejudices which contravene Monastery doctrine (for example, the deprecation of the break tag).

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>
:

  1. line 1 of list
  2. line 2 of list
  3. 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 (&amp;).

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.

Comment on RFC: Monastery Markup Introduction
Select or Download Code
Re: RFC: Monastery Markup Introduction
by almut (Canon) on Mar 07, 2008 at 19:31 UTC

    Nicely done, but I think it's still too long for those who tend not to read the docs if there's any way around it...  In particular, I'd mention <c>...</c> together with <p>...</p> right at the beginning. In my opinion, they're the two most important tags, by far, because with those tags alone, every first-time poster can create legible, properly formatted nodes. Everything else is more or less nice-to-have, and can be learnt later step by step as people become more familiar with the Monastery...  Just my two cents.

      Excellent thought!

      Perhaps the "too long" could best be ameliorated with an initial heading on the order of Must knows with a section which would cover only para and code tags; followed by the balance of the Textual.... section and the caveats?

      I also like blokhead's table but wonder if that might not work even better as the foundation for replacing the existing Perl Monks Approved HTML tags; an observation I make as one who works with .html much of the time and who finds that table (as it stands) lacking for those without .html background, "whose name (it appears) is multitude."

        ... with an initial heading on the order of Must knows ...

        Yes, that's exactly what I meant. I think it should leave no doubt from the structure of this intro what is compulsory reading (for first-time posters not to annoy their audience right away), and what is optional reading that you can come back to at some later time, in case things should appear too confusing now...

Re: RFC: Monastery Markup Introduction
by blokhead (Monsignor) on Mar 07, 2008 at 20:09 UTC
    When I saw Need examples for PerlMonks HTML Tags, I pictured something much more visual and "cheat sheet"-like:

    PM Markup:Result:
    paragraphs / line breaks
    <p>first paragraph</p>
    <p>second paragraph</p>
    

    first paragraph

    second paragraph

    link to nodes by name
    Have you tried [Super Search]?
    
    Have you tried Super Search?
    Thanks for your help, [tye]
    
    Thanks for your help, tye
    Thanks for nothing, [tye|wiseguy]
    
    Thanks for nothing, wiseguy
    link to nodes by ID
    Please consult [id://3989]
    
    Please consult Super Search
    other kinds of links

    (more info)

    Check out [pad://NodeReaper]
    
    Check out NodeReaper's scratchpad
    Did you try [http://google.com|this]?
    
    Did you try this?
    Did you check [doc://perlfaq]?
    
    Did you check perlfaq?
    including code in text
    The result is in <c>$array[0]</c>
    
    The result is in $array[0]
    The code should read:
    <c>
    use strict;
    use warnings;
    
    my @array = ("Hello world\n");
    if (@ARGV) {
        print $array[0];
    }
    </c>
    
    The code should read:
    use strict; use warnings; my @array = ("Hello world\n"); if (@ARGV) { print $array[0]; }
    text/font formatting
    This will be <b>bold</b>
    
    This will be bold
    This will be <i>italic</i>
    
    This will be italic
    This will be <tt>fixed width</tt>
    
    This will be fixed width
    quoting / indenting
    A wise monk once said:
    <blockquote>
    "Indenting is good"
    </blockquote>
    .. and I agree
    
    A wise monk once said:
    "Indenting is good"
    .. and I agree
    lists
    My favorite flavors are:
    <ul>
    <li>vanilla</li>
    <li>chocolate</li>
    </ul>
    
    My favorite flavors are:
    • vanilla
    • chocolate
    How to make toast:
    <ol>
    <li>insert bread</li>
    <li>press button</li>
    </ol>
    
    How to make toast:
    1. insert bread
    2. press button

    I adapted the tags you decided to include in your introduction.

    This node is intended as a 60 second introduction to markup used here.
    If so, then it is much too long IMHO.

    Update: missing </pre> tags inserted, according to GrandFather's suggestion.

    Update 2: demonstrated whitespace preservation of <c> tags. Thanks to kyle for that suggestion.

    blokhead

      I recommend, as ww has suggested, that you:

      consider turning on (checking) the "enforce" and setting "Reporting Level" and its "Preview" to the max values

      then review your node. ;)


      Perl is environmentally friendly - it saves trees
      Magic blokhead ++ Just the job, you must have been reading my mind or vice versa.

      I'd recommend the code example include some indentation so that it's clear <code> behaves like <pre> in this respect.

      use strict; use warnings; if ( ! @ARGV ) { die "not enough arguments\n"; }

      I'd hate to see <blockquote> in the middle of somebody's code.

      The only addition that I can think of would be an example to an external link for example.

      <a href=" http://nbpfaus.net/~pfau/cbhistory.cgi?site=PM "> CB History </a>

      Which would display

      CB History
        ++

      Very, very nice! I really think this is the way to go! If we want users to actually read something then it needs to be concise and easily accessible. Most people have used references and one page "cheat sheets" before so I think this format will feel very natural and likely see much more use.

Re: RFC: Monastery Markup Introduction
by hsmyers (Canon) on Mar 08, 2008 at 18:47 UTC
    Interesting---it takes three screens to see your entire post at the same time. Was this intended?

    --hsm

    "Never try to teach a pig to sing...it wastes your time and it annoys the pig."
Re: RFC: Monastery Markup Introduction
by Bloodrage (Monk) on Mar 09, 2008 at 07:55 UTC

    Depending on what you read, where you were taught or how you write your own CSS; <i>...</i> and <b>...</b> are to some degree interchangable with <em>...</em> and <strong>...</strong> respectivly.

    YMMV

      I think that they are interchangeable to some extent.

      The difference is in how they are interpreted by different browsers and to a greater extent speech programs and I think Braille bars for the visually impaired etc.

      You are correct, within the context of the conditions in your initial clause; in fact, one of my (test) browsers renders <i>...</i> text in boldface, pointing up the fact that Gavin's reply below is a more precise characterization.

      For reference, however, this, from w3c (at http://www.w3.org/TR/html401/present/graphics.html#h-15.2.1):

      Rendering of font style elements depends on the user agent. The following is an informative description only.

      TT: Renders as teletype or monospaced text.
      I: Renders as italic text style.
      B: Renders as bold text style.
      BIG: Renders text in a "large" font.
      SMALL: Renders text in a "small" font.
      STRIKE and S: Deprecated. Render strike-through style text.
      U: Deprecated. Renders underlined text.
      (Emphasis in original; the draft .html 5 language is different.)

      You will notice that w3c deprecates the last two, whereas PM does NOT (though I suspect you will find a consensus here against the use of U). Further, since you mention CSS, the word "style" in the w3c statement is NOT a reference to CSS.

      And -- at this time -- the specialized sub- and super-set of .html 4.01 used in the Monastery does NOT accept .css entered in an input box.

      To demonstrate:

      <p style="font-style: italic;">This will NOT render as italic.</p>

      This will NOT render as italic.

      In fact, if you have "enforce" turned on and "reporting" set high in Display Settings (see above), you will see the second <p style="font-style: italic;"> highlighted (in my case, in a light grey) as non-conformant.

      Of course, you can impose your own preferences on rendering by supplying .css in your personal style-sheet, but there's no assurance that other readers will have it rendered as you do.

Re: RFC: Monastery Markup Introduction
by xdg (Monsignor) on Mar 10, 2008 at 19:01 UTC

    Perhaps this goes beyond "introduction", but I sometimes find it useful to put <p> marks inside <li> marks if the list items are full sentences that might span lines. For example:

    <ul> <li><p>The quick brown fox jumped over the lazy dog and then jumped ba +ck again once or twice, which really annoyed the dog.</p></li> <li><p>Another paragraph of long text which has no point but to show o +ff how list paragraphs look when composed of a long sentence that mig +ht span several lines on the screen and having a little extra white s +pace would be a kindness</p></li> </ul>

    Result:

    • The quick brown fox jumped over the lazy dog and then jumped back again once or twice, which really annoyed the dog.

    • Another paragraph of long text which has no point but to show off how list paragraphs look when composed of a long sentence that might span several lines on the screen and having a little extra white space would be a kindness

    -xdg

    Code written by xdg and posted on PerlMonks is public domain. It is provided as is with no warranties, express or implied, of any kind. Posted code may not have been tested. Use of posted code is at your own risk.

Re: RFC: Monastery Markup Introduction
by Argel (Prior) on Mar 10, 2008 at 19:11 UTC
    Nitpick: "Deprecated" should be replaced with "strongly discouraged" so that it falls in line with what the Perl Monks Approved HTML tags document actually says. Nowhere in that FAQ does it say that any tags are deprecated and I do not think this FAQlet should contradict the more authoritative document.

      Thanks for comment (++) because the more precision we can manage in the end product (within the limits of the brevity espoused by other respondents), the better that product will serve us.

      I think your "nitpick" is well taken because, as I understand it, the most common IT useage is in the sense Don't use this, because the "command" or "statement" may become obsolete.

      I'm torn, however, about adopting that suggestion and hope others will weigh in because "discouraged" is the first (3rd overall, with the first two labeled "archaic") current definition for "deprecate" in Merriam-Webster's book while Cambridge ("Advanced Learners Dictionary") cites "disapprove" first.

      :-) Aside: Personally, I'm much taken by the second archaic sense:

      b: to seek to avert
      <deprecate the wrath…of the Roman people — Tobias Smollett>

      ...if we just s/Roman people/Perl Monks/

      And re the consistency argument, we're already inconsistent: Perl Monks Approved HTML tags does indeed discourage or strongly discourage some markup, including <br> while Writeup Formatting Tips specifically encourages it:
      "Use a <br> or a <br/> to get a line-break...."

        Well, I'm not torn up about anything! That's because "deprecated" in computer jargon means that that feature (or program) is going to be removed in a future version.

        I think the intent is that using <br> in place of <p> is discouraged so I do not see any inconsistency in those two documents since both suggest using <p> tags for paragraphs.

        Nice try but you will have to do better than that!! :-)

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: monkdiscuss [id://672852]
Approved by almut
Front-paged by Old_Gray_Bear
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others taking refuge in the Monastery: (7)
As of 2014-04-18 23:23 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    April first is:







    Results (472 votes), past polls