Differences between revisions 35 and 36
Revision 35 as of 2010-04-06 17:42:24
Size: 16555
Comment:
Revision 36 as of 2010-04-10 21:13:42
Size: 16605
Comment: some minor fixes
Deletions are marked like this. Additions are marked like this.
Line 16: Line 16:
Generally speaking: everything which might have a noticeable impact on the Debian Project at large and its user base is special. Generally speaking: everything which might have a noticeable impact on the Debian Project at large and its user base in particular.
Line 20: Line 20:
 * Discussion taking place on a mailing list, which:  * Discussions taking place on a mailing list, which:
Line 41: Line 41:
think fitting to the ProjectNews to our mailing lists debian-publicity@lists.debian.org .

Keep in mind, that one of the main purposes from our side, beside keeping our users informed, is to show them that we are a living, working community! I.e. to show that Debian is thriving, that Debian is alive!
think fitting to the ProjectNews to our mailing list debian-publicity@lists.debian.org .

Keep in mind, that one of the main goals for us, beside keeping our users informed, is to show them that we are a living, working community! I.e. to show that Debian is thriving, that Debian is alive!
Line 47: Line 47:
So one thing you can help as a native speaker is to fix his en_DE to proper English. The issues are drafted in So one thing you can help with, as a native speaker, is to fix his en_DE to proper English. The issues are drafted in
Line 51: Line 51:
review, and mail comments to the [[mailto:debian-publicity@lists.debian.org|debian-publicity mailing list]]. review it, and mail comments to the [[mailto:debian-publicity@lists.debian.org|debian-publicity mailing list]].
Line 55: Line 55:
<<Anchor(becomingeditor)>>
Line 58: Line 58:
If you want to contribute directly and want to add small articles for the ProjectNews yourself, feel free If you want to contribute directly and want to add small articles to the ProjectNews yourself, feel free
Line 73: Line 73:
 * run {{{svn co svn+ssh://svn.alioth.debian.org/svn/publicity/dpn/en/current}}}. This command will create a Folder {{{current}}} containing the current draft the Debian Project News. If you like, you may rename that folder into something more convenient for you.
 * Change into that directory. Whatever you do: never delete or otherwise touch the {{{.svn}}} folder therein! It contains some meta date needed to maintain everything.

You can now edit the Debian Project News. Don't worry if you unexperienced with subversion or the Website Meta Language / HTML (which is used for Debian's website). Nothing you do will directly appear on the website and all errors you might do can be revoked relatively painlessly.
 * run {{{svn co svn+ssh://svn.alioth.debian.org/svn/publicity/dpn/en/current}}}. This command will create a {{{current}}} folder containing the current draft the Debian Project News. If you like, you may rename that folder into something more convenient for you.
 * Change into that directory. Whatever you do: never delete or otherwise touch the {{{.svn}}} folder therein! It contains some meta data needed to let everything work properly.

You can now edit the Debian Project News. Don't worry if you are unexperienced with subversion or the Website Meta Language / HTML (which is used for Debian's website). Nothing you do will directly appear on the website and all errors you might do can be revoked relatively painlessly.
Line 83: Line 83:
 * You may now edit {{{index.wml}}} as you like. See bellow for details of the format.  * You may now edit {{{index.wml}}} as you like. See below for details on the format.
Line 93: Line 93:
Two more other guidelines for committing your changes: Two more guidelines for committing your changes:
Line 96: Line 96:
 1. Try not to make to long lines. Tracking changes / viewing diffs is easier, when the line length is shorter then ~80 characters. Most Editors can be configured to automatically break the line for you.  1. Try not to write too long lines. Tracking changes / viewing diffs is easier, when the line length is shorter than ~80 characters. Most Editors can be configured to automatically break the line for you.
Line 102: Line 102:
To use the translation check header (which makes it possible for translators to mark which revision of a file they followed when translating) the wml-Files must be have the respective svn keywords properties set. So you can place $Id:$ in a document, and subversion will automatically replace it with some information about who did when the last changes and which revision is this document now.

So before committing a new wml file to the repository, please use the following to allow the keyword expansion: {{{svn propset svn:keywords "Date Author Id Rev" <yourfile>}}}.

You can also add the following the {{{[auto-props]}}} section of your {{{~/.subversion/config}}} and uncomment the {{{enable-auto-props = yes}}} entry which should take care of that automatically:
To use the translation check header (which makes it possible for translators to mark which revision of a file they followed when translating) the wml-Files must have the respective svn keywords properties set. So you can place $Id:$ in a document, and subversion will automatically replace it with some information about who did the last changes, when and which revision this document is now.

So before committing a new wml file to the repository, please use the following to allow keyword expansion: {{{svn propset svn:keywords "Date Author Id Rev" <yourfile>}}}.

You can also add the following line to the {{{[auto-props]}}} section of your {{{~/.subversion/config}}} and uncomment the {{{enable-auto-props = yes}}} entry which should take care of that automatically:
Line 111: Line 111:
<<Anchor(indexwmlformat)>>
Line 115: Line 115:
 * As e-mail send to the [[http://lists.debian.org/debian-news|debian-news mailing list]] (in text form)  * As e-mail sent to the [[http://lists.debian.org/debian-news|debian-news mailing list]] (in text form)
Line 119: Line 119:
All these formats are generated from the {{{index.wml}}} file. Debian's website use the ''website meta language (WML)'' to create the web pages. Roughly speaking is WML HTML with embedded macros (e.g. for common elements on various sited) and the possibility to embed perl scripts, e.g. to create a list of DPN issues based on the files available. But don't worry: you don't need to know WML or perl (and only basic HTML) to contribute to the DPN. Luckily nearly everything is already in place and we just need to create the content with minimal HTML markup.

If you look at an empty {{{index.wml}}} (you can look at [[https://alioth.debian.org/scm/viewvc.php/*checkout*/dpn/en/index.wml-template?root=publicity|this one]] which is used as template) you'll notice that it starts as follows:
All these formats are generated from the {{{index.wml}}} file. Debian's website uses the ''website meta language (WML)'' to create the web pages. Roughly speaking WML is HTML with embedded macros (e.g. for common elements on various sites) and the possibility to embed perl scripts, e.g. to create a list of DPN issues based on the available files. But don't worry: you don't need to know WML or perl (and only basic HTML) to contribute to the DPN. Luckily nearly everything is already in place and we just need to create the content with minimal HTML markup.

If you look at an empty {{{index.wml}}} (you can look at [[https://alioth.debian.org/scm/viewvc.php/*checkout*/dpn/en/index.wml-template?root=publicity|this one]] which is used as a template) you'll notice that it starts as follows:
Line 128: Line 128:
The first line says to the wml compiler that it should use the project-news template for the header. It also sets two variables for the publishing date and a small summary. The summary is used for example at the [[http://www.debian.org/News/project/2009/|index page for recent issues]]. It should be to long. The first line says to the wml compiler that it should use the project-news template for the header. It also sets two variables for the publishing date and a small summary. The summary is used for example at the [[http://www.debian.org/News/project/2009/|index page for recent issues]]. It shouldn't be too long.
Line 132: Line 132:
At the end you'll see something similar: At the end you'll see something similar to this:
Line 180: Line 180:
 * Now you can mimik the same directory layout used under the {{{en}}} folder. Old Issues are kept in the specific {{{en/<year>/<issue>}}} directories, the one currently worked on is in {{{en/current}}}. You'll also notice the {{{en/index.wml-template}}} which is an empty issue, used as template to start a new one.
 * Please see [[HowToContribute#Becominganeditoryourself|Becoming an editor yourself]] for some usage guidelines for subversion and a small description of the format of the wml files. But note:
  * Translations should also use an {{{#use wml::debian::translation-check translation="<revision>"}}} header, to mark which revision of the original your translation follows.
 * Similar to the {{{editor}}} field of the {{{#use wml::debian::projectnews::footer}}} field, translator can also add a {{{translotor}}} field in a similar fashion. See the following example:
 * Now you can mimic the same directory layout used under the {{{en}}} folder. Old Issues are kept in the specific {{{en/<year>/<issue>}}} directories, the one currently worked on is in {{{en/current}}}. You'll also notice the {{{en/index.wml-template}}} which is an empty issue, used as a template to start a new one.
 * Please see [[#becomingeditor|Becoming an editor yourself]] for some usage guidelines for subversion and a small description of the format of the wml files. But note:
  * Translations should also use a {{{#use wml::debian::translation-check translation="<revision>"}}} header, to mark which revision of the original issue the translation follows.
 * Just like the {{{editor}}} field in the {{{#use wml::debian::projectnews::footer}}} line, translators can also add a {{{translator}}} field in a similar fashion. See the following example:
Line 206: Line 206:
As shortly explained in section [[/HowToContribute#Formatoftheindex.wmlfile|Format of the index.wml]], the Debian Project News are published in three ways: As shortly explained in section [[#indexwmlformat|Format of the index.wml file]], the Debian Project News are published in three ways:
Line 209: Line 209:
 * Text mail send to various lists  * Text mail sent to various lists
Line 213: Line 213:
To send your translation out as e-mail on one of our [[http://lists.debian.org/devel.html|user mailing lists]], note that the debian-news-''language'' lists are moderated, so please get in contact with the respective moderators / your translation team (e.g. via the debian-l10n-''language'' lists). If there's no debian-news-''language'' list for your language, but a debian-user-''language'' list, you may send your translation to that list (depending on how the members of that list think about it).

Regardless of where you send it, you will find the script {{{scripts/DPNhtml2mail.pl}}} quite handy: when your translation is available on the website, you can just run it, and it will create the text version for you. You can call it similar to {{{scripts/DPNhtml2mail.pl -d -l en -i 2008/06}}}. It doesn't work perfect, yet, but it makes it very easy to create a "good looking" text version.
To send your translation out as e-mail on one of our [[http://lists.debian.org/devel.html|user mailing lists]], note that the debian-news-''language'' lists are moderated, so please get in contact with the respective moderators / your translation team (e.g. via the debian-l10n-''language'' lists). If there's no debian-news-''language'' list for your language, but a debian-user-''language'' list, you may send your translation to that list (depending on what the members of that list think about it).

Regardless of where you send it, you will find the script {{{scripts/DPNhtml2mail.pl}}} quite handy: when your translation is available on the website, you can just run it, and it will create the text version for you. You can call it in a way similar to {{{scripts/DPNhtml2mail.pl -d -l en -i 2008/06}}}. It doesn't work perfectly, yet, but it makes it very easy to create a "good looking" text version.

Translation(s): Español - Français- Italiano

(!) ?/Discussion


  • This page explains HOWTO contribute to Debian ProjectNews and what YOU can do to help.

HOWTO contribute

Contributing to ProjectNews is easy but depends on your skills and the amount of time you can spare.

Send interesting news

The easiest way to help us is to inform us about interesting things happening in the Debian universe. Debian is quite a big project, and we don't have the manpower to monitor every mailing list, blog, news site for content we might want to add to our ProjectNews. So tell us, if you noticed something interesting happening. You can usually do this by sending an E-Mail to debian-publicity@lists.debian.org .

What you should send

Generally speaking: everything which might have a noticeable impact on the Debian Project at large and its user base in particular.

Some ideas:

  • Discussions taking place on a mailing list, which:
    • have a noticeable impact on Debian (e.g. License Discussion, a scheduled software transition)
    • contain an interesting discussion regarding Project foo to Project bar General Resolutions, etc.)

  • Smaller announcements from sub projects:
    • debian installer about to release beta3, testing requested
    • French debconf translations reach 100%
    • cdrkit capable of burning blue ray discs
    • "Bits from " mail
    • etc...
  • Interesting Bug Reports (ever looked at 245047?)

  • You represent Debian at a conference or exhibition (with a booth, talk, workshop, etc.)
    • You wrote a report after having represented Debian at a conference or exhibition
  • You were interviewed about your work on Debian
  • Debian related reviews / tests / articles in other media / web sites / mailing lists / blogs
  • Conferences, mini ?DebConfs, FOSDEM, CeBIT, etc.

  • etc...

Things you don't need to report

Of course the above list is far from being complete. We would especially like to point out, that we can't monitor other media, web sites, blogs and everything else. So it's very valuable to report anything you think fitting to the ProjectNews to our mailing list debian-publicity@lists.debian.org .

Keep in mind, that one of the main goals for us, beside keeping our users informed, is to show them that we are a living, working community! I.e. to show that Debian is thriving, that Debian is alive!

Help from native speakers

Currently the main editor is not a native English speaker. He knows it, and you probably have noticed it, too. So one thing you can help with, as a native speaker, is to fix his en_DE to proper English. The issues are drafted in a Subversion repository. Details on how to access using a Subversion client are listed below in the "Becoming an editor yourself" section. Even if you are unfamiliar with Subversion, you can always download the current issue, review it, and mail comments to the debian-publicity mailing list. We would prefer to receive your changes as diff or wdiff, if possible: Just make a copy of the downloaded file, edit it, and send us the output of diff -u <oldfile> <newfile>.

Becoming an editor yourself

If you want to contribute directly and want to add small articles to the ProjectNews yourself, feel free to join the team:

Accessing the subversion repository

Before accessing the subversion repository, you might want to read ?Setting up SSH the first time to use the subversion repository on alioth more conveniently.

  • run svn co svn+ssh://svn.alioth.debian.org/svn/publicity/dpn/en/current. This command will create a current folder containing the current draft the Debian Project News. If you like, you may rename that folder into something more convenient for you.

  • Change into that directory. Whatever you do: never delete or otherwise touch the .svn folder therein! It contains some meta data needed to let everything work properly.

You can now edit the Debian Project News. Don't worry if you are unexperienced with subversion or the Website Meta Language / HTML (which is used for Debian's website). Nothing you do will directly appear on the website and all errors you might do can be revoked relatively painlessly.

Editing

  • Change into the folder containing the checkout. Unless you renamed it, that would be current.

  • Before editing, you should run svn update. This will get your local copy up to date.

  • You may now edit index.wml as you like. See below for details on the format.

  • After you changed index.wml, please run svn update again. Just in case someone changed that document while you where working on it.

    • Subversion tries to be smart, when applying foreign changes to your changed document. Unless you changed the very same line, everything should work out pretty fine.
    • Should you have changed the very same lines, you have created a so called conflict, which must be resolved. Please see the svn book on how to do so.

  • Once your local copy is up to date, you can send your changes to the central repository by running svn -m "description of your changes" commit index.wml.

  • Congrats you just contributed to next issue of the Debian Project News!

Also note, that there are several graphical front ends for subversion. But as the writer lacks experience with any of them, he can't recommend them.

Two more guidelines for committing your changes:

  1. Please use a useful commit message (the description of your changes behind the "-m" Parameter).
  2. Try not to write too long lines. Tracking changes / viewing diffs is easier, when the line length is shorter than ~80 characters. Most Editors can be configured to automatically break the line for you.

Some hints for subversion usage

Keyword expansion and subversion

To use the translation check header (which makes it possible for translators to mark which revision of a file they followed when translating) the wml-Files must have the respective svn keywords properties set. So you can place $Id:$ in a document, and subversion will automatically replace it with some information about who did the last changes, when and which revision this document is now.

So before committing a new wml file to the repository, please use the following to allow keyword expansion: svn propset svn:keywords "Date Author Id Rev" <yourfile>.

You can also add the following line to the [auto-props] section of your ~/.subversion/config and uncomment the enable-auto-props = yes entry which should take care of that automatically:

*.wml = svn:keywords="Author Date Id Rev URL";

Format of the index.wml file

The Debian Project News are available in three formats:

All these formats are generated from the index.wml file. Debian's website uses the website meta language (WML) to create the web pages. Roughly speaking WML is HTML with embedded macros (e.g. for common elements on various sites) and the possibility to embed perl scripts, e.g. to create a list of DPN issues based on the available files. But don't worry: you don't need to know WML or perl (and only basic HTML) to contribute to the DPN. Luckily nearly everything is already in place and we just need to create the content with minimal HTML markup.

If you look at an empty index.wml (you can look at this one which is used as a template) you'll notice that it starts as follows:

#use wml::debian::projectnews::header PUBDATE="2010-XX-XX" SUMMARY=""
#use wml::debian::acronyms

The first line says to the wml compiler that it should use the project-news template for the header. It also sets two variables for the publishing date and a small summary. The summary is used for example at the index page for recent issues. It shouldn't be too long.

The acronyms line allows the use of specific acronyms, which will show the explanation as a hover text over the acronym.

At the end you'll see something similar to this:

#use wml::debian::projectnews::footer editor="XXX, XXX, Alexander Reichle-Schmehl"

That tells the wml compiler to add the normal footer to the web page. With the editor variable, it will also add the names of the contributors listed there.

Everything between these lines, is regular HTML, which in our case mostly means: some headlines (<h2>...</h2>), some paragraphs (<p>...</p>) and some lists (<ul><li>...</li><li>...</li></ul>).

Every article should start with a headline:

<a name="1"></a>
<h2>This is the headline of my small article</h2>

The stuff between the <h2> and </h2> is the actual headline. The <a name="x"></a> creates a so called anchor used to directly jump to a specific entry. It's for example used in the RSS-feed.

After that follows the actual article between <p> and </p>. You may use several of these paragraphs, but note that only the first one will appear in the RSS-feed. (Which might be a bug worth fixing, if you know enough perl...)

As explained, you may use normal HTML in these paragraphs. This means:

  • <q>...</q> for quotes, citations or release names:

    • Debian 6.0 <q>squeeze</q>, Steve McIntyre said: <q>Booh!</q>

  • <a href="..."> for links:

    • The Secretary <a href="http://lists.debian.org/debian-devel-announce/2010/03/msg00000.html">called for nominates</a> for the project leader elections.

  • <!-- ... --> for comments, which won't appear on the website:

    • {<!-- TODO:  Add a link once this discussion has come to a conclusion! -->

As the Project News is also read by users not very familiar with the Debian internal jargon and acronyms, please also use the <acronym ...> </acronym> tag (not part of HTML but one of our wml templates). See the following example:

One topic discussed was: <q>Race against <acronym lang="en" title="None of the above">NOTA</acronym>.</q>

While it won't work in the text version for e-mails, at least the HTML version for the websites and the RSS feed will mark the acronym so, that when the user moves the mouse cursor over the acronym the explanation is displayed. You can see an example on http://www.debian.org/News/project/2009/02/ (search for DPL).

Translating the Debian Project News

Feel free to use the subversion repository for your translation work, too. In these cases it is easier to just check out the complete DPN hierarchy of the subversion repository by doing:

  • svn co svn+ssh://svn.alioth.debian.org/svn/publicity/dpn/

  • cd dpn

  • Now check if there is already a directory for your language. If not
    • Create one, e.g. mkdir fr

    • Add it to the repository, e.g. svn add fr

    • And commit it to the central Server, e.g. svn commit -m "create directory for french translations" fr

  • Now you can mimic the same directory layout used under the en folder. Old Issues are kept in the specific en/<year>/<issue> directories, the one currently worked on is in en/current. You'll also notice the en/index.wml-template which is an empty issue, used as a template to start a new one.

  • Please see Becoming an editor yourself for some usage guidelines for subversion and a small description of the format of the wml files. But note:

    • Translations should also use a #use wml::debian::translation-check translation="<revision>" header, to mark which revision of the original issue the translation follows.

  • Just like the editor field in the #use wml::debian::projectnews::footer line, translators can also add a translator field in a similar fashion. See the following example:

#use wml::debian::projectnews::footer editor="Moritz Muehlenhoff, Andre Felipe Machado, Alexander Reichle-Schmehl" translator="Benedikt Beckmann"

Using Translation check to track original document versions

If you use the publicities subversion repository you can use the script in scripts/trans-check to track which of your translations are up to date. Your translations need a translation check for this to work. For example:

#use wml::debian::translation-check translation="45"

This will tell the script (and later Debian's website), that your translation was based upon revision 45 of the original document.

The only parameter it takes is the language to be checked or to be more precise: the folder it should compare against the en/ folder. See the following example:

alex@rusalka:publicity/dpn$ scripts/trans-check fr
Found 'fr/current/index.wml' is outdated!
  Please run 'svn diff -r 9:18 "en/current/index.wml"' to review the changes to the original document.

Getting your translation published

As shortly explained in section Format of the index.wml file, the Debian Project News are published in three ways:

  • HTML on the Debian web site
  • RSS feed (also on the Debian web site)
  • Text mail sent to various lists

To get your translation published on Debian's website, it will need to be added to the CVS repository. See http://www.debian.org/devel/website/ for more details about that.

To send your translation out as e-mail on one of our user mailing lists, note that the debian-news-language lists are moderated, so please get in contact with the respective moderators / your translation team (e.g. via the debian-l10n-language lists). If there's no debian-news-language list for your language, but a debian-user-language list, you may send your translation to that list (depending on what the members of that list think about it).

Regardless of where you send it, you will find the script scripts/DPNhtml2mail.pl quite handy: when your translation is available on the website, you can just run it, and it will create the text version for you. You can call it in a way similar to scripts/DPNhtml2mail.pl -d -l en -i 2008/06. It doesn't work perfectly, yet, but it makes it very easy to create a "good looking" text version.