Frank Sundermeyer wrote:
> On Sat, 23 Jul 2011 13:30:00 +0200 MadMax wrote:
>
> Hi,
>
> first a big sorry: Since we just finished with daps the documentation
> of our toolchain is hopelessly outdated.
I'll manage with your help. This _very_ extensive e-mail gave me a lot 
of information. And I didn't receive it until today, 27 july. My 
webhoster decided to move their hardware to a new location, without 
notice. But I'm very happy with it now.
In the last days I installed several new releases of daps. So I noticed 
you have been busy. Even today I got a new version.
>> 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
> of susedoc.
Ok, I try without susedoc and use daps and the new ENV-files.
>> 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).
I'm not scared easily of a little learning. I can read several 
languages, so xml won't be a big problem. Only the implementation of the 
dtd and the choice of variables are still puzzling. But I'll learn that 
later.
>> 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.
I managed that already (with susedoc) and will continue with daps.
More help will be asked. But I start with translating the  text.
>> 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
>> http://en.opensuse.org/openSUSE:Documentation_Contribute
> Sounds good.
>> 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
>> PDF.
> 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
> https://svn.berlios.de/svnroot/repos/opensuse-doc/trunk/documents/distribution/nl/
> which you can use for your translations (you should have read-write
> permissions tomorrow at latest). I have updated the ENVfiles to be daps
> compatible.
Thank you. This was the missing piece of the puzzle. Now I can use daps. 
Daps didn't understand the ENV-files earlier.
>
> Assuming you downloaded the SVN stuff to
> ~/suse/doc/trunk/documents/distribution/nl/
>
> All you need to do to build a PDF from the e.g. Start Up manual is to
>
> cd ~/suse/doc/trunk/documents/distribution/nl/
> 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
>> http://en.opensuse.org/openSUSE:Documentation_Emacs_Docbook_Macros
>>
>> 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
>> http://en.opensuse.org/openSUSE:Documentation_Contribute#How_to_Contribute
> 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)
I read it, activated the xml plugin. This helped also. Something to put 
up on the wiki, by me.
> [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
>> how.
> 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
> local changes.
> 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  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
>                the server
> 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
>    repository
> * Submit early and often - subversion is your external backup
>
>
>> I don't understand which work flow to follow.
> Pretty easy:
>
> 0. Initial step, need to do it once:
>     Check out your working directory from the server:
>     svn co \
>     https://svn.berlios.de/svnroot/repos/opensuse-doc/trunk/documents/distribution/nl/
>
> And then, your normal routine would look like the following:
>
> 1. Update your local working copy:
>     svn up
> 2. Open  in editor and edit/translate it
>     kate
> 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  color-pdf
> 5. If valid, submit your changes to the server:
>     svn ci -m "Started translation of FILE, still WIP"
>     (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 think I make some time coming weekend to submit the first work. I made 
the first PDF and it's looking good.
I'm used to usefull messaging when updating work (by example in a wiki). 
I hope to continue that with svn.
>> 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
> like.
>
>> 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:
Understood, thanks for the detailed description.
> 1. The directory structure:
>
>   distribution/nl/
>                |-ENV-opensuse-*
>                |--images/
>                |    |--src/
>                |    |   |--dia/*.dia
>                |    |   |--fig/*.fig
>                |    |   |--png/*.png
>                |    |   |--svg/*.svg
>                |--xml/*.xml
>
> 2. XML files
>
> the xml files are placed under the XML subdirectory. In DocBook you can
> include one xml file into another with  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-*)
>
> 3. ENVfiles
>
> 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-startup		Start-Up
> ENV-opensuse-tuning		Tuning Guide
>
> 4. Which files belong to which book:
>
> XML files:	daps -e  projectfiles -p
> Images: 	daps -e  projectgraphics -p
>
>
So, to work then! I get do something, makes me excited.

Greetings,

Max


-- 
To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org
For additional commands, e-mail: opensuse-doc+help@opensuse.org