On Sat, 23 Jul 2011 13:30:00 +0200 MadMax wrote:
first a big sorry: Since we just finished with daps the documentation
of our toolchain is hopelessly outdated.
> I asked earlier the help you offered. But after some attempts to make
> the PDF I realised I missed something. So I installed susedoc and now
> I am able to reproduce a PDF. My first step is made.
hmm. It is _not_ necessary to install susedoc when having installed
daps (once the final version of daps will be released, it will not be
possible to install both programs in parallel). daps is the successor
> Again, I never worked with documentation programs, so I need a crash
> course to read somewhere. I am an absolute beginner in writing
> documentation with xml.
OK - the most important part to begin with is: don't be scared off by
XML source code - it's _much, much easier_ than it seems.
Have you ever written HTML pages with a non WYSIWYG editor or are you
able to understand HTML source code? Writing DocBook XML is almost the
same as writing HTML (The main differences are different tag names and
a bit more structure in DocBook).
> So, where do I start to read?
When I joined the Documentation Team I simply opened a PDF with one of
our manuals and the corresponding XML files side-by-side. I read the
XML source code and whenever I was unsure what a certain tag/structure
would look like, I had a look at the PDF.
If that does not work for you, we can schedule an IRC session where I
can teach you the most important things.
> Maybe it is a good idea to use the opensuse
> wiki for documenting my experience. I can write my experience and
> things I think I needed on
> What I did so far.
> I downloaded the xml source with svn. I recognize text in the xml
> files. I browsed through some files. I think I can work with that.
> I installed DAPS. But all my attempts with DAPS will not deliver any
I have an idea why - the format of the ENV-files has changed from
susedoc to daps and the tags directory has the susedoc-ENVfiles. Sorry
that I missed that in my initial mail.
I have created a new directory for you
which you can use for your translations (you should have read-write
permissions tomorrow at latest). I have updated the ENVfiles to be daps
Assuming you downloaded the SVN stuff to
All you need to do to build a PDF from the e.g. Start Up manual is to
daps -e ENV-opensuse-startup color-pdf
> I found the editor EMACS, but don't know what to do with it. I read
> the emacs macro link somewhere to simplify the use of xml dtd schema.
> But how, I do not understand. Even after reading
> I am used to Kate for php programming, or editing other basic text
> documents. So I need to learn Emacs, if that is the tool for docbook
> xml. Can you give directions here? I understand its a struggle to
> choose the right tools from
More often than not tools are subjects of religious wars rather than
subject of a neutral discussion. There is only _one_ aspect that
matters in regards of tools:
_You_ have to be familiar with them and you have to like them.
So if you are familiar with Kate, use Kate to edit the DocBook XML
files. Kate has a (DocBook) XML mode and is well suited for editing XML
documents (see http://l10n.kde.org/docs/tools.php)
[My editor of choice is emacs. To make my life easier, I have written a
macro package for emacs that automates some common tasks when writing
DocBook XML. But that macro package just adds a bit of convenience,
nothing more. there is absolutely no need to learn emacs in order to
write DocBook. _Every_ text editor is suited to write DocBook.
However, some editors, among them Kate and emacs, have special XML
plugins which make it easier to write DocBook.]
With KDE 4.5 the Kate XML plugin also supports auto-completion of tags,
which makes editing XML very comfortable.
> I subsribed to berlios. Username Max_23. So I can use svn if I knew
OK, here is a very brief instruction on SVN.
SVN (subversion) is a version control system. Such a system keeps
control of all versions of the files it hosts and allows multiple users
to work on the same files.
The "master copy" of the files is hosted on the subversion server.
When you are working on files hosted on an subversion server, you
first have to "check them out" (download them) in order to create your
own local copy.
Now you can start working on your files _locally_. All the changes you
do you do to your local files only. If you want to push your changes
into the master copy on the server, you have to "commit" (upload) your
The server then computes the differences between your submission and
the master copy (diff) and merges these changes into the master copy.
Using such a mechanism allows it to merge submissions from different
contributors into one master copy. Only when two persons made changes
on the same part of a file such a merger results into a conflict which
has to be solved manually.
The most important svn commands (see svn help or svn <command> help
for more information):
svn checkout: Initial check out (download) from server. Needs to be
done only _once_
svn update: Update your working copy to the latest version
(called HEAD) of the master copy on the server
svn log: View the history of a file
svn commit: Commit (upload) your local changes to the server
svn revert: Revert your local changes of a file and restore the
latest version from the server
svn diff: Show differences between your local file and the one on
svn add: Add a file/directory
svn status: Compare your local working directory with the one on the
server to see waht has changed locally (e.g. which files
have been modified, deleted or added)
The important paradigmas you need to understand are:
* _Everything_ (incuding adding, deleting or moving files) you do will
happen within your _local_ copy _only_ until you commit your changes.
So before commiting your changes, make sure everything in your local
copy is as you would like to have it (make use of svn status)
* It is almost impossible to entirely break things. Since subversion
keeps track of all revisions of all files, you can always go back to
an old version of a file, a subdirectory or even of the complete
* Submit early and often - subversion is your external backup
> I don't understand which work flow to follow.
0. Initial step, need to do it once:
Check out your working directory from the server:
svn co \
And then, your normal routine would look like the following:
1. Update your local working copy:
2. Open <FILE> in editor and edit/translate it
3. Save the file
Once finished, check if the DocBook XML is still valid:
daps -e ENV-openSUSE-all validate
4. If not valid, fix your XML -> back to step 2.
5. Build a PDF or an HTML version of the book you are currently
translating to check what you have done
daps -e <ENVfile> color-pdf
5. If valid, submit your changes to the server:
svn ci -m "Started translation of FILE, still WIP" <FILE>
(The text you specify with -m is a log message that can be seen with
svn log - always use meaningful log messages!)
6. start over with 1.
> I read a big part of docbook.org. But all that teached me of xml use.
> I gave up there.
Don't confuse yourself with too much reading about DocBook. Just look
at the existing files and if there is something you do not understand,
ask on IRC or via mail. As said above, it's much easier than it looks
> I like to find some story about the opensuse books, how it all works
> together. I understand it must be simple. But how?
Finally a general not about our working environment:
1. The directory structure:
| | |--dia/*.dia
| | |--fig/*.fig
| | |--png/*.png
| | |--svg/*.svg
2. XML files
the xml files are placed under the XML subdirectory. In DocBook you can
include one xml file into another with <xi:include ...> statements.
Thus you do not need to have only one huuuuge file for each book but
rather a set of small files and you can also reuse files in different
books. We name our files according to the hierachy:
xml/MAIN.opensuse.xml (the complste set: all openSUSE books)
xml/book.* (a single book)
xml/*.xml (the rest, singles chapter or sections
usually (but not always) prefixed with the book
name, e.g. security-*)
The configuration files for the books. Each ENVfile represents on book
and therefore needs to be specified with each daps command.
ENV-opensuse-all The complete set (all openSUSE books)
ENV-opensuse-html The complete set (all openSUSE books)
ENV-opensuse-kvm Virtualization with KVM
ENV-opensuse-reference Reference Guide
ENV-opensuse-security Security Guide
ENV-opensuse-tuning Tuning Guide
4. Which files belong to which book:
XML files: daps -e <ENVFILE> projectfiles -p
Images: daps -e <ENVFILE> projectgraphics -p
Frank Sundermeyer, Technical Writer, Documentation
SUSE Linux Products GmbH, Maxfeldstr. 5, D-90409 Nuernberg
Tel: +49-911-74053-0, Fax: +49-911-7417755; http://www.opensuse.org/
SUSE Linux Products GmbH, GF:
Jeff Hawn, Jennifer Guild, Felix Imendörffer, HRB 16746 (AG Nürnberg)
"Reality is always controlled by the people who are most insane" Dogbert
To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org
For additional commands, e-mail: opensuse-doc+help(a)opensuse.org