Index:
Abstract:
This is a guideline for the LinuxFocus editors and describes a
bit how an editor for LinuxFocus might want to work and what
he/she should do, what programs to use etc..
I call the "soft part" those things that are not that easily to define and where different people will have different opinions about. It is the management part if you like. The other part is the technical part.
As editor you are a little bit like the manager of a small business. You will have to take initiative, coordinate things and try to motivate other people. Motivation is especially important as all of the people working together with you are working for free. Editor means also that you will usually have to do the work that nobody else wants to do.
The free software world has lots of people and it is actually not difficult to find "friends" over the internet that will support you as an editor. There are however a few things to keep in mind. As everyone is working for free it means also that everyone will come and go when he/she likes. The nice people will tell you when they want to leave but some will just die away without saying goodbye. This is annoying but you will have to cope with it. Nobody wants to work for a project where nothing is going on. So, keep your people informed about new things and what is coming next. Never complain about the work that someone contributed. A translation might have been of bad quality and caused a lot of re-work for you but it was probably still easier than translating all from scratch.
After working for some time you will find that you have a lot of people doing close to nothing and only a few that really do something. Don't be frustrated about this. This is the way it is.
The free software world is ideally suited for projects that are modular and consist of small parts which can be distributed. There are however normally a few things which can not be distributed. These are the things that you, as an editor, definitely have to do.
You will have to put all the articles together, check for correct links, and do the updates on the server. You will also have to work on the articles on which for some reason nobody else wants to work.
LinuxFocus is definitely not only translation work. There are a lot of things to do. You can write small programs to automate things. You can invent new layouts, you can maintain a news section at LinuxFocus, you can write your own articles, you can do a lot of things. Especially writing your own articles can be a very interesting thing to do. Just be a bit creative.
This describes the new file system structure. In the past there have sometimes been other policies. This is valid for all new articles. All languages should try to follow this structure to avoid chaos. Many tools for creating dynamic links (e.g links to available languages in each article) depend on this file structure. You should also use the english names for file names and directories.
The directory /common contains files shared by all languages. This has 3 purposes:
common/
|
|-- mirrors.html Index of lf mirror sites
|-- lfteam.html An up to date list of the contact persons for LF.
|
|-- images/ Article illustartions (title picture) and
| | images of the authors go here.
| | Also the naviagation bars can be found
| | in this directory.
Images that are slightly different
from language to language will use
the suffix -en, -es, etc.. to specify
the the appropriate language. For
example: Bottom-en.gif, Bottom-es.gif,
etc... Photos of authors will be
named according to the first and second name
of the author.
| |-- articleXXX/
Some articles about graphics come with a lot of
pictures specific to this article.
| ....
| |
| `-- flags/
The flags of the different nationalites (mostly
used from the www.linuxfocus.org/index.html page and
probably not important to you.)
|
|
`-- src/
|-- articleZZ Code examples and other stuff that is specific to
| a certain article.
....
|
|
`db/ The directory containing the Linuxfocus database system
From 2004 on there is also a common/images2 and common/src2 because the common/images directory was getting to big. So bit that the search time in an ext2 filesystem started to degrade. There are of course filessytems such as ReiserFs which would not have this problem but most Linux servers will use ext2/ext3. In other words all images from March 2004 onwards go to common/images2.
There is 1 directory that are especially important to you as editor:
/doc contains documents of relevance for editors,
for example proposals and guidelines like this one.
/doc/nextissue.html is always a pointer to the next issue.
Articles are named as articleXXX.html where XXX is a unique number.
LinuxFocus articles come in 2 formats. The final article
which is called articleXXX.shtml. This is a machine generated
file. You need not to edit this file. You work on files called
articleXXX.meta.shtml. To get articleXXX.shtml you run
lfparser -l fr articleXXX.meta.shtml >
articleXXX.shtml
or
lfparser -l fr XXX
Replace fr (French) with the right option for you language.
New articles are .shtml instead of .html because we use now serverside includes (SSI) to generate the list of available languages at run time when the reader clicks on an article..
Articles are stored per language section and they are stored 2 levels down from the web-server root. So to get to the common directory you will need to use ../../common in a html-HREF. The directory structure per language looks therefore like this. (note the names are alwasy english):
YourLanguage
|--MonthYYYY/ The directory of an issue (e.g November2003)
| |
| articleXXX.meta.shtml The meta file from which the article is generated
| (the meta.shtml is only stored here to not get lost)
| articleXXX.shtml The actual article shown to our readers
| ...
| index.shtml The index of this issue
|
|-- index.shtml The door to your laguage section.
|
|-- indice.html Information about the different indices. Just copy the
| file from English and translate it.
|
|-- issues.html A long list of all articles.
| There is an online tool to generate this file.
| it is called lfthemes.
|
|-- map.html A site map (eg. you can list links to the different issues).
|
|-- aboutus.html Description of your team.
|
|-- Archives/ Tar-balls. There is an online tool to generate the archives called
| lfarch.
|-- Links/ What ever you like. You can also redirect to English by
| putting a index.shtml file in this directory and write in this
| index.shtml: <!--#include virtual="../../English/Links/index.html"-->
|
|-- News/ Here you could start a news section. Normally just redirect to
| ../English/News if you do not want to maintain this.
|
|-- Search/ Normally just redirect to ../English/Search unless you want
| to translate this page too.
|
|-- Themes Created by the lfthemes program.
|
`-- db/
|
titles.txt A text file to generate translated versions of issues.html and Themes
with the lfthemes program.
When you receive a contribution you should check it a bit to see if it at least fulfills a minimum quality standard. Normally all links are wrong because the person sending in the article had stored the article in his/her local disk in a different way. I usually run the command
tr_llnk -A articleXXX.meta.shtmlon the article to see what links it has. Most likely you will have to edit the links. tr_llnk is part of a perl module called HTML::TagReader available from http://pepper.linuxfocus.org/~guido/.
Next check the correctness of the HTML code with
tidy -e articleXXX.meta.shtmlWhen you have edited the article and corrected the faults you can run
tidy -im -raw articleXXX.meta.shtmlto indent the HTML code and make it look nicer.
After the above automatic checks you should read the article and correct mistakes a bit. This task can also be distributed to other people in your team.
You should prepare a mail when new people come. Tell them
what they can do and how to work. They can also subscribe to
the mailing list by sending an e-mail to
majordomo@linuxfocus.org. One should write the following text
into the body of the mail (subject can be empty):
subscribe listname
end
Example, subscribe to the list deutsch@linuxfocus.org:
subscribe deutsch
end
To remove a subscription:
unsubscribe listname your@e.mail
end
The actual mailing list (the address to use when sending mails to the list) is listname@linuxfocus.org
You should introduce new people in the team to the work and tell them to subscribe to the mailing list. Tell them also to read the Translation guideline: http://main.linuxfocus.org/English/articles/transguide.shtml.
As an editor you will need a local copy of the language section which you maintain and the /common directory on you hard disk. This will make it easy for you to keep the server nice and tidy and you can already check and preview all articles on you local harddisk.
The best way to get a local copy is to use rsnyc. This is also the fastest way as files are compressed during the transfer. Nevertheless it can take a couple of hours to get all files from common and your language section. The good news is that you can interrupt rsnyc and continue to mirror the rest of the files at a later stage.
The commands to get e.g the French section and common to the
current directory are:
rsync -rLtz -vv rsync.linuxfocus.org::lf/Francais . rsync -rLtz -vv rsync.linuxfocus.org::lf/common . or: rsync -rLtz -vv --exclude='*Archives*' rsync.linuxfocus.org::lf/Francais .
rsync is part of any good linux distribution (though it might not be installed by default) or can be obtained from http://samba.anu.edu.au/rsync/download.html
You have to be careful to not overwrite articles which you have not sent to the server yet with older copies from the server. For this reason it can be helpful to setup a file structure on your local disk as follows:
|-mirror/
| |
| YourLang/
| English/
| common/
|
|-local/
YourLang/
common -> symlink to ../mirror/common
English -> symlink to ../mirror/English
While there are several theoretical possibilities to upload
files there is really only one that is easy to use and made for
the daily work as editor.
Use
http://cgi.linuxfocus.org/cgi-bin/lfupdate.
You can basically do all updates with the upload patches
function. Patches are gzip compressed tar files. Html files
usually compress very well and it is therefore possible to
update a whole issue of Linuxfocus even over a modem line in
just a few seconds.
To use lfupdate you will need a user ID on the LinuxFocus server and a password. There is also a little utility called lfsendpatch which allows you to use lfupdate from the shell prompt. In other words you don't need a webbrowser to do that. It is generally faster from the command line since you can just run:
tar zcvf patch.tgz YourLang/MonthYYYY/articleXXX.* YourLang/MonthYYYY/index* ....
lfsendpatch -u username -p passwd patch.tgz
There are also several possibilites to check that your local
copy of LinuxFocus is in sync with the files on the server.
To see which files have recently been modified on your local
disk and need therefore probably to be uploaded to LinuxFocus
you can run:
find . -mtime -1 -type f -print
Please note: LinuxFocus has more than one server:
Cgi scripts are on: cgi.linuxfocus.org
All changes are done on: main.linuxfocus.org
All the other servers update automatically over night from
main.linuxfocus.org.
After major updates you should always check for broken
links. There is a program called tr_blck which is part of a
set of programs called HTML::TagReader.
You can download
it from
pepper.linuxfocus.org/~guido/.
You use tr_blck from the web-root directory of your local
LinuxFocus copy like this:
tr_blck *.html */*.html
Since July 1999 a new article format is used. Have a look at
pepper.linuxfocus.org/~guido/dev/lfparser.html
and
http://main.linuxfocus.org/English/articles/authguide.shtml.
Point 3 is really important even if you do not want to use this re-linking. The server tests at runtime if there is an article file with size bigger than 2000 bytes. If that file is there then it is assumed that the article is translated. So, never copy english article just over to your language section. Translate them or do not put any file.
How do the link to the available languages technically work?
Lfparser inserts a
<!--#include virtual="../../dynahead.shtml" -->
statement. The file dynahead.shtml finally contains
<!--#exec cmd="/usr/local/bin/lfdynahead" -->
A mirror site must therefore only modify this one
dynahead.shtml to adjust the path and create an own site
specific dynahead.shtml file. This file can then be excluded
from rsync.
The script lfdynahead which finally inserts the links is really
short. It uses only the filesystem as database. Using the right
directory structure is therefore important. It checks if the
article file exists in the other language and what its size
is.
LinuxFocus offers on request every editor a private homepage and an e-mail address. It's up to you to use it.
Your private homepage is main.linuxfocus.org/~YourLFUid
To upload files to your homepage you use scp (from openssh) and
put the files into the directory called public_html
You may create sub-directories in there. We have not set up any
limit for the size of your homepage but rely on your
cooperation to not mis-use this service. Note: For the moment there are no more homepages due to increased security on the server.
Please note that LinuxFocus is the initiative and work of volunteers that spend most of their spare time on LinuxFocus and work for free. The last thing that we would like to do is get in contact with the police because you misused LinuxFocus. We trust you and we hope that you are aware of the responsibility you have. Use your account and LinuxFocus in peace. If you want to fight a war then do it somewhere else.