How to post code samples, big or small, in your Dreamwidth posts and comments

[facetofcathy]

As long as I've been using journals or forums online, I've seen variations on the conversation that goes like this:

Isn't there an HTML code that lets you post, well, HTML code?

Oh, yeah, that's the pre tag isn't it? Pre stands for preformatted.

No, that just keeps the lines from wrapping, you're thinking of the code tag.

No, pre just keeps whitespace, and it's not code, it's something else...

What our imaginary friends want is a tag that automatically escapes HTML. And they aren't imagining things, there did used to be such a code, but it's obsolete now. Neither code nor pre are a magic fix. You have to do your escaping manually.

The Basics

Escaping Code

Escaping means writing out certain symbols in the code your browser uses to print the character on the screen. This way, your browser (or Dreamwidth's posting engine) doesn't think what you wrote is code it needs to execute.

The only time you don't need to escape certain symbols in your posts is if you are using the Rich Text Editor. You don't have this option for comments, though, so knowing how to post something like, "To post a user name at Dreamwidth, type in <user name=facetofcathy>," without it coming out looking like this: "To post a user name at Dreamwidth, type in facetofcathy," might come in handy.

White Space

Usually when you make a comment or a post, extra white space—like the two spaces I can't seem to stop myself from putting after a period—get collapsed into a single space. In many types of code, extra white space is used to make the code more readable and understandable and you want to keep it exactly as is.

Again, posting via the RTE will preserve your white space and might be an option if you're in a hurry, but if you're using the comment post form you need to know some HTML to make code readable.

Most of the time the characters you need to escape are < and &. You rarely have to bother escaping the >, since escaping the opening bracket is usually enough to tell the browser this isn't code to execute. These two escape codes are easy to remember. They look like this: < for the < symbol which opens HTML tags and Dreamwidth specific tags like <user name=NAME> and & for the & that you use to start the escape codes themselves so you can show what codes to use for various symbols. lt stands for less than and amp for ampersand. Once you've memorized that, all you need to remember is the & and the ; on each end.

So to show someone the code for a Dreamwidth user name like I did above, you would replace the first bracket with the code for that symbol and type in (in a comment or in the HTML editor):

&lt;user name=NAME>

Which would show the reader this:

<user name=NAME>

That's the basics, and knowing that will let you post sample code for your readers to use for a header template, a link, a cut tag or instructions on how to make a proper em dash—whatever you might want. But some special formatting isn't a bad idea, especially in long segments of code.

Formatting with code tags.

I've been using the <code> tag throughout this post to mark fragments of code within sentences. Unless a Dreamwidth style or a users' personal settings override the default, browsers show text inside the <code></code> tags in a monospace font. That's it. There's no automatic escaping and no other formatting is applied by default.

I've seen the <code> tag used for large blocks of code, which might work in some circumstances, but for those cases, usually the <pre> tag is a better option.

Formatting with pre tags

Text inside <pre></pre> tags is also shown in the users' monospace font of choice, unless overridden by styles or browser preferences. But by default, it also preserves spaces or "white space" in the text, rather than collapsing it, and it keeps the lines of text from wrapping. This is excellent for posting things like CSS, Java Script, PHP or other type of code blocks.

A section of CSS code inside <pre></pre> tags looks like this (I use a two-space indent when I write CSS, and this is preserved here.):

#footer {
  background-color: #4C0808;
  background-size: contain !important;
  background-position: top center !important;
  color: #fff5E5;
  min-height: 5em;
  position: relative;
  margin-top: -5em;
  height: auto!important;
  }

#footer ul.navigation {
  background-image: url("/images/beta-flag.png");
  background-repeat: no-repeat;
  background-position: top right;
  background-size: contain;
  max-width: 100%;
  margin: 0;
  padding: 2.94em;
  font-weight: normal;
  font-size: small;
  text-align: center;
  border-top: solid black thin;
  }

This might look even better if I also used a <blockquote> tag as well. Remember, if your code has < in it, you still have to escape that within the pre tag.

What you see there is likely nicely contained within the entry since the code doesn't have very long lines. But many people on Dreamwidth have very narrow entry or reading page columns. They might also be reading your post on a mobile device with a narrow screen. Because <pre> doesn't wrap lines, your code will overflow the entry column to the right, and might give some readers a scrollbar.

To prevent this, you can apply a style to your <pre> tag to make it wrap the lines of text. The white space still gets preserved, and it only wraps the lines if it has to. Which means the readability might be poorer for some people, but you haven't broken their layout.

Here's the code to use that works in all modern browsers and includes a second style that works in IE 8 and older.

<pre style ="word-wrap: break-word; white-space: pre-wrap;">CODE GOES HERE</pre>

An example using a longish unbroken string and the blockquote tag to make it easier to see in the text flow (you might need to make your browser window narrower to see the wrapping):

p.kudos {
  text-align: center;
  background: url("/images/skins/iconsets/default/kudos.png") bottom right no-repeat;
  padding: 0.2022em 50px;
  margin: 0;
  min-height: 60px;
}

When a line of text wraps, it is not indented like the rest of the code, marking it out to the reader as a wrapped line.

This does a good job for a block of code that isn't so large it overwhelms the post, but when you want to post a good sized chunk of code that you want people to be able to use, you might be better off using <textarea> tags.

Using textarea boxes

Enclosing your text in <textarea></textarea> tags will put it inside a box that might have scrollbars and preserves the original whitespace but wraps the text.

Here's the example from above using <textarea></textarea> tags:

p.kudos { text-align: center; background: url("/images/skins/iconsets/default/kudos.png") bottom right no-repeat; padding: 0.2022em 50px; margin: 0; min-height: 60px; }

Some browsers let users resize text boxes like this. IE does not; so if an IE user is presented with the defualt sized box above, they can only copy and paste it into a text editor to see it all easily.

You can add sizing attributes to the textarea tag, but you need to be careful not to make it so big it breaks layouts. textarea uses cols and rows to set the size, but you can also use the style attribute to control the size.

Here's an example:

<textarea cols=500 rows=20 style="max-width: 100%">YOUR CODE GOES HERE</textarea>

Here it is in action (you might need to make your browser window smaller to see that the very wide text box never overruns the entry column): form.filters { display: inline-block; padding: 1.618em 0 1.618em 1.618em; vertical-align: top; background: transparent; border: none; margin: 0; max-width: 12em; } .filters fieldset, .filters fieldset fieldset { border: none; padding: 0; } dl.filters span.hidden { padding: 0.2022em; cursor: pointer; } .filters dt { float: none; }


By default, text inside a textarea box can be edited by the user. They can adjust the code before they cut and paste it, which is sometimes very handy. It's not all that great a format for showing code you want to discuss with others unless you take the time to size the box appropriately. For discussion or illustration purposes, the pre tag with the line wrapping style added might be your best bet.

Whatever you use to post code, don't assume that everyone has a widescreen and a style with a wide entry column. There are no "safe" widths you can display content in anymore, and line wrapping and max-width are the polite way to post.

Comments

[boundbooks]

I give this post a 10,000 out of 10 for being absurdly handy.

"What our imaginary friends want is a tag that automatically escapes HTML."

^ totally a member of this particular imaginary friend crowd :D

[facetofcathy]

I want that fantasy code too--although there is a bunch of javascript tricks that do it, and Wordpress has some as plugins. I wonder more and more if DW doesn't need to be a little more like Wordpress and a little less like LJ.

[onyxlynx]

Thank you! I don't know when I'll need this, only that I will.

[yourlibrarian]

I will have to come back to this because I, too, believed there used to be a code that would allow the posting but not implementation of code.

[facetofcathy]

The old now obsolete code is xmp. If a site/browser supports pre HTML4 it might do something if you use it, but implementation was always buggy. If you use it on DW now (in Firefox anyway) it displays escaped code, rather than displaying the code. But you could use it as a code generator with the preview function.

So if I type in <user name=facetofcathy> with the xmp tags around it, I get..

&lt;user name=facetofcathy&gt;

And if I take what that shows on preview and paste it in my comment...

<user name=facetofcathy>

I get displayed code.