Beefy Boxes and Bandwidth Generously Provided by pair Networks
laziness, impatience, and hubris
 
PerlMonks  

Improving access to "Writeup Formatting Tips"

by nedals (Deacon)
on Jan 07, 2003 at 22:58 UTC ( #225103=monkdiscuss: print w/ replies, xml ) Need Help??

My memory is not as it used to be! I find myself writing or editing a post and cannot remember the syntax to insert a node or cross out a portion of a previous post. Worse than that, I cannot remember where I found the post that tells me how to do this or that. So I would ask that the-powers-that-be add the Writeup Formatting Tips link above/below/near the textarea edit element whenever it is displayed.

The current "Writeup Formatting Tips" is barely adequate to compose/edit a post. I've written a new version, heavily plagerized from other posts on this site. After the monk's review, I would ask that this replace the current version.

On occasion there is a short list added below the textarea element. So, alternatively, this list, edited somewhat, could be added to all instances of the textarea element.

This is not supposed to be a tutorial, simply a reminder for newbies, infrequent users, or for those who have lost their marbles... memories.

Writeup Formatting Tips (revised)

Writing a new (or a reply) node:

Are you posting in the right place? Check out What section should I put this in? to know for sure.

Please, please use a descriptive Title when posting things. "Need help with this script" is not a good title!

Always, always use the "Preview" button before you "Submit" your post. This will give you an opportunity to edit if you don't like what you see. Note that, once posted, you can edit your reply to a thread, but you cannot (in general) edit a root node you create. See How do I change/delete my post?.

  • Posts may use any of the Perl Monks Approved HTML tags.
  • Carriage returns will be stripped from your submission except within the <CODE> sections.
  • Use <P> to insert paragraph breaks. Generally you will not need to use the <BR> tag since your text will wrap atomatically. If you do need add a line break, don't use <br>, use <br/> instead and then only sparingly.
  • Don't get too carried away with font tags. Plain text is sufficient for just about anything. If you really want to add formatting to your text, <STRONG> and <EM> should be sufficient for most purposes.
  • <pre> tags should be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and probable editor intervention).
  • Use &lt; and &gt; to make the < and > characters, and &#091; and &#093; to make the [ and ] symbols when used outside the <code> tags.
  • When posting a very long node use a <READMORE> at a good point for a break in the node.
  • Use the <CODE> and </CODE> tags around any code sections. Your program will display in a monospaced font and all line breaks will displayed where you put them.
  • Do not use tabs within your code for indentation. Use 2 or 3 spaces instead.
Linking to other nodes: Editing your node:

As an unwritten custom, Monks don't like to delete info. A post you made may already have comments from others. Rather than leave bad info out, it's customary to correct any bad info, and leave an indication that you did so with either a <strike>through</strike> or a brief note labeled <strong>Update</strong> at the bottom.

Comment on Improving access to "Writeup Formatting Tips"
Re: Improving access to "Writeup Formatting Tips"
by ehdonhon (Curate) on Jan 07, 2003 at 23:07 UTC
    # To link offsite use standard HTML <A HREF=http://mypage.org>Link text here</A>.

    No, use this:

    [http://mypage.org|Link text here]

    instead.

Re: Improving access to "Writeup Formatting Tips"
by graff (Chancellor) on Jan 08, 2003 at 03:58 UTC
    Your post happens to demonstrate one formatting tip that seems to make a difference on my linux-based Netscape 4.78 browser:

    Whenever I view a post with a <UL> or <OL> construct, and the close tag for the construct is followed immediately by text (without a <P> tag in between), the last list element and the first line of text overlap on the same line of the display, and are not readable -- I need to view the page source to see what was actually written. (Oddly when I reply to such a node, the same markup displays correctly, no problem.)

    In any case, I have gotten into the habit, when using the list elements in my own posts, of always putting a <P> right after the end of each list -- this always assures a good display.

Re: Improving access to "Writeup Formatting Tips"
by agentv (Friar) on Jan 08, 2003 at 05:04 UTC
    ...a find distillation.

    And much thanks from those of us who rely upon the net to serve in lieu of hippocampus destroyed during college days.

    Contrary to popular belief, I do not actually tattoo important facts on my arms and calves.

    ...All the world looks like -well- all the world, when your hammer is Perl.
    ---v

Re: Improving access to "Writeup Formatting Tips"
by Louis_Wu (Chaplain) on Jan 08, 2003 at 08:48 UTC
    I like your idea. Bug any members of the Site Documentation Clan whom you see in the CB. I'm looking at the Writeup Formatting Tips node, and I can edit it, so I know that the SDC is capable of dealing with this.

    A few suggestions for more linkage:

    • New Link Tags in addition to what you gave
    • Site Doc Wishlist, June 2001 is quite old, maybe we should start a new one. ('Course, that implies that I have time to spearhead a wishlist project. Maybe I should keep quiet.)

    The item about pre tags (<pre> tags should be avoided. If they must be used, ...) leaves room for the uninitiated to use pre tags when they think it's appropriate. I personally don't know of any situation where it is appropriate, so I think that a narrower definition of 'appropriate' (with examples comparing pre and code usage) would be helpful.

    I'll have more to say tomorrow, it's almost 1am here and my brain is playing hopscotch with my eyeballs.

Re: Improving access to "Writeup Formatting Tips"
by hawtin (Prior) on Jan 08, 2003 at 20:50 UTC

    As others have said a fine summary.

    To follow up on the comment from graff (and also your <br/> comment). You post did render oddly in my (admittedly old) browser, personally I would have added a statement like:

    • Your HTML will look better in a wider range of browsers if you follow the strict XHTML rules, that is always open and close tags (e.g. use <p>Paragraph Text</p> for paragraphs, <li>Item Text</li> for list items and <br/> for breaks).
Add HTML-Entities - Re: Improving access to "Writeup Formatting Tips"
by metadoktor (Hermit) on Jan 09, 2003 at 01:43 UTC
    If someone could please also add a link to all of the HTML-Entities like &# 91 (left bracket) and &# 93 (right bracket). That would be fantastic!

    metadoktor

    "The doktor is in."

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others perusing the Monastery: (5)
As of 2014-10-25 12:08 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    For retirement, I am banking on:










    Results (143 votes), past polls