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.
Paragraphs |
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 |
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:
@Bi:Fig1.png |
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. |
Or:
@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:
<U>http://www.world.wide.wait.net/index.html<U> |
A 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:
@LI: |
is slightly too long. Preferably:
@LI: |
Boxouts and Tables |
Listings longer than a couple of lines should be in a separate Listing boxout. Make 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 ... |
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 |
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:
@IT:Info
[2] Carl Corner: The Kernel -- Compiling Made Easy, |
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 |
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.
News
-
Zorin OS 17 Beta Available for Testing
The upcoming version of Zorin OS includes plenty of improvements to take your PC to a whole new level of user-friendliness.
-
Red Hat Migrates RHEL from Xorg to Wayland
If you've been wondering when Xorg will finally be a thing of the past, wonder no more, as Red Hat has made it clear.
-
PipeWire 1.0 Officially Released
PipeWire was created to take the place of the oft-troubled PulseAudio and has finally reached the 1.0 status as a major update with plenty of improvements and the usual bug fixes.
-
Rocky Linux 9.3 Available for Download
The latest version of the RHEL alternative is now available and brings back cloud and container images for ppc64le along with plenty of new features and fixes.
-
Ubuntu Budgie Shifts How to Tackle Wayland
Ubuntu Budgie has yet to make the switch to Wayland but with a change in approaches, they're finally on track to making it happen.
-
TUXEDO's New Ultraportable Linux Workstation Released
The TUXEDO Pulse 14 blends portability with power, thanks to the AMD Ryzen 7 7840HS CPU.
-
AlmaLinux Will No Longer Be "Just Another RHEL Clone"
With the release of AlmaLinux 9.3, the distribution will be built entirely from upstream sources.
-
elementary OS 8 Has a Big Surprise in Store
When elementary OS 8 finally arrives, it will not only be based on Ubuntu 24.04 but it will also default to Wayland for better performance and security.
-
OpenELA Releases Enterprise Linux Source Code
With Red Hat restricting the source for RHEL, it was only a matter of time before those who depended on that source struck out on their own.
-
StripedFly Malware Hiding in Plain Sight as a Cryptocurrency Miner
A rather deceptive piece of malware has infected 1 million Windows and Linux hosts since 2017.