Proofreading LG

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.)

The first requirement of this job is access to our Subversion repository - that's what we use for version control. This requires several steps:

1. Email your SSH public key to the editor (). This will be used to grant you access to the repository.
2. Install a Subversion client on your machine (e.g., "apt-get install subversion" for Debian users).
3. Read and follow the SVN setup procedure, which will create a working copy of the repository on your system.
4. Familiarize yourself with the description of the SVN structure in $SVN_ROOT/doc/files, especially the part related to the STATUS file.
5. Recommended but not required:
   • Join The Answer Gang. Many LG-related issues, including proofreading, are discussed in TAG. See the Members FAQ for details.
   • Create a "home" directory for yourself under the "$SVN_ROOT/p/" subdirectory of your working copy and 'svn add' it. This way, anything that you're working on but are not yet ready to release will become part of the repository - very handy in case your hard drive dies [so speaks bitter experience. :) ]

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 SVN and LG-related work, and the per-user "home" directory structure.

The Proofreading Process

Workflow

NOTE: It is critically important to save and commit ('svn ci') immediately after making any changes in the "STATUS" file. Not doing so creates conflict and wastes your or someone else's work. As you run 'svn ci', add a comment at the top that describes what you're doing and who you are - e.g.

Editing pfeiffer.
 -- Ben

Before you edit anything, run "svn update" to bring your working copy up to date and check the status of the article you want to work on.

In the STATUS file for the current issue, find the line for the article you want to edit and put your initials in the appropriate column; this tells others that you are working on it. When you're done with that section, replace your initials with an 'X' and list yourself as having worked on that article at the bottom of the STATUS file. If you have to freeze the article pending an author revision, copyright question, or some other reason, put your initials in the "HOLD" column and the reason in the "Comment" column.

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

(If you're using Vim, take a look at 'lg.vim' in the SVN 'docs/' directory; it contains many shortcuts that are useful in editing LG. The instructions for loading it are in the docs/README file.)

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.