comment on

One solution might be to provide, just below the edit box, a prominent link to an even simpler guide to formatting than we already have. Yes, some people just don't care, but based on the number of poorly formatted posts, the failure of people to fix them on their own, and quotes from posts like this one:

Not everyone is conversant with HTML, and, for the occasional posting, I don't want to go through the "approved html tags" list or the like. Source: Wiki-Style syntax for posting, by Anonymous Monk

I suspect information overload is at least one reason why people can't be bothered. The key is to focus on the absolute essentials.

Here is an example of what I mean. The title is intentional and the entire post teaches only two tags at a level that I hope even the most HTML inept among us can understand. Many of you have a much better sense of humor than I, so perhaps you can improve on it:

The Braindead Guide to Formatting your Post

Welcome to the Monastery!

At Perl Monks we use a wierd combination of HTML and wiki-style mark-up to format our posts, but you can ignore that for now. To make nice posts readable by all you only need to learn two things:

how to use  and  to break up your post into paragraphs.
how to use <c> and </c> to make your code samples or terminal output readable by mere mortals.

Just to give you an idea of why this is so important, here's a post where someone forgot the formatting. Let's see if you can read it:

Hi, I'm getting a weird problem with XML::Simple; Tue Feb 17 03:40:51 2009 import_attachments.cgi: Couldn't open encma +p iso-8859 -15.enc: Tue Feb 17 03:40:51 2009 import_attachments.cgi: No such file or dir +ectory Tue Feb 17 03:40:51 2009 import_attachments.cgi: at /usr/lib/perl5/ +vendor_per l/5.8.4/x86_64-linux/XML/Parser.pm line 187 I've tried 2 ways of approaching: my $data; open(READIT,"<$file"); while (<READIT>) { $data .= $_; } close(READIT); my $ref = XMLin($data);

Source: Error with .xml file processing in XML::Simple, by Anonymous Monk

No? Its pretty hard to answer a question you don't understand, so you aren't like to get many answers. You want answers? yes? Here is what you can do to make things more readable:

At the start of each paragraph put a little
At the end of each paragraph put a little . Notice that both the start and end have a "p" for paragraph, but the start thingy (a.k.a. tag) is a little different from the end tag - it has a "/". "/" means "end".

Now for your code sample or screen output. That also has a start and an end, but we use "c" for code rather than "p" for paragraph. So to add code to your post:

add a start and end code tag pair where you want the code to go, like this:
```
<c>
</c>
[download]
```
now, cut and paste your code sample or screen output and put it between the start and end tag.

And here is what you should see in your edit box:

<p>Hi,</p>

<p>I'm getting a weird problem with XML::Simple;</p>

<c>
[Tue Feb 17 03:40:51 2009] import_attachments.cgi: Couldn't open encma
+ p iso-8859
-15.enc:
[Tue Feb 17 03:40:51 2009] import_attachments.cgi: No such file or dir
+ectory
[Tue Feb 17 03:40:51 2009] import_attachments.cgi: at /usr/lib/perl5/ 
+vendor_per l/5.8.4/x86_64-linux/XML/Parser.pm line 187
</c>

<p>I've tried 2 ways of approaching:</p>

<c>
my $data;
open(READIT,"<$file");
while (<READIT>) {
  $data .= $_;
}
close(READIT);
my $ref = XMLin($data);
</c>
[download]

And this is what the actual post looks like when you hit that "Create" or "update" button:

Hi,

I'm getting a weird problem with XML::Simple;

[Tue Feb 17 03:40:51 2009] import_attachments.cgi: Couldn't open encma
+ p iso-8859

-15.enc:
[Tue Feb 17 03:40:51 2009] import_attachments.cgi: No such file or dir
+ectory
[Tue Feb 17 03:40:51 2009] import_attachments.cgi: at /usr/lib/perl5/ 
+vendor_per l/5.8.4/x86_64-linux/XML/Parser.pm line 187
[download]

I've tried 2 ways of approaching:

my $data;
open(READIT,"<$file");
while (<READIT>) {
  $data .= $_;
}
close(READIT);
my $ref = XMLin($data);
[download]

Now isn't that better? Which version do you think is likely to get lots of readers, and lots of answers?

The moral of this story? Use and <c> tags. They are easy! And you'll get happy monks giving all sorts of answers, and that will make you happy.

Best, the Monks at the Monastery

In reply to Re: Formatting Tips by ELISHEVA
in thread Formatting Tips by lakshmananindia

Posts are HTML formatted. Put   tags around your paragraphs. Put <code> </code> tags around your code and data!

Titles consisting of a single word are discouraged, and in most cases are disallowed outright.

Read Where should I post X? if you're not absolutely sure you're posting in the right place.

Please read these before you post! —

Posts may use any of the Perl Monks Approved HTML tags:

a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr

You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)

	For:		Use:
	&		`&`
	<		`<`
	>		`>`
	[		`[`
	]		`]`

Link using PerlMonks shortcuts! What shortcuts can I use for linking?

See Writeup Formatting Tips and other pages linked from there for more info.