Formatting your text


Formatting your Text?

Submit articles as plain text files, saved as “Western (ISO Latin 1).

Tags are used to emphasize the text in certain passages (titles, listings, images, etc.). Below is a brief outline of the formatting tags.



The various text elements, such as titles, normal body text etc, are separated by special tags. Tags always use the following format @XX:. Our texts comprise the following major elements:

  • A top line that describes the subject (@D:)
  • An imaginative main headline/title (@T:)
  • An intro (@V:)
  • Author name (@A:)
  • The text itself (@L:)
  • Subtitles (@ZT:)
  • An author boxout with a short c.v. (@IT:)

You only need to insert a tag when the format changes. If you have several paragraphs of body text that follow each other, a single @L: at the start of the line will suffice. Of course, paragraphs can comprise several lines of body text. A paragraph break will not occur until indicated by a an empty line (newline character) or the next tag occurs.

An article should include more than just text, please include screenshots, boxouts, tables, or diagrams. These items are movable elements, so you cannot refer to them by saying "as the picture shows" or "as shown below.” Instead, you will need to refer to a Figure by number. Identify your images as "Figure X:".



Images make it easier for the reader to understand what will mainly be complex technical topics. While you are writing, you should be thinking about how you can make it easier for your readers to understand you by adding screenshots or other visual elements.

SVG is a good format for diagrams or flowcharts. If you use a different format, ensure that you enclose both the source format and a PS, EPS or PDF version. JPEG and TIFF are suitable for photos.

PNG and GIF are suitable for screenshots. When you create a screenshot, make sure that it contains only the relevant screen areas, instead of empty space. Try to select a color scheme that has good contrast between the background and the font colors so it is easy to read. Remember that fonts – especially menus – need to be legible in the printed magazine, so try not to include too much in a screenshot. 

Figures are indicated as follows:

 @B:Figure 1: The racing track game in action on the desktop.

The caption should describe what you can see in the picture and emphasize the important aspects of the picture. Use a sentence like the following to refer to the figure in the body text:

@L:Figure 1 shows the simulation of a 90 degree turn as a desktop game written in Go with racing animation.


@L:...the simulation of a 90 degree turn as a desktop game written in Go with racing animation (Figure 1).


Tags in the text body

Body text always begins with the @L: tag. Tags always refer to the entire paragraph that follows.

Text markups such as bold, italic, and code font are indicated by tags in angled brackets. Short commands, such as "rm -rf *" or file and directory names should be placed in the body text as follows <C>Code<C>. This will appear as follows: rm -rf *. Other possible markups are <I>italics<I>, "quotes" or in extremely rare cases <B>bold<B>. You can even add URLs to the body text, using the <U> tag to indicate them, as in:


Listing comprising only one or two lines can be introduced by the @LI: tag on a separate line of body text. Listings are printed in a non-proportional font with 41 characters per line. If the line happens to be longer, make sure that you separate the line. Use §§ to indicate the line-wrap (this character should not occur in normal listings). For example:

 ./configure --with-idea --prefix=/usr --with-rsa

is slightly too long. Preferably:

 ./configure --with-idea --prefix=§§
 /usr --with-rsa


Boxouts and Tables

Listings longer than a couple of lines should be in a separate Listing boxoutMake sure that you supply only complete (that is executable) scripts and sourcefiles, as they will be made available to our readers.

Boxouts always have a title(@KT:). Normal text in a boxout is boxout text (@KL:). Listings in boxouts are still formatted using @LI::

@KT:Listing 1: xy.c
 #include <stdio.h>


In addition to code, boxouts can contain additional information, such as glossaries, interviews, or a different aspect of the main topic that does not fit into the main body of text.

Tables are similar in appearance to boxouts and start with the @TT: tag. The individual lines of a table must occupy one line of your source text; the columns should be tab-separated:

@TT:Table 1: Character
 @TL:Column1 Column2

You can save tables as spreadsheets (.csv or similar) to help ensure the correct formatting.

The Info section includes references to URLs or literature. Again these can take the form of a boxout that is introduced by @IT:Info where the references are placed in an @IL: area:

 [1] Online Manual for Penguin Breeders:

[2] Carl Corner: The Kernel -- Compiling Made Easy,
 Linux Magazine Issue 22, p45

Use square brackets [1] in the text to refer to a footnote in the Info section.

The author boxout is similar to the Info boxout and is introduced by:

@IT:The Author
 @IL:Mary Anybody enjoys writing...


Typical Problems

  • too many abbreviations (e.g., etc.)
  • over use of the passive form
  • changing the narrative perspective too often (one, you, I, we)
  • not enough illustrations, no captions, or captions not descriptive enough
  • figures, tables, boxouts not referenced in the text
  • no subtitles, or subtitles too short
  • file formats, such as HTML or PDF, instead of plain text
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters

Support Our Work

Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.

Learn More