path: root/greek/devel/website/working.wml

#use wml::debian::template title="How to work on the Debian web pages" BARETITLE=true
#use wml::debian::toc
#use wml::debian::translation-check translation="b5c35a479efa1910b978df5114fd87e4142e3892" maintainer="galaxico"

<toc-display/>



<toc-add-entry name="general">General information</toc-add-entry>

<h3>Resource requirements</h3>

<p>If you want to work on our web site, please be prepared to store at least
740 MB of data on your disk. This reflects the current size of the source
archive. If you (accidentally) rebuild all of the pages, you will need at
least three times as much space.</p>

<h3><q>What are these lines beginning with `#'?</q></h3>

<p>In WML, a line beginning with a `#' is a comment. These are preferred to
normal HTML comments as they don't show up on the final page.</p>

<p>Please read the page on <a href="using_wml">using WML</a> for more
information on WML.</p>

<toc-add-entry name="etiquette">Etiquette for editors</toc-add-entry>

<h3><q>Can I modify this page?</q></h3>

<p>That depends. If you see a small mistake, like a typo, just fix it.</p>

<p>If you notice that some bit of information is missing, feel free to fix
it, too.</p>

<p>If you feel that something is awful and needs to be rewritten, bring it
up on debian-www so it can be discussed. We'll probably agree with you.</p>

<p>If you notice there's a problem in a template (i.e. a file in
webwml/english/template/debian directory), please think about the change
before committing it, because changes to templates often cause large portions
of the site to get rebuilt.</p>

<h3>When adding new directories, also add the Makefile!</h3>

<p>Some care should be taken when adding a new directory to git. If the
current directory is listed in ../Makefile then you <b>must</b> create a
Makefile in it &mdash; otherwise <tt>make</tt> will give an error message.</p>

<h3>Use clear and simple English</h3>

<p>Since the Debian web pages are read by non-native speakers of English
and are translated into other languages, it is best to write in clear and
simple English and avoid the use of slang, emoticons and obscure idioms.
</p>

<p>If you do use any of this, add a comment to the file explaining the
meaning.</p>

<p>
If any doubt, or in order to proofread your proposal, please contact the <a
href="mailto:debian-l10n-english@lists.debian.org">English localization team</a>.
</p>

<h3>Look for READMEs</h3>

<p>Some of the directories contain a README to help you understand
how that directory is organized. These should provide any special
information needed when working in that area.</p>

<h3>Separate the changes in content from the changes in formatting</h3>

<p>Always make separate patches or commits for content changes and for
changes in formatting. When they are combined, it's much harder for
translators to find the differences. If you run <kbd>git diff -u</kbd> with
such mixed changes, you can see the mess for yourself.</p>

<p>In general, avoid random formatting changes. Making older parts of pages
XHTML/XML-compliant shouldn't be done in the same commit with other changes.
(New stuff can and should be done properly from the start, of course.)</p>


<h3>Update translations, too, if possible</h3>

<p>Some changes are independent of the language used in a WML file, like
changes to URLs or embedded Perl code. Fixing typos also falls in the same
category, because translators have usually ignored them while translating.
With such language-independent changes, you can do the same change in
all the translated files without actually knowing the other languages,
and safely increase the version in the translation-check headers.</p>

<p>It's not terribly hard for translators to do the same work themselves,
and it can be inconvenient for English-speaking editors to have a full
checkout in which to operate. However, we still encourage people to do this
in order to avoid bothering two dozen people for something that can be done
quickly by a single person.</p>

<p>In addition, to make such changes easier to apply, you can use the
<a href="using_git#translation-smart-change"><code>smart_change.pl</code></a>
script from the top-level directory in the webwml git module.</p>

<toc-add-entry name="links">Links</toc-add-entry>

<h3><q>This link doesn't look right. Should I change it?</q></h3>

<p>Because of the way the web servers are set up (using
<a href="content_negotiation">content negotiation</a>),
you should not have to change any of the internal links.
In fact we suggest you don't. Write to debian-www
if you feel a link is incorrect before changing it.</p>

<h3>Fixing links</h3>

<p>If you notice a link to an external web site results in a redirection
(301, 302, a &lt;meta&gt; redirect, or a page saying <q>This page has moved.</q>)
please tell debian-www about it.</p>

<p>If you find a broken link (404, 403, or a page that's not what the link
says it is), please fix it and tell debian-www about it so translators are
aware. Even better, fix the link in all the other translations, and update
translation-check headers if possible.</p>

<toc-add-entry name="special">Separation of text from data</toc-add-entry>

<h3><q>What are these foo.def and foo.data files?</q></h3>

<p>To make it easier to keep the translations up to date, we separate the
generic parts (data) from the textual parts (text) of some pages. The
translators only need to copy and translate the textual parts of those, the
generic parts will be added automatically.</p>

<p>An example may help in understanding this. It takes several files to
generate the page of vendor listings in <code>CD/vendors</code>:</p>

<dl>
  <dt><code>index.wml</code>:</dt>
      <dd>The text at the top of the vendors page is in this file.
      A translated copy of this should be placed in each language directory.</dd>
  <dt><code>vendors.CD.def</code>:</dt>
      <dd>This contains all the pieces of text which are needed for each
      vendor entry. Translations are added via
      <code>&lt;<var>language</var>&gt;/po/vendors.<var>xy</var>.po</code>.</dd>
  <dt><code>vendors.CD</code>:</dt>
      <dd>This file contains the actual vendor entries which are independent
      on the language, so a translator doesn't need to touch this file.</dd>
</dl>

<p>When one of the people behind <email "cdvendors@debian.org"> adds a
new vendor, they add it to <code>debiancd.db</code>, convert it into WML
format as <code>vendors.CD</code> (using <code>getvendors.pl</code>),
and then let WML and the makefiles do their magic. All the translations
get rebuilt using the existing translated text but with the new vendor
data. (An updated translation for free!)</p>

<toc-add-entry name="newpage">Adding a new page</toc-add-entry>

<p>Adding new pages to Debian is quite easy. All the work of getting the
header and footer right are done using WML. All you need to do is to include
a line such as the following at the top of the new file:</p>

<pre><protect>
#use wml::debian::template title="TITLE OF PAGE"
</protect></pre>

<p>followed by the body. All pages should use the
<code>wml::debian::template</code> template file unless they are using
a special one created just for that section, e.g. the News or security items.</p>

<p>The templates we have allow you to define certain variables which will
affect the pages created. This should avoid having to create different
templates for every situation and allow improvements to be easier to
implement. The variables currently available and their purpose are:</p>

<dl>
<dt>BARETITLE="true"</dt>
	<dd>Removes the "Debian --" part that is usually prepended
	to all the &lt;title&gt; tags.</dd>
<dt>NOHEADER="true"</dt>
	<dd>Removes the initial header from the page. A custom header
	can, of course, be included in the body.</dd>
<dt>NOMIRRORS="true"</dt>
	<dd>Removes the mirror dropdown list from the page. It is generally
	not recommended to be used, except for a handful of pages.</dd>
<dt>NOHOMELINK="true"</dt>
	<dd>Removes the link back to the main Debian page, which is normally
	added to the bottom of the page.</dd>
<dt>NOLANGUAGES="true"</dt>
	<dd>Removes the links to versions in other languages, which are
	normally added to the bottom of the page.</dd>
<dt>GEN_TIME="true"</dt>
	<dd>Sets the date on the resulting files to the timestamp of the
	generated files, instead of the timestamp of the source file.</dd>
<dt>NOCOPYRIGHT="true"</dt>
	<dd>Removes the copyright notice at the bottom of the page.</dd>
</dl>

<p>Note that you can use any string as the value of these variables,
<q>true</q>, <q>yes</q>, <q>foo</q>, it doesn't matter.</p>

<p>An example of the use of this is in the ports pages which have
their own headers. <code>ports/arm/index.wml</code> uses:</p>

<pre><protect>
#use wml::debian::template title="ARM Port" NOHEADER="yes"
</protect></pre>

<p>If you want to do something that can't be done using the existing
templates, first consider extending one of them. If it isn't
possible to extend one in a backward compatible way, try to make
the new template a superset of an existing one so the pages can
be converted to it at the next major upgrade (hopefully never more
than every 6 months).</p>

<p>If you are creating a page that is generated by a script or has
little prose, consider using the &lt;gettext&gt; tags to ease
the task of keeping translations up to date.</p>

# think of a good example for <gettext> in new pages

<toc-add-entry name="inclusion">Including other files</toc-add-entry>

<p>If you want to separate some parts of your page into a distinct file 
   (which is then included by your main file) use
   the extension <code>.src</code> if your file contains content which should
   be translated because then your included file is tracked for changes as
   any ordinary <code>.wml</code> file. If you use any other extension, like
   <code>.inc</code>, translators will not notice your updates and different
   languages might ship different content.</p>

<toc-add-entry name="newdir">Adding a new directory</toc-add-entry>

<p>Note: do <strong>not</strong> create a directory with the name
<code>install</code>. This confuses make and the pages in that directory
will not be updated automatically.</p>

<p>Below is an annotated example of adding a new directory to the web site.
</p>
<pre>
   mkdir foo
   git add foo
   cd foo
   cp ../intro/Makefile .
   git add Makefile
</pre>

<p>Edit the Makefile in the parent directory and add the directory you just
created to the <code>SUBS</code> variable. This will add the directory to
the build for when make is run.</p>

<p>Finally, commit all the changes just made to the repository with
</p>
<pre>
  git commit Makefile foo
</pre>