First steps

So you've decided to become a proofreader for the Linux Gazette. First, thank you for offering your time and effort – it's sincerely appreciated! You'll be doing something great for the Linux community, and helping yourself by learning the job at hand as well as gaining knowledge about Linux itself: part of proofreading for LG involves technical review, however much of it you can do (there are other mechanisms in place to back you up, so don't worry about being perfect in this regard.)

Recommended but not required:

• Join The Answer Gang. Many LG-related issues, including proofreading, are discussed in TAG. See the Members FAQ for details.

There are three major areas of the repository that you will use as a proofreader: articles/, doc/, and p/. These are, in order, the issue content, documentation on the various aspects of LG-related work, and the per-user "home" directory structure.

The Proofreading Process

Workflow

TBA

Technical review

Make sure the title and/or first paragraph accurately describe the scope of the article. Readers count on these to determine which articles are relevant to them. Reword the title and first paragraph if necessary, or contact the author to have them do so.

Is the article technically correct? Most importantly, does it contain bad advice that would make readers shoot themselves in the foot? If you believe that a part of an article is incorrect but cannot fix it yourself, add a ***FIXME*** tag at the beginning of the problem section, and put a HOLD on the article with "Technical review needed" as the reason in the STATUS file (this will be a red flag to the various and multiple bulls who browse these pastures.) Until that flag is cleared, the article will not be released (i.e., published.)

If in doubt, as always, contact editor@linuxgazette.net . I'll be happy to steer you to the most appropriate staff expert for the given content.

Style Guide

First, fix grammar, spelling, and punctuation errors, with an eye to improving clarity and readability. If a passage is unclear or has clear structural errors, you can rewrite it, using a bit of caution to respect the author's "voice" (manner of speaking/writing). You can also tighten wording (omit needless words, or substitute a better one) – but you should avoid rewriting a passage merely because you feel you could say it better. That may be true, but it is not your article. Your aim should be to produce quality copy, but the author should be able to recognize his/her own writing style, appearing to best effect.

The Gazette is published in (American) English, but we're not fanatical about usage as long as the content remains readable. As you edit, remember that many of our readers are non-native English speakers – and keep it readable. Colloquialisms common in British or American usage are generally OK, but require some judgement (E.g., "petrol" is OK, "dodgy" is borderline, but "trolley" for a wheeled cart had better be explained.) If the wording sounds really foreign (e.g., "Indian English", "Dutch English", "Russian English"), try to fix the most jarring constructions.

In cases of serious doubt – i.e., you consider the grammar, structure, etc. to be so broken that you cannot resolve the problem/ambiguity – feel free to contact the editor-in-chief.

HTML check

Fix the hyperlinks and image links to supplemental files, putting URIs in the form "misc/author/filename". Add "alt=", "width=" and "height=" attributes to image tags by running the "image_size" utility (in "bin/" in the SVN working copy.) Check the images themselves: if the author has sent us a huge (or tiny) image and resized it with the above tags, please resize the image itself (the 'mogrify -geometry WxH filename' command from the ImageMagick package works well). Also, check to see that the image type is correct by using the 'file' command; sometimes, we get PNGs with a ".jpg" extension and so on, which causes problems for browsers that have to delegate to image handlers (e.g., Dillo.)

Internal LG links, except for the ones that only exist at the root LG site (see below), should be relative rather than absolute (i.e., '../121/smith.html', not 'http://linuxgazette.net/121/smith.html'.) As well, all links to an index must be to 'index.html', not to the directory. These rules are necessary to make LG readable offline.

Link to an article in the same issue:

'<a href="[filename].html">'.

Link to an article in another issue:

../###/<author>.html
or (old issues)
../issue###/<author>.html

Link to a global file:

../faq/index.html

Absolute links are required to the search page and to CGI scripts since they don't work on mirrors or offline. *Occasionally* an absolute link to the home page is necessary, usually labelled "main site".

Recap of the LG "sorta-HTML" article format:

• No HTML headers or footers
• The LG "header" consists of two required and one optional line:

  author: author's_LG_name (usually the last name; see $SVN_ROOT/authors/) title: article_title
  

  and optionally

  summary: Short description of the article on one line
  

  and must be followed by a blank line.
   

• No <h1>s (reduce to <h2>s)
• No in-line CSS
• Minimize the number of tags wherever possible (get rid of &nbsp;s, etc.)
• Paragraph headings should be <h3>s
• Each paragraph should be enclosed in <p></p>

Convert literal special characters to entities:

    < to &lt; 
    > to &gt; 
    & to &amp; 

These are especially common in inline program listings.

Run the article through HTML Tidy, ignoring the following errors (occuring due to lack of HTML headers):

line 4 column 1 - Warning: missing <!DOCTYPE> declaration
line 4 column 1 - Warning: plain text isn't allowed in <head> elements
line 4 column 1 - Warning: inserting missing 'title' element

In case of any questions, problems, or errors, please contact either the proofreading team coordinator or the editor.