...making Linux just a little more fun!
The first requirement of this job is access to our Subversion repository - that's what we use for version control. This requires several steps:
There are three major areas of the repository that you will use as a proofreader: articles/, doc/, and p/. These are, in order, where the issue content is kept, documentation on the various aspects of SVN and LG-related work, and the per-user "home" directory structure.
Before beginning any work, run "svn update" to bring your working copy up to date.
Update the STATUS file. Add a line for the article and put an 'X' in the appropriate column (whatever you're working on.) The 'X' tells others that you are done with that section, and it's OK to work for someone else to work on this article. If you have to freeze the article pending an author revision, copyright question or other reason, put "HOLD" and the reason on the line.
(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.)
Run a spillchucker over the file and look for grammar and phrasing bugs. American and British spellings are both acceptable.
Clarity and conciseness are paramount; many of our readers have a limited knowledge of English (although technical explanations need to be explicit and clear regardless of the audience.) Minimize colloquial phrases and unnecessarily obscure words. Reword or explain phrases not understood across all English dialects. (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, especially those that will trip up speakers from other non-English backgrounds.
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 (this will be a red flag to the various bulls who browse these pastures.)
When all technical problems are fixed, put an 'X' in the REVIEW column. "svn commit STATUS" immediately.
Fix the hyperlinks and IMG tags to supplemental files, putting URIs in the
form "misc/author/filename". Add ALT=, WIDTH= and HEIGHT= attributes to IMG
tags (we're trying for maximum access, and there are a lot of people who
rely on these tags to provide meaningful content.) Do 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
' command from the ImageMagick package works well) to
match the specified parameters. 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 invoke
image handlers (e.g., Dillo.)
Fix links to all LG resources. Note that internal LG links, except for the ones that only exist at the root LG site (see below), must 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.
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".
Remember to "svn add" any files and directories you create and to commit your changes promptly.
Recap of the LG "sorta-HTML" article format:
author: author's_LG_name (usually the last name; see $SVN_ROOT/authors/) title: article_titleand must be followed by a blank line.
Convert literal special characters to entities:
< to < > to > & to &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
When done, update STATUS for the article by setting the appropriate columns to 'X'. Check your work into the repository by running "svn commit" (be careful not to run "svn update" instead, or you'll lose all your work!)
In case of any questions, problems, or errors, please contact either the proofreading team coordinator or the editor.