The editor's guide to LinuxFocus

Index:

  1. The soft part
    1. What is an editor?
    2. What do I have to do as editor?
    3. Is LinuxFocus only translation work?
  2. The technical part
    1. The file system structure
    2. Checking articles
    3. New people, mailing list
    4. Getting your own local copy of your language section
    5. Updating pages on the server
    6. Checking for dead links and programs to help editing LinuxFocus
    7. Editors toolbox
    8. Article templates
    9. Links to different languages via SSI
  3. E-mail and homepage
  4. How to start?

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




 

The soft part

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.

 

What is an editor

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.

 

What do I have to do as editor?

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.

 

Is LinuxFocus only translation 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.

 

The technical part

 

The file sytem structure

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:

  1. It saves disk space
  2. It makes article translation easier as one needs only to translate the text and the images can stay where they are.
  3. It makes surfing faster as you get more cache hits from proxy servers and your own browser cache.
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.
 

Checking articles

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.shtml
on 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.shtml
When you have edited the article and corrected the faults you can run
 
tidy -im -raw articleXXX.meta.shtml
to 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.

 

New people, mailing list

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.

 

Getting your own local copy of your language section

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
 

Updating pages on the server

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

This will list the files modified within the last 24 hours. You can also use the inspect function from lfupdate and then use a program called lfcheckfiles to compare the files on the server with your files. You can read more about lfcheckfiles on this web-page.

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.

 

Checking for dead links and programs to help editing LinuxFocus

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
 

Editors toolbox

A seperate document called "ebox" = Editors Toolbox contains a list of useful tips and tools for your work: http://main.linuxfocus.org/doc/ebox/  

Article templates

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.

 

Links to other languages via Server Side Include

Since April 2000 you can have links to other languages for each article. These links are generated at run time via server side includes. For this to work you need to follow a few simple rules:
  1. name your articles .shtml instead of .html
  2. use lfparser 2.31 or higher (pepper.linuxfocus.org/~guido/dev/lfparser.html)
  3. If the article is not yet translated then put no file into the directory! There is a program executed at upload time for YourLang/MonthYYYY/index.shtml or YourLang/MonthYYYY/index.html which will automatically re-link links to articles which are not yet translated. For this to work put <!-- lftransstatus=1 --> into the index.shtml (or index.html).

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.



 

Private E-mail and homepage

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.

 

How to start?

Whether you start a complete new section or you bring new life to a currently unmaintained language section you should try to tell the world as early as possible about it. Update first the YourLang/index.shtml and put a text there saying that a new language will be available and people who are interested to join should contact you.

Don't try to immediately catch up with the work that others have done over years. Instead start with the next issue. Again when the "next issue" comes out put a little box on the side where you ask people to help you (write this on YourLang/MonthYYYY/index.shtml).

It is simply too much work for only one person. It is much better to be a team. It will take some time but you will normally find people.
Last updated Sun Jan 11 12:37:39 EST 2004 guido socher (guido/at/linuxfocus.org)