...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, the issue content, documentation on the various aspects of SVN and LG-related work, and the per-user "home" directory structure.
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.
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 bulls who browse these pastures.)
(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.
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.
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:
author: author's_LG_name (usually the last name; see $SVN_ROOT/authors/) title: article_titleand optionally
summary: Short description of the article on one lineand 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
In case of any questions, problems, or errors, please contact either the proofreading team coordinator or the editor.