Articles and Typography: a brief manual: articles, formatting codes, typography

Introduction

Typography focuses on readability and clarity first, and aesthetics second; both benefit from simplicity. This article explains the tools available for article authors by demonstrating them in place, while promoting simplicity.

The author only controls partially the layout of the content, or the body of the article. When viewed by a reader, the page already contains several graphical elements provided by the Experts-Exchange interface, and the title is placed somewhere above, perhaps with additional information about authorship, date of publication, status of the article, etc.

The page rendering engine will also apply a style sheet, depending on the selected skin, and on the media used to access the page. If an article survives for a few years, who can tell how the style sheets will evolve?

You, the author, start by creating content. It's basically structured text, perhaps with code samples, perhaps with illustrations, perhaps with demo files. For the text content, start with simple non-formatted text, using only line separators to create paragraphs and titles. A simple text editor is sufficient.

At that point, all you need is the help page Guidelines and Help Topics for Writing Articles to learn about formatting tags and how to include code snippets and images. The present article explains roughly the same, only in more words.

Note: Please check the date of the last revision of the article. Any or even most of the information here might be out of date, as the entire article formatting process is still under revision, and will likely evolve regularly.

Character formatting

The three basic text modifications are: bold, italics, and underlined. They are produced by square-bracketed tags:

[b]bold[/b], [i]italics[/i], [u]underlined[/u]

Unsupported tags will not be ignored, but treated as text. For example, the following do not work: [sup]superscript[/sup], [sub]subscript[/sub], [large]large font[/large], [small]small font[/small]. If any of them do work, this article needs updating.

There are only a few workarounds for missing formatting options.

Superscript is limited to very few characters: ¹²³°ªº This allows however to write 2 m², or 20 °C. The superscripted numbers ¹²³ make good footnote indicators, along with *. Subscript is simply not available: water will be H2O and xi will have to do in a mathematical formula.

Large can only be achieved with CAPITALS. Main titles in capitals are a good option if two levels of titles are needed. And why not use the old-style spaced capitals, e.g.: M A I N T I T L E

Tip: Typographers never mix attributes: bold all-caps, underlined italics, etc. So if you do, make sure it conveys some added information. If all section titles are bold italics, the reader soon recognizes the visual clue and that improves fast reading.

Special characters

Full Unicode support is planned, but not yet implemented. Currently, articles and comments use the code page Windows-1252, also known as “ANSI”. This means that practically any unformatted English text can be pasted directly into the edit article input box, even if “smart quotes” — a modern name for typographical quotes — or other special characters have been used.

Note: Before 2010-01-14, the ISO-8859-1 encoding was used. Several quite common typographical signs did not register correctly, most notably the typographical quotes replacing the keyboard's straight quotes on many word processors. Articles written before that date might thus contain mangled characters () or appear to have missing quotes and apostrophes.

The ANSI encoding contains accented characters and ligatures for many Languages using Latin alphabets and the most common typographical signs:

• Spanish punctuation: ¡ ¿
• currency symbols: ¢ £ ¤ ¥ €
• typographical quotes: « » ‹ › “ ” ‘ ’ ‚ „
• dashes (‘en’ and ‘em’): – —
• bullet and daggers: • † ‡
• miscellaneous typographical signs: ¯ ¦ § ¶ µ · © ® ™ …
• superscript characters: ¹ ² ³ º ª
• vulgar fractions: ¼ ½ ¾
• mathematical symbols: ¬ ± × ÷ ° ‰
• diacriticals: ¨ ´ ¸ ˆ ˜

Not visible in the list, the required space is accepted. It must be entered as character — there is no character entity like   here — but it's stored and honoured in the layout. It's good practice to remember to use them when writing “Dr Hyde” or “2 × 2 = 4”, when you don't want a line break in the expression. On PCs, the required space is obtained with Alt+(Numpad)255 or Alt+(NumPad)0160.

Note: Many word processors change straight quotes to typographical quotes. Make sure to use straight quotes in code fragments when these are expected, and also in all formatting tags with parameters.

Typographical suggestions

This is a short manual, with no room for detailed rules. Instead, use good judgement. An article isn't a comment in a question thread, or a message on a bulletin board system. It has, or hopefully will have, a large audience and a long life. Let me spell out some obvious guidelines.

Expand acronyms, or define them early in the text. If you use many acronyms, add a glossary. The same is true for abbreviations. Surprisingly, it's faster to read “Geneva, Illinois” than “Geneva, IL”, and it avoids confusion, perhaps with an “International Labour” organization in Geneva, Switzerland. It's even faster to read `in extenso´ than `i.e.´, but that would be going too far. It is however good style to write about Mister Jones, and not about Mr Jones, but if you do, don't forget the required space.

If dates appear in the text, be certain to use unambiguous representations. Again, it's easier to spell them out: November 9th, rather than 11/9. Then again, all small numbers should be spelled out anyway. You don't have 2 things to say, but two.

In articles involving a computer languages, do not confuse that language's syntax with English. Computer manuals use a distinct font to isolate language related keywords from the text flow. Without it, it is best to place the syntactically correct version in a code tag (see below), and use friendlier versions in the text. The “before insert” event, not `BeforeInsert´, “on click” for `onClick´, “the `company name´ field of the Customers table” for `tblCustomers.CompanyName´, etc. If your spell checker ticks in, at least stop to think about it.

Paragraph formatting

The fundamental formatting tool, used long before Gutenberg, is the line break. Don't hesitate to break paragraphs up, don't hesitate to use double and triple line spacing. Simple subtitles can be created by single lines in bold or italic font.

The subtitles in this article have been created with the subtitle tag:

[subtitle]text[/subtitle]

Note that newlines have been added above to make the composition lighter and the subtitles stand out more; the tag adds a newline below. The font is already bold, but you can italicise it if you wish.

Indented paragraphs create a pre-determined amount of white-space at the left. It can be put to good use in many situations, and the indented section can contain several paragraphs.

[indent]indented text or paragraphs
[/indent]

You can use it for quotes, but there is a special —fancier— tag for those. Note that you can embedd indents (as I did just above).

There are also bullet lists and numbered steps (see below). However, even without paragraph formatting, we already have everything that is needed to produce professional looking and typographically pleasing articles. An excellent example is the Articles FAQs by B. Milne, for clarity in both content and layout.

Bullet lists

A list is created by enclosing each item in a “bullet” tag, and it looks like this:

[bullet]Item text[/bullet]

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Note: vertical space is allowed within items

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Depending on the current style sheet some spacing might get added before each item. Line breaks can be used for multi-paragraph items. Items can also contain images and code snippets.

If you want to create a compact list, do not insert a line break between the ending code of an item and the starting code of the next:

green

blue

The encoding used above is:

[bullet]red
[/bullet][bullet]green
[/bullet][bullet]blue
[/bullet]

The rules of thumb regarding line breaks and all paragraph tags are:

A line break is inserted if needed before the opening tag.

If line breaks precede the closing tag one of them is removed.

Special Tricks
¯¯¯¯¯¯¯¯¯¯¯¯

___________
¡ WARNING !
¯¯¯¯¯¯¯¯¯¯¯
Special tricks
do not improve
readability !!!

Although I'm a big fan of ASCII art and other tricks with characters, special tricks should be discouraged. They force the reader to adjust to unexpected semantics (“what do these `+---+´ and `====´ mean?”) and break the flow. Of course, this is a very old theme in typography. Reading CAPITALS or italics is harder, so they are used to slow down the reader, and attract attention. It can be argued that the silly pannel above does the same.

Whenever you are tempted to create some special effect, stop to think if there isn't a simpler and more elegant solution. Think about your readers on a portable media, or in ten years...

The few tricks I do use involve little-used typographical characters — for example as bullets, the required space, and my favourites: the low and high lines and the `em-dash´. They can create underline effects and rulers, and these are perceived outside of the reading flow, as additional clues.

Tip: Horizontal rulers should be full-width or short. Full-width is not available, so make them short.

____________________

The rest of the article shows how links, snippets, and files can be embedded in articles, and ends with two built-in typographical special effects: steps and quotes.

¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯

Hyperlinks

If you simply write an address, it looks like this: www.experts-exchange.com. The page rendering process will detect the URL and present it as a link. If it doesn't, precede the address with http or copy the complete URL from a browser address box.

If you want more control over presentation, there is the “url” tag:

[url="address"]text to display[/url]

The address (enclosed in straight quotes) will be masked (but visible in the browser's status bar on hover), and the clickable text can be a more friendly identification of the target. The target opens in a new tab (or window).

Tip: When the address is on this site, the address can be shortened, as in http:/A_2285.html — a link to the article “How to use shorthand links” by Qlemo. However, always use the full address in “url” tags.

Code snippets

A code snippet is extremely useful for ... well, code. It uses a mono-spaced font, and doesn't apply any formatting, not even line wrapping. It can also be used to present tabular or columnar data. A snippet is simply everything between the opening and closing tags:

[code]
10: PRINT "Hello World!"
20: GOTO 10
[/code]

And it looks like this:

10: PRINT "Hello World!"
20: GOTO 10

1:
2:

Select all Open in new window

^ Notice that the lines are numbered, which is useful if you need to refer to a line in your text. Perhaps a future extension will allow unnumbered lines for special cases.

The unwanted trailing white line is caused by the newline between the “code” tag and the first line of actual code. It doesn't appear at the top due to another current problem...

Warning: Currently, white lines in a code snippet must contain at least one space to be preserved; if not they will move to the end of the snippet.

Within a snippet, codes are ignored, e.g. [b] isn't bold, and [code] doesn't create a sub-snippet.
The only tag that cannot be included is the closing code tag, for the obvious reason.
 
^ the line above contains a space.

1:
2:
3:
4:

Select all Open in new window

For longer code fragments, entire modules, it's useful to handle them outside of the article flow. This is done using “embedded” snippets, basically independently stored text files, similar to document attachments, but presented in-line, using the tag:

[embed=snippet number]

The number identifies each snippet on the server, just like comment snippets, and is created by using the “Code” link below the “Article Body” text box while editing an article. The embedded box looks identical.

#Lorem ipsum
;
; dolor sit amet
; consectetur adipisicing elit
 
sed_do (eiusmod) {
    tempor = incididunt(ut)
    labore(et).dolore = magna-->aliqua
    }
 
; Ut enim ad minim veniam
;
quis (nostrud, exercitation) {
 
    ullamco!
    laboris
    nisi = ut
 
    aliquip ex~ea("<commodo> %consequat%")
 
    Duis aute {
        irure (dolor in (reprehenderit) || in (voluptate) && velit) {
            esse = cillum
            dolore(eu) += fugiat
            nulla /= pariatur
            }
        Excepteur.sint = occaecat(cupidatat non proident)
        sunt in (culpa + qui)  ; <!
        }
 
    officia = *deserunt
    }
 
!mollit-->anim?
 
; id est laborum.

1:
2:
3:
4:
5:
6:
7:
8:
9:
10:
11:
12:
13:
14:
15:
16:
17:
18:
19:
20:
21:
22:
23:
24:
25:
26:
27:
28:
29:
30:
31:
32:
33:
34:
35:
36:

Select all Open in new window

(open in new tab)

The buttons [Select All] and [Open in New Window] seen below comment snippets are not inserted, for obvious typographical reasons — they would break the flow by attracting attention. If you want to offer a full window link, this is the corresponding url, using the snippet number:

http://www.experts-exchange.com/codeSnippetPopup.jsp?csid=448575

It has been embedded in a “url” tag just below the frame. It will open in a new window or tab.

Tip: The ID number is stable even if you edit the code snippet; no need to update the “embed” tags in the article body after a revision.

Hack: You cannot embed a snippet that isn't attached to the article, but you can embed the same snippet more than once...

Images and Files

Images and Attached files are embedded like stand-alone code snippets, by using the corresponding links. Once uploaded on EE, each receives an ID number, used in the “embed” tag. For an image, it looks like this:

[embed=image number]

picture.jpg

9 KB
Jet d'Eau, Geneva

Note: Images wider than 550 pixel will be displayed shrinked to that size, and the reader will have to download the image to see the full-size version. If you are using screen snapshots, try to crop them so that they are readable in-line.

For an embedded attachment, it looks like this:

[embed=file number]

lorem-ipsum.txt

446 bytes
Lorem ipsum, etcetera...

lorem-ipsum.txt

At the moment, the file type determines the layout more than the keyword “image” or “file”, but that is susceptible to change: the file information or download link don't seem as important for images, for example. Simple illustrations would benefit from a more streamlined frame, or no frame at all, leaving only the description as caption.

Special formatting

The EE article formatting codes include two special codes, both creating some sort of indentation. Let's start with a quote:

[quote]quotation
[/quote]

The feature is meant for full text quotations, which are displayed like this:

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

— hacked from: Cicero, De finibus bonorum et malorum, 45 BC

Quotes are loosely equivalent to an indented paragraph, and could conceivable be used for that purpose. In pure typographical style, it has no frame. There are enough frames on web layouts already. The amount of indentation is controlled by the style sheet; it's currently rather small for the Expert Skin.

Tip: Start the quotation immediately after the “quote” tag. Like for the “code” tag, a new line following it becomes part of the quotation.

Steps are formatted like subtitles. They have three elements: a number, a title, and a subtitle.

[step="number" title="main title"]subtitle[/step]

All elements are optional; if the number is left blank, the overall numbering of steps is used. Note that straight quotes are used for both the number and the title.

Warning: Steps are meant to support numbers up to 99. Currently, the indentation applied by the Expert Skin is too small for two digits.

1: Lorem ipsum
dolor sit amet

With all three elements present, the layout is balanced and pleasing. It's clear that “steps” are meant to be top-level subdivisions of an article. It's possible to mishandle the template a little.

: "" title="Title Level 1"]

Without the number (number set to "") and without subtitle, it becomes similar to an indented subtitle [Note that this trick has become obsolete with the introduction of the subtitle tag.]

3: ]Subtitle only

All text until the “end step” is indented, and can be fully formatted. However, formatting codes affecting indentation cannot be embedded:
» sub-steps
» quotes
» bullet lists.

Those that don't are accepted, like images and code snippets.

By removing both the number and the title, all is left is an indented frame, in which case it makes more sense to use the indent tag, except for one special trick, namely creating an indented code frame. As they say:

""]

Always indent your code!

1:

Select all Open in new window

Conclusion

This started out as “scratch article”. I needed to test various formatting combinations, being quite frustrated with the “steps” feature, for example, and discrepancies between “preview” and “published result”. As I explained more and more things to myself in writing, and gathered reference examples, I ended up with something perhaps worth reading.

Several mistakes and omissions were pointed out by the first readers. LHerrou reminded me of the skins and their effects on layout, which led to several changes throughout the article; mwvisa1 showed me how to create compact bullet lists, a simple trick which had eluded me. I thank them both for their contributions, and also Netminder for his support both technical and personal.

I hope you found the rambling, the advice, or the examples useful. Again, please check the revision date, as this sort of information needs periodic revisions.

Success with your articles!

Markus G Fischer
(°v°)

_____
Last reviewed: 2010-05-31

Articles and Typography: a brief manual

Introduction

Character formatting

Special characters

Typographical suggestions

Paragraph formatting

Bullet lists

Special Tricks
¯¯¯¯¯¯¯¯¯¯¯¯

Hyperlinks

Code snippets

Images and Files

Special formatting

Lorem ipsum

Conclusion

articles

formatting codes

typography

Article Tips

About The Author

More Articles From harfang

Comments

Revision 2010-05-31

Add your Comment

Top Article Tips Experts

Articles and Typography: a brief manual

Introduction

Character formatting

Special characters

Typographical suggestions

Paragraph formatting

Bullet lists

Special Tricks¯¯¯¯¯¯¯¯¯¯¯¯

Hyperlinks

Code snippets

Images and Files

Special formatting

Lorem ipsum

Conclusion

articles

formatting codes

typography

Article Tips

About The Author

More Articles From harfang

Comments

Revision 2010-05-31

Add your Comment

Top Article Tips Experts

Special Tricks
¯¯¯¯¯¯¯¯¯¯¯¯