[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ next ]

Debian Reference Contributor's Guide
Chapter 2 - How to contribute

Read documents under SourceForge.Net -\|[gt ]\| Site Docs to get used to sf.net system. "sourceforge.net" and "sf.net" are the same URL.

2.1 Work environment

Recommended OS for editing documents is the Sid version of Debian GNU/Linux while Sarge is in testing :-)

Theoretically, you can use FreeBSD, NetBSD or OpenBSD as your platform, too.

You must be careful on the encoding issue. Some newer environments in various OSs are Unicode which may create incompatible encodings unless you take great care. Notably, the Sid environment in Debian needs some care when using EMACS. Also post-7.0 versions of Redhat and Windows XP need some care since they use Unicode UTF-8 as their default encodings.

Do not use Windows as a development environment. You can of course use a terminal program in Windows to do development on a Debian GNU/Linux machine. I recommend using puTTY as ssh terminal. Also, the 7th section under SourceForge.Net -\|[gt ]\| Site Docs gives many hints for Windows users. I have to say even CygWin was erratic. CygWin editors added funny CR after all lines :-( Bad.

2.2 Software environment

I think that it is probably best to use the Sid version of the debiandoc-sgml package even if you have a Woody system. However, if you encounter problems then you should go back to the older version. TeX is changing a lot from Woody to Sarge, so expect a rough ride if you update your system. Use chroot tricks to experiment with these unstable environments. Please note that Sarge could not be used at the moment (August 2003) to create Chinese PostScript or pdf files. I think it is usable as of now (May 2005). You need Sid to do this.

2.3 First steps

You need a SSL enabled web browser to do the following.

  1. Join sourceforge.net (=sf.net) and get account name.

  1. Read SourceForge.Net -\|[gt ]\| Site Docs.

  1. Inform your sf.net account name to the project manager through e-mail.

  1. Wait for your name being added to "qref" developers.

  1. SSL login to "Personal Page" at sf.net with your account name.

  1. Click "Debian Reference" under "My Projects".

  1. Click "Lists" and proceed to add your e-mail address to "qref-developers".

  1. Set up MUA for "qref-developers". (You can directly access this at Qref-developers Info Page)

      # apt-get install debiandoc-sgml debiandoc-sgml-doc ssh make
      $ cd /usr/share/doc/debiandoc-sgml-doc/
      $ zless debiandoc-sgml.en.txt.gz
      $ ssh yourname@qref.cvs.sf.net
      ... (activate CVS account by this)
      $ export CVS_RSH=ssh
      $ cvs -z3 -d :ext:yourname@qref.cvs.sourceforge.net:/cvsroot/qref co -P qref
      $ cd qref
      ... do what ever to update "Debian Reference"
      $ cvs up
      ... resolve conflicts
      $ cvs ci -m"I did something"

The "-P" option is used to ensure that empty directories are not created.

If someone adds a new directory you can use cvs up -d to obtain this.

For web page including this document, check out "htdocs" instead of "qref".

      $ cvs -z3 -d :ext:yourname@qref.cvs.sourceforge.net:/cvsroot/qref co htdocs

I only update main web pages index.??.php this way. (I will change this to scp soon.)

2.4 Daily activities

      $ export CVS_RSH=ssh
      $ cd qref
      $ cvs diff -u -r rev1 -r rev2 [files ...] |less
      ... inspect what others have done
      $ cvs up
      ... edit as you wish
      $ cvs up
      ... resolve conflicts
      $ cvs ci -m"I did something"

2.5 CVS usage guide

CVS must be used effectively with an editor. (Read "Debian Reference" for more info.)

2.6 Choice of contents

The choice of what shall be included in the document involves tough decisions. Let me explain a bit more.

Introductions aimed at new Debian users are OK so long as it is in appropriate chapters such as system.sgml, tutorial.sgml or support.sgml. Try to keep them from getting too long.

I have no problem fixing factual errors any time as long as this does not break existing contents. When you correct, please consider other people's systems. "It works for me this way" is not a good enough reason to change the current recommendation.

Adding a new section is easier on translators than moving and reorganizing. I am not too tough on people requesting addition as long as it does not bloat too much and writing style meet out standard. (No to bloat quick-* applies.)

As for section reorganization, I know it is tempting but please avoid it as much as possible. Also once a section is started to be translated, please refrain from too much of stylistic changes and line formating changes. These tends to cause confusion to translators. If you need to include existing contents, use <ref id="..."> to refere existing contents elsewhere than moving it instead.

This guide should be the collection of best practices. So if there is a bug which needs a workaround, file a bug report against the package. If it needs to be mentioned on this document, make a link to BTS entry so that when the bug is fixed, readers have an easy way of finding this out. Please do not make this document into a collection of workarounds. [3]

If you intend to make major changes, ask the mailing list and give people 10 days to respond.

2.7 Mailing list communication guide

Mailing lists must be used effectively.

2.8 Sf.net shell account guide

Shell account gives you access to your home directory and the project web page. (Please do not worry updating web. Just drop me a mail after commit. This is here for reference only.)

Peek into my home directory for the examples (/home/users/o/os/osamu).

2.9 Update contents

Always use latest file from English as the source of translation. html, text, ps, and pdf file can be created locally to test your SGML:

     $ cd /where/you/have/qref
     $ cvs up                       # sync with HEAD
     $ make clean                   # if file owner is not you
     $ make html1 LANGS1=en LANGS2=      # for English for full  html document
     $ make html2 LANGS1=en LANGS2=en    # for English for short html document
     $ make html  LANGS1=en LANGS2=en    # for English for both  html documents
     $ make txt   LANGS1=en LANGS2=en    # for English for both  txt  documents
     $ make ps    LANGS1=en LANGS2=en    # for English for both  ps   documents
     $ make pdf   LANGS1=en LANGS2=en    # for English for both  pdf  documents
     $ make pdf   LANGS1=de LANGS2=de    # for German  for both  pdf  documents
     $ make html1 "LANGS1=fr it"         # for French and Italian full html
     $ make publish "LANGS1=fr it"       # for French and Italian html to ~/public_html
                       # this emulates what happens on DDP server 
     $ make sf         # publish web page to sourceforge.

Last one only works from Osamu's account :-)

     # apt-get install ssh
     # apt-get install -t unstable debiandoc-sgml debiandoc-sgml-doc
     # apt-get install -t unstable tetex-bin tetex-extra # this may be dangerous
     $ cd directory-where-local-qref-exists
     $ cvs up                       # sync with HEAD
     $ export SFUSER=osamu
     $ make scp                     # sf page created

Web page can be synced easily with cvs contents (HEAD) from a shell account of yourname as long as you update contents in CVS:

     $ cd /home/groups/q/qr/qref/htdocs/
     $ cvs -d:ext:yourname@cvs1:/cvsroot/qref up

Even though anyone can update any sf.net web page or files through rigourous shell account activity, it may be complicated and error prone.

Please do not commit file elsewhere and overwrite file here by manually copying latest version. It will break merging file.

2.10 Check output

LaTeX is used to create PostScript and .pdf files. These files contain hyphenations (such as un-stable) to ensure a proper text width in contrast to .html or text files. TeX's algorithm works well on English texts nevertheless it may create wrong hyphenations such as "files-ystem".

You can check these in the German translation of the Debian Reference with

     $ make LANGS1=de LANGS2= check-hyphen

(This requires the hyphen-show package.) The output is written to reference.de.hyp. Check this file for wrong strings. If you don't want to check this file again and again, you may create <lang>/validLaTeX.hyphen (copy the .hyp file). Ensure that all entries in this file are valid. The next time you start this hyphen check, the output and .hyp file are reduced by these and contain only hyphenations which are (possibly) wrong.

These words should be written into <lang>/LaTeXmacros.sty with correct hyphenations. Please see the German file for an example. Do another check after this until the .hyp file stabilizes.

2.11 Roadmap

Continuous activities:

  1. Spell and grammar corrections.

  1. Factual corrections.

  1. Experiment with po-debiandoc.

  1. Add/remove some prospectus contents to README.org.

Structual road map and prerequisite:

  1. Rebump build script. (anytime soon when Jens is ready.)

  1. Experiment with po-debiandoc. (when someone can add short howto in this manual and understand what to do.)

  1. Move CVS to debian-doc CVS or alitoh CVS on Debian system. (when someone can do this.)

  1. Move to docbook-xml. (when this can be done with script automatically and xml system is much more stable than 10/2003)

Content growth road map:

  1. Add standard unix tutorial contents in old debian-guide package into tutorial.sgml but exclude from quick-*, Do not copy and paste but just borrow idea and rewrite it as a shorter one.

  1. apache and simple CGI programing. (tune.sgml and program.sgml)

  1. DNS for simple behind firewall LAN. (tune.sgml after mail or gateway.sgml)

  1. DHCP server for simple behind firewall LAN. (tune.sgml after DNS or gateway.sgml)

Small contents proposals are always added to README.org as reminder first. Once good info accumulates, add to the real content.

2.12 Start a new translation

The translated pages have some comment lines to enable nice version tracking. See existing translation for examples. All of them starts something like:

     <!-- CVS revision of this document "$Revision: 1.21 $"  -->
     <!-- CVS revision of original english document "1.31"  -->
     <!--Line width ruler (ruler uses 78 characters)     34567890123456789012345-->

Only the 2nd line is really needed for the translation (modify it when necessary) and only the 1st line (created by CVS) is really needed for the English original.

It is very important that the revision number in the second line matches the revision of the English file, which was used for translation. Using this approach the translator knows, what parts of the translation need an update, whenever English files changed.

If you are starting from scratch, do the following to create template files for your new translation. Suppose you want a new language "bk":

     $ mkdir bk
     $ ./bin/doc-copy bk

You overwrite the existing English contents on the files in "bk" directory to create the new real translated files.

You may want to edit a few more files as well (don't hesitate to ask if you need help):

2.13 Check changes (CVS)

This may not be easy if the translator does not use version tracking implemented through the comment line in translation files. Using these version numbers you can manually check recent contents change existed or not and what was the change.

We made this automated with doc-check script. A list of outdated files can be obtained with

     $ bin/doc-check lang

(replace lang with de, es ,fr, it, ...).

Use the -d option to get a diff of english files (you must be online).

     $ bin/doc-check -d lang subdoc

(replace subdoc with system, tips, tune, ...).

[4] Here is the coplete command syntax.

     bin/doc-check [-d] [-v] [-V] [-e] [-w] [-a|lang [subdoc ...]]
     bin/doc-check -h [-e] [-a|lang [subdoc ...]]
           -a: all language
           -d: diff
           -v: verbose on reading each file header
           -V: verbose on diff
           -e: verbose on equal rev file (default=quiet)
           -h: create html page with translation versions in table format
           -w: ignore whitespaces for diff

After building source for package or after "rm README; make README", you have the version number table created in README using this doc-check script. That may give you good idea what chapter is lagging translation.

Let me show an example of how to use this doc-check script.

Let's determine whether the French translation is up to date or not (start this from qref's base directory):

     $ ./bin/doc-check fr 
     Translation delay for fr
     tips : 1.46 -> 1.73

The argument "fr" is the directory of the translation (de, pt-br, ...). It shows that fr/tips.sgml is outdated. A diff of en/tips.sgml's revision 1.46 against 1.73 is available with option -d (-w is used to ignore white spaces).

Check changes in English for Italian as a diff (ignore white spaces):

     $ ./bin/doc-check -d -w it | less

This lists all changes in original English contents from the days Italian translation. [5]

This may be too much to handle if these are too many changes. To make diff on one SGML source, for example tune.sgml:

     $ ./bin/doc-check -d -w it tune| less

Alternatively, you can get nice colored diff etc using the version number and techniques written in Check changes (WEB), Section 2.14.

2.14 Check changes (WEB)

If you have any difficulties using CVS like me for tracking changes, use CVS page on qref.sf.net. This can be reached by selecting the CVS tab on the top of the project page. Few things to remember: We are working on "MAIN" branches. Latest version is called "HEAD". The rest should be no problem using web interface and color to check what as been changed.

Make sure to update top lines which record referenced English version.

[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ next ]

Debian Reference Contributor's Guide

30 April 2005

Osamu Aoki osamu#at#debian.org
Jens Seidel tux-master#at#web.de