...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.
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/ Fix links to all other 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:
Convert literal special characters to entities:
Run the article through HTML Tidy, ignoring the following errors
(occuring due to lack of HTML headers):
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.
or (old issues)
../issue###/<author>.html
author: author's_LG_name (usually the last name; see $SVN_ROOT/authors/)
title: article_title
and must be followed by a blank line.
< to <
> to >
& to &
These are especially common in inline program listings.
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