Skein HTML Guide
prose by
sprice
24 March 2002
30 comments
|
 |
Skein Home
Author's Works
View without comments
|
HTML on Skein
|
|
|
A disclaimer to you who know html: I'm oversimplifying many things here.
[1]
This is a guide to using html to format text within the skein engine.
It's not a guide to HTML proper or full. I'm going to explain just a little bit about HTML and then list some tags that you might use everyday.
After that, I'll explain a few tags that are slightly more complicated, and then some tags that we don't allow at all.
Finally, there are some links to sites where you can learn more.
|
|
|
[ 1 ] lisa:
You could omit this first sentence. Why start with a disclaimer? The rest of the paragraph states concisely and effectively exactly what you are giving the readers. |
|
sprice:
That's a good point. I intended the second and third sentences to actually be following up on the first, but you're right-- the paragraph reads just fine without it. |
| Add comment |
|
|
|
|
|
The basics of HTML
|
|
|
HTML is at heart a system of glorified highlighters.
A web page is basically just a regular file full of text, that then has "tags" put in that set sections of the text apart to be treated differently.
Tags are set apart with characters that tell the browser not to display the tag, but to interpret it instead.
So to make multiple lines set apart a paragraph, which in the middle has a section of bold text, here's what the browser sees:
|
|
|
<p>This is a new paragraph that <b>has some bold text</b> in the middle of it.
When it hits the edge of the screen, it wraps around without my having to tell it to.</p>
|
|
|
sprice:
So the real deal won't have quite so much space between paragraphs. I'm not entirely sure why this is happening-- something to do with the way I formatted linebreaks in my code, I'll bet. |
| Add comment |
|
|
And that gets displayed as:
|
|
|
This is a new paragraph that has some bold text in the middle of it.
When it hits the edge of the screen, it wraps around without my having to tell it to.
|
|
|
Spaces are a special case.
Web browsers will ignore extra spaces, because they assume that you've formatted your code in special ways to be readable.
To get more than one space character in a row, you need to use special "non breaking spaces", which are explained in the next section.
This is also why we need to have skein treat poetry differently than prose...
besides the different ways that you can comment, skein also needs to know that it should be careful about spaces and single-line carriage returns.
[2] [3] [4]
|
|
|
[ 2 ] lisa:
Maybe just call them "line breaks" here, and "single line carriage returns" later when you're actually explaining how to use them. |
|
[ 3 ] samira:
I agree with Lisa. Since I do not have any idea what you are talking about, less jargon is good until you are a place where the jargon will be explained. |
|
[ 4 ] sprice:
Hm... that's interesting. I'd expected the "carriage returns" to actually make this more accessible, since that's a legacy term from typewriters. If it's just as jargon-y as 'line breaks', then I'll do away with it. Thanks! |
| Add comment |
|
|
A final note before describing some tags (see, there really isn't much to it!) is that most tags need to be closed and nested.
Closing a tag means that when you're done with the bold section, you need a tag </b> that says "this is the end of the bolding".
Nesting means that if you want two tags to apply to the same section of text, you need to set one entirely within the other, both opening and closing.
To apply two styles, you essentially need to say "do thing 1 to this" "and thing 2" Here's the text "end of 2" "end of 1".
[5]
See the next section for some examples of both of these.
|
|
|
[ 5 ] lisa:
Good explanation! |
|
sprice:
thanks-- a technique honed on fifth-graders. |
|
alecia:
A visual metaphor my fifth-graders and I came up with, if you're interested. Using multiple tags is like putting a piece of text in successive boxes: every "box" (every tag) has to have a top (the open tag) and a bottom (the closed tag) before you put it inside another box. It's a little confusing without the visual of a bunch of boxes that fit inside each other, but it works for them when they're checking code. |
| Add comment |
|
|
|
|
|
|
|
|
Some Immediately Useful Things
|
|
|
There are a few things that you may want to use immediately, and which may be all you need know.
|
|
|
- <p>starts off a new paragraph.
Note that skein is smart enough to interpret both line breaks and <p> tags as the start of a new paragraph...
and it will be careful to only put one paragraph break in if you put both line breaks and <p> into your submission.
|
|
|
<b>bold</b>
|
|
|
Do be careful to close this.
|
|
|
|
|
|
<i>italic</i>
|
|
|
Close this one, too.
|
|
|
|
|
|
<b><i>bold and italic</i></b>
|
|
|
Note the nesting.
|
|
|
<a href="filename.html">link text</a>
|
|
|
samira:
The examples are very helpful. |
| Add comment |
|
|
So if you'd like to post a "next" link at the bottom of a work, visit the work that you want to link to, copy the URL from the little line at the top of the browser, and put it in place of filename.html , including the "http://" stuff.
|
|
|
<u>underline</u>
|
|
|
eppy:
Completely random thing: is there a way for Skein submissions to make their links NOT look like skein's link form (i.e., just underlined rather than small-caps)? Not that I'd want to break the aesthetic unity, just curious. |
|
sprice:
Mike, I think that it's all by the stylesheet... so skein has rewritten the default link style, and you could override skein's css by wrapping stuff in your own styles. But I haven't tested this against skein's submission form. Chuck? |
| Add comment |
|
|
As someone who cares about design, I'm required to ask that you not use underlines...
because links use underlines, and it can get confusing.
But it's there for you if you want it, like in a bibliography.
|
|
|
<a name="name"></a>
|
|
|
If you'd like to link to some place within a single work, you can put in a "named anchor" like this one.
Then you can link to <a href="http://www.skein.org/filename.html#name"> and the link will jump the reader's browser to that place.
I don't recommend using this, but it's there for you.
[6] [7]
The links that I have in the opening paragraph to this page are links to anchors which are placed at the beginning of each section.
|
|
|
[ 6 ] lisa:
"Why doesn't he want me to use this, when he uses it?" thinks the reader. Do you just not think it will have a place in creative stuff, because it's more for practical stuff like this? Do you object to it on some sort of style principle, and only used it above as an example? |
|
[ 7 ] sprice:
Lisa, I have no idea why I wrote this. Good catch. |
| Add comment |
|
|
<blockquote>Text with wider margins</blockquote>
|
|
|
This will set off the section of text like a block of quotation in a properly formatted academic paper-- it will have wider margins and will have a blank line before and after.
It won't be smaller type.
|
|
|
<hr>
|
|
|
makes one of those lines that stretches the width off the page, called a "horizontal rule".
|
|
|
lisa:
Rather than describing, why not show it? |
|
eppy:
I think I understand Scott's dillema here--he's using horizontal rules to separate sections, so to include one as an example might be confusing. Maybe you should move this sucker to the bottom of the section (or the top) so the example can serve two purposes? |
|
sprice:
Mike, that's a good solution. Will do. |
| Add comment |
|
|
<br>
|
|
|
This is a line break, and is the way that you get a single "carriage return" in a document-- otherwise, if you declare a new paragraph (like with <p>) then you get a full blank line between the lines of text.
|
|
|
lisa:
I think this is understandable enough, but you could also take this text and display it as a couple of lines separated by line breaks (showing the code) and a couple of lines separated by paragraph breaks, to show the difference. |
|
sprice:
Lisa, this is some more good advice. Do you think that it would help with some of these to offset (perhaps in a table with a grey background) several examples? Some of these are near-impossible to show sensibly in the explanation, but I could set up an "example" box for those. good call. |
| Add comment |
|
|
- and > or <
|
|
|
There are a lot of characters that html "reserves" for its own use, like < and >.
If you put those characters into a document, the browser will interpret them as html itself.
For those characters, you need a special code.
One such code is a "non-breaking space", or .
[8]
That's the way that you get several blank spaces at the beginning of a paragraph, which is one way to indent just the first line of some text.
> means "greater than", and < means "less than".
[9]
|
|
|
[ 8 ] lisa:
Again, show what this looks like. Also, you might want to show how to get several blank lines in a row. |
|
[ 9 ] eppy:
I found this a bit confusing. See below. |
|
sprice:
Yes, I think I'll rewrite this paragraph. The last sentence should appear right after the "you need a special code". Lisa, that's a good point-- some browsers will take a series of <p> by themselves, some want the paragraph to have content, so a <p> is necessary. |
| Add comment |
|
|
|
|
|
|
|
|
Some Slightly More Complex Things
|
|
|
There are many more things which skein allows, but which are a bit more complicated.
The most useful of these are: lists and <font> tags.
|
|
|
To make lists, you have to do three things: tell the browser what kind of list it is, where the list is, and where to divide each of the items in the list.
There are two main kinds of lists: unordered lists (bullets) and ordered lists (numbers, letters).
|
|
|
<ul>
<li>In an unordered list, this is the first list item, with a bullet afore it.</li>
<li>and this is the second item.</li>
</ul>
|
|
|
<ol>
<li>In an ordered list, this is the first list item, with a number (one) before it.</li>
<li>This is the second item.
</ol>
|
|
|
If you'd like an ordered list to have letters rather than numbers, you can add a type: <ol type="a"> for instance.
|
|
|
Showing different fonts is a tricky business, because the computer that is viewing the work may not have the right font, and if it doesn't, it will simply guess at what it should display, or it will use the regular fonts.
Because of this, you should take care using fonts, and be very careful to close the font-ed area, or else you might affect the rest of the page (including comments, for instance).
So:
|
|
|
<font face="Times"> This should appear in times.</font>
<font face="Arial"> This should appear in Arial.</font>
<font face="Sand"> This probably won't appear in sand unless you're on a Mac.</font>
|
|
|
|
|
|
|
|
|
Some Things You Shouldn't Do
|
|
|
Finally, there are a bunch of HTML tags that skein will do its best to eradicate.
These tags are disallowed because they can be used to do Bad Things, either to the server itself or to the page that displays the work.
There are good things that can be done with them-- they're just bad for Skein's digestion.
I'm not going to explain them because you don't need them, right?
|
|
|
|
|
|
<frameset>
|
|
|
Server Side Includes
|
|
|
<script>
|
|
|
<table>, <td>, <tr>, <th> -- Tables have many legitimate uses; right now, however, they are dangerous, because improperly formatted tables will break the entire page.
In time, skein will verify HTML submitted to it.
|
|
|
<form> and all its ilk
|
|
|
<bgsound>
|
|
|
<applet>
|
|
|
<embed>
|
|
|
<div>
|
|
|
<ilayer> and <iframe>
|
|
|
<layer>
|
|
|
<span> and <style>
|
|
|
<div>, <span>, and <style> also have many legitimate uses, but when javascript and stylesheets are disabled, these tags do little but allow you to streamline your html.
|
|
|
<php>
|
|
|
<?>
|
|
|
<blink> ...because we cannot permit pure evil.
|
|
|
lisa:
:) |
|
sprice:
Chuck gets credit for that one. |
| Add comment |
|
|
<multicol>
|
|
|
|
|
|
|
|
|
|
|
|
Learn More
|
|
|
This is just the tip of a very large iceberg.
If you'd like to learn more, and learn about stuff that we won't yet let you do on skein, here are some sites to explore.
|
|
|
|
|
|
HTML at about.com - http://html.about.com/compute/html/mbody.htm - a readable guide for learning HTML, from basics on up to the tricky stuff.
|
|
|
Index dot HTML - http://www.blooberry.com/indexdot/html/index.html - The most thorough guide to HTML and browser implementation, ever.
|
|
|
Non-dithering Font Colors - http://www.lynda.com/hexh.html - A nice palette-style guide to colors, visually, in hex, and in RGB values
|
|
|
Named Font Colors - http://www.umd.edu/HTMLClasses/glossary.html#font - Though named colors are dangerous to use, here's a quick visual guide to some.
|
|
|
|
|
lisa:
In general, I think this is very readable and useful. It doesn't go into too much detail so it stays a managable size. I think the links at the end are a good idea, too. You are clear on the point that this page is only about skein features, but it's nice that you offer suggestions for how to learn more if the user's interest has been piqued. |
|
eppy:
I don't think I can be of too much help since I know HTML reasonably well already, but I did find this quite readable and got all the way to the end with no effort even though I know most of it 'n' stuff. I will mention that some of my favorite discussion sites actually have a li'l HTML guide below the submission form. But. Now, if you could just whip up a quick-n-easy XML guide, I'd be happy. |
|
eppy:
Ironic addendum: I attempted to put a <g> at the end of my last comment and Skein ate it as a HTML tag. Ha. So the guide came in useful for commenting on the guide. I will henceforth use smileys. |
|
sprice:
re: submission form, I think that's a good idea. Once the guide is in place, we should link to it from the submission form and the comment form. |
|
alecia:
Very readable, and generally very clear. With your permission, I might borrow a few of your explanations for future teaching-html documents, of which I seem to write lots, lately. A question: how did you get the tags to show up in the text? I tried to include a couple of tags in my above metaphor-comment, and skein swallowed them, even though they weren't valid html. Hmm... :) |
|
sprice:
Alecia-- I'd be honored to know that my explanations wound up in a classroom. As for the tags-in-skein issue, that's another bit of explanation that I should add to the " " section. To have a tag show up, you've got to put it into the submission (or comment) window as html already: for a p tag, it's got to appear as: <p> . Don't even ask what that looked like-- encoding a fake tag so that it gets interpreted as fake and not as either a tag to display nor a tag to read as html. ; ) |
| Add comment |
|
|
Content © copyright 2002 by Scott Price. All rights reserved.