[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ next ]
Read documents under SourceForge.Net -\|[gt ]\| Site
Docs to get used to sf.net system. "sourceforge.net" and
"sf.net" are the same URL.
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.
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.
You need a SSL enabled web browser to do the following.
Join sourceforge.net (=sf.net) and get account name.
Inform your sf.net account name to the project manager through e-mail.
Wait for your name being added to "qref" developers.
SSL login to "Personal Page" at sf.net with your account name.
Click "Debian Reference" under "My Projects".
Click "Lists" and proceed to add your e-mail address to "qref-developers".
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.)
Update local archive with latest source (cvs up).
Use mailing list (qref-developers@lists.sf.net) to communicate with others.
Use CVS to update to latest version, etc.
If mistakes exist, correct them. Just make sure you don't make new mistakes! :)
$ 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"
CVS must be used effectively with an editor. (Read "Debian Reference" for more info.)
Go to CVS
page to see what has been recently changed and who did it. This
will give you an idea of which files need attention. See Check changes (WEB), Section 2.14.
You can get diff information from web with colors.
Use the CVS diff command to find out exact changes by others.
Try to commit one file at a time with a good description.
Try to set text file width to 72-78 char/line before commit.
Start vim with $ vi -c "set tw=78" filename
Or even better for translators, use "vimdiff -c 'set tw=78' en/file.sgml fr/file.sgml" on sideway stretched (160 char/line) x-term. It is very nice ;-)
Reformat by highlighting with visual mode (V) and "gq" only if it is new section (do not do this for old sections).
Start vim with $ vi -c "set tw=78" filename
Also having diff file shown in another window is handy.
Try to be slow on any structural changes and consult others. General guidelines are:
Do not change filenames.
Do not change line breaks across files.
Do not add new files.
Do not move sections.
Do not add long descriptive sections. There should be an alternative which is simpler.
Try to coordinate with others.
Ask on the mailing list or ask me.
Make sure to update referenced version number when translating.
Use comments if needed. <!-- comment words -->
Use switchable comment text for FIXME. <![%FIXME;[Describe issues here ...]]> [2]
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.
Mailing lists must be used effectively.
Respect threading in the ML and assign a good subject line.
Use "Reply-to" to the ML when responding to old topic in ML. (list-reply-to)
Try not to use "Reply-to-all" for ML.
New topics must have new title for ML.
Do not create a new topic by clicking "Reply-to" for ML.
Give people at least 3 days to respond for trivial things.
Give people at least 10 days to respond for important things.
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.)
Set umask to be 002 to create files/directories as 664/775 or:
$ chmod -R g+w *
You can always remove a file (Be careful though).
$ cp foo bar
$ rm foo
$ vim bar
$ mv bar foo
Change content of all CVS/Root content to your account if you want to update on the same tree. (You can create new one and move them into the place too.)
$ perl -pi -e 's,:osamu@,:yourname@,g' $(find . -path '*/CVS/Root')
All important files are archived in CVS (htdocs for web page).
Edit web page in CVS locally and update it in shell account.
Peek into my home directory for the examples (/home/users/o/os/osamu).
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.
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.
Continuous activities:
Spell and grammar corrections.
Factual corrections.
Experiment with po-debiandoc.
Add/remove some prospectus contents to README.org.
Structual road map and prerequisite:
Rebump build script. (anytime soon when Jens is ready.)
Experiment with po-debiandoc. (when someone can add short howto in this manual and understand what to do.)
Move CVS to debian-doc CVS or alitoh CVS on Debian system. (when someone can do this.)
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:
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.
apache and simple CGI programing. (tune.sgml and program.sgml)
DNS for simple behind firewall LAN. (tune.sgml after mail or gateway.sgml)
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.
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):
translate the website (htdocs module), add the new language code to htdocs/index.php for content negotiation
translate the debian-reference manual page
update bin/getdocdate (outputs the date in your preferred format)
select hyphenation patterns in texmf/language.dat
update makeindexhtml
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.
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 2005osamu#at#debian.orgtux-master#at#web.de