Re: Need examples for PerlMonks HTML Tags

[ww]

Updates, mostly acknowledged in red, throughout.

Perhaps an html tutorial would help?

http://www.w3schools.com/html/
http://www.w3.org/MarkUp/Guide/ Dave Raggett's
http://www.goer.org/HTML/

Regrettably none of those provides a one page set of examples. That, however, is scarcely a war-stopper. If you have a text editor and a browser, you can try stuff out... which is a very good way to learn.

However the minimal basics for use in the Monastery (which is PerlMonks, BTW, not HTMLMonks) are these (note that all of these except <br> are tags which -- nominally -- should be used in pairs, <open> ... </close>):

Ordinary paragraphing is accomplished with <p>...</p> tags, which renders the text within as (some might say, "conventional") paragraphs by providing a blank line between paragraphs (description of the action is NOT precise, but IMO, it's good enough for this primer re PM). That's highly recommended, as it makes your node easier to read. On the other hand, inserting a <br> tag forces a newline at that point, but does not provide a blank line. See tye's note, ++, below, urging that these NOT be used, below.   In my (contrary) view, the ability to insert a single line break is sometimes useful and presents very little hazard to readers. However, I heartily agree with his caution against use of </br>, which does NOT do what <br> does and as an afterthought would counsel against using <div.../div> tags as a substitute for paragraph tags.

<c>...</c> (and <code>...</code>) tags cause the code (or data) they enclose to appear in a distinguishable font, and may be line numbered (tye notes that numbering is NOT automatic; this is true. Turn on line numbering in Display Settings in the section on "Code Listing Setings". Note that code tags preserve your indentation, the symbols for which use of character-entities is conventional in w3c .html, blank lines and the like. A typical use would be to cut'n'paste your code into a PM node for help or review. 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
}

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.

And, now, the "Note below:" In line 11 the "&"s are NOT written as character entities (&amp;). Moreover, line 11 should be in red, but is not because there is no really straightforward, pure-html method (that I know of) to apply tags like <font color="red"...</font> inside code tags.

<pre> ...</pre> has a somewhat similar effect... BUT DON'T USE IT HERE chiefly because <pre> tags will not wrap lines that are too long for the viewer's browser window.

Lists can be either ordered (numbered, lettered) or unordered (bulleted). One of each follows; first the ordered list, created with <ol><li>...</li><li>...</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

Heading tags, <h1> thru <h6> (from largest to smallest), headline their content (Moved down, because these are DEPRECATED), as, for example

<h1>Big and bold </h1>

<h3>Not so big, but also, as is the case with h tags, bold</h3>

<h6>Pretty small</h6>

Any closing </hn> tag can be thought of as implying a line break; that is, any line begun with a heading tag will end at the closing tag (absent manipulation with css or other techniques far beyond the scope of this reply.See tye's note, below, warning against use of heading tags.

Finally, read carefully the hints which appear below the text entry box, when you're creating a node, for the character entities (the last phrase is inside <tt>...</tt> tags) 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.

Other updates: Thank you Gavin and repellent for the kind words and as to your thoughts. Re css: ikegami's cautionary note about css is accurate and relevant, but I assume that those who know enough css to apply it here, probably don't need the tips above. Re: "put that up on a node" -- perhaps, when we have a somewhat more complete and definitive guide to this topic, others of the sitedoc clan will chose to commission a faq or tut. But, nitpicking, it IS "on a node; this one. :-})

Re tye's "auto code wrapping": Bad on me. I thought I had that turned on. I didn't. Duh! Thank you.

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.

[tye]

For <h1>, I'd rather the message be "Don't use these" (as is noted at Perl Monks Approved HTML tags).

Note the red plus sign and lack of line number on the continuati­ons after wrapping is performed

Showing line numbers is not the default. For those fortunate enough to have a browser that supports soft hyphens (&shy;), "auto code wrapping" is a much nicer option and it doesn't produce any red plus signs (it can produce red hyphens but only when the wrapping happens in the middle of a long block of non-spaces).

(sometimes at unfortunat­e points, as seen in this instance.

There would likely be no "unfortunate point" when "auto code wrapping" is used but even for non-auto wrapping each user can pick their preferred line width so you shouldn't assert that the code will be wrapped at an "unfortunate" point in your specific example.

The main point for BR tags should probably also be "Don't use these". A note that </br> is a particulary bad idea might be warranted.

Update: By far the most common use of BR tags
is inappropriate.
So it seems more important to stress that
they not be used inappropriately
(to introduce line wraps within a paragraph --
I'm not sure why this is so commonly done).
Since examples were desired,
an example like Thanks,<br />Tye
would seem appropriate to me,
especially if it is noted that the use of BR tags
should be the exception and
normal paragraphs should be achieved via P tags.

[Argel]

Hmm. So how hard would it be to replace two new lines in a row with <p> tags behind the scenes so we could avoid having to actually enter them? It seems like most of the time that would match the actual intent.

[tye]

How hard would it be? The devil is in details. I've long supported taking some clues from POD and splitting paragraphs at blank lines and implying code tags for "indented" paragraphs, at least in such a way that such guessing doesn't get in other people's ways.

So how hard would it be? Nobody has implemented it yet.

[Gavin]

Very nice ww ++
While I agree with ikegami regarding CSS I think a tutorial that was pertinent to PerlMonks showing the basics is a very good idea and one that consolidates all the links that are scattered through the Monastery would be even better.

If there isn't one already perhaps there should be.

[repellent]

Thanks, Gavin. You said it best.

ww, that's great++! If you could put that up on a node, and start with the most common tags first, it will be a big help to new people joining PerlMonks.

Also, keep it simple and sparse (explain less, show more).

[doom]

Updates, mostly acknowledged in red, throughout.

Which I can't detect at all, because I use custom colors in firefox that override your attempt to make something look red.

Another helpful message, from the Department of Irony.