Re: Formatting Tips

[ELISHEVA]

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 <p> and </p> 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 <p>
• At the end of each paragraph put a little </p> . 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>
  

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

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

I've tried 2 ways of approaching:

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

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

[wazoox]

I'd go even farther and modify the help text right under the edit box to include your advice to use at least <p></p> and <c></c> The current help text ( If you think you're going to use <pre> tags — don't! Use <code> tags instead! This applies to data as well as code. ) is too small and not visible enough IMO.

[jethro]

My main concern with that sentence "If you think you're going to use pre tags..." is it talks only to the few who would have thought of using pre tags here, or at least KNOW what a pre tag does. To tell you the truth, if I hadn't read that sentence on perlmonks so often, my knowledge about a pre tags would still amount to zero.

That sentence should simply be "Use code-tags for code and data". Not as clever or witty but to the point.