Re: Novell / opensuse documentatie vertalen

classic Classic list List threaded Threaded
17 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: Novell / opensuse documentatie vertalen

Jos Poortvliet-2
Max,

I'm shamelessly replying to you sending this to the person whom I think
of when someone mentions openSUSE translations - Thomas Schraitle. I've
also CC'ed the opensuse-doc mailinglist (no idea if I'm subscribed or
what'll happen when I turn out not to be).

So your question is: where is the source of the starters guide to
openSUSE 11.4 to be found? The original is still to be found on the
Novell site (soon to be the SUSE.com site).

Now I had a look at the webpage of the documentation team:
http://en.opensuse.org/openSUSE:Documentation_team

And apparently they suck developers' brains out. Scary. But that page
also told me about this how-to:
http://en.opensuse.org/openSUSE:Documentation_Contribute
and I think you are looking for this:
http://en.opensuse.org/openSUSE:Documentation_Contribute#SVN_Structure

However, I might be wrong (it's been noted to happen) and in that case,
I'm sure Thomas or some other openSUSE documentation Wichtl (?) will set
me straight.

Cheers,
Jos

On 2011-07-16 MadMax wrote:

> Hoi Jos,
>
> Ik heb twee e-mailadressen van je gevonden en ga beide proberen.
>
> Op het Nederlandse opensuseforum heeft Ben Henderson zijn vertaling
> geplaatst van Start-up guide van Novell.
> http://forums.opensuse.org/nederlands-dutch/community/nl-how-tos/4621
> 79-opensuse-11-4-nl-starters-gids.html
>
> Het origineel staat hier:
> http://www.novell.com/documentation/opensuse114/
>
> Ik heb aangeboden deze gids na te kijken op type- en spelfouten.
> Alleen heeft Ben zijn werk gebaseerd op de PDF die je kunt
> downloaden. Dat is een monnikenwerk qua vertaling. Nu lees ik bij de
> Novelldocumentatie dat deze is gemaakt in DocBook. Of eigenlijk een
> Novellvariant daarvan. Het is vast een stuk eenvoudiger dit in de
> DocBook te vertalen.
> Ik heb deze wijsheid uit:
> About the Making of This Manual
>
> This book is written in Novdoc, a subset of DocBook (see
> http://www.docbook.org). The XML source files were validated by
> xmllint, processed by xsltproc, and converted into XSL-FO using a
> customized version of Norman Walsh's stylesheets. The final PDF is
> formatted through XEP from RenderX. The open source tools and the
> environment used to build this manual are available in the package
> susedoc that is shipped with openSUSE.
>
>
> Aangezien jij als Ambassadeur en ook werknemer van Novell misschien
> weet wie ik kan benaderen om een kopie van de DocBook-xml te vragen.
> Wij zouden graag een Nederlandse vertaling maken. Denk je dat
> mogelijk is?
>
> Groet,
>
> Max


signature.asc (205 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Re: Novell / opensuse documentatie vertalen

Thomas Schraitle-3
Hi Jos,

(removed my private address)

On Sunday 17 July 2011 Jos Poortvliet wrote:
>
> I'm shamelessly replying to you sending this to the person whom I think
> of when someone mentions openSUSE translations - Thomas Schraitle. I've
> also CC'ed the opensuse-doc mailinglist (no idea if I'm subscribed or
> what'll happen when I turn out not to be).

Thanks for the fame, but I'm not involved in translations at all. ;)
I think, Karl is the right person to ask (he reads opensuse-doc too) and he
does all the good things in and with translations.

 
> So your question is: where is the source of the starters guide to
> openSUSE 11.4 to be found? The original is still to be found on the
> Novell site (soon to be the SUSE.com site).

The source code is not available from the Novell site; it contains only the
end product (read: HTML and PDF).

The sources can be found in our documentation SVN at BerliOS:
  https://svn.berlios.de/svnroot/repos/opensuse-doc/trunk/documents

The project is hosted at BerliOS:
  http://developer.berlios.de/projects/opensuse-doc/

To create HTML or PDF, you need daps (Document Authoring and Publishing
Suite), the successor of susedoc. You can install it from OBS, repo
Documentation:Tools.

 
> [...]
> and I think you are looking for this:
> http://en.opensuse.org/openSUSE:Documentation_Contribute#SVN_Structure
> However, I might be wrong (it's been noted to happen) and in that case,
> I'm sure Thomas or some other openSUSE documentation Wichtl (?) will set
> me straight.

The structure is still correct.

Hope I could clarify some questions. If you still have some questions, just
ask. :)


--
Gruß/Regards,
    Thomas Schraitle

----------------------------------------------------------------------
SUSE LINUX Products GmbH   (o<   Tel:   +49-(0)911-740 53 131
Maxfeldstrasse 5           /\\   Documentation Specialist
90409 Nuernberg, Germany  _\_v   http://www.suse.com
SUSE LINUX GmbH, GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer, HRB 21284
--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Re: Novell / opensuse documentatie vertalen

Frank Sundermeyer
On Mon, 18 Jul 2011 09:12:40 +0200 Thomas Schraitle wrote:

Hi Max,

> > I'm shamelessly replying to you sending this to the person whom I
> > think of when someone mentions openSUSE translations - Thomas
> > Schraitle. I've also CC'ed the opensuse-doc mailinglist (no idea if
> > I'm subscribed or what'll happen when I turn out not to be).
>
> Thanks for the fame, but I'm not involved in translations at all. ;)
> I think, Karl is the right person to ask (he reads opensuse-doc too)
> and he does all the good things in and with translations.
>
sounds like you want to translate our manuals. If so, we can offer you
all the infrastructure you need.

> To create HTML or PDF, you need daps (Document Authoring and
> Publishing Suite), the successor of susedoc. You can install it from
> OBS, repo Documentation:Tools.

http://download.opensuse.org/repositories/Documentation:Tools/
to be precise. This is one part of the infrastructure we can offer. If
you need help with daps, just contact me. daps --help should give you a
first impression of what the tool can do. If you have already worked
with it's predecessor susedoc, there is a transition guide
at /usr/share/doc/packages/daps/README.upgrade_from_susedoc_4.x

We can also offer you SVN access to our documentation SVN at BerliOS
(http://developer.berlios.de/projects/opensuse-doc/) and add a
directory for your translations at
http://svn.berlios.de/svnroot/repos/opensuse-doc/trunk/documents/distribution/nl

The Hungarian, Japanese, Portuguese, and Russian translators are also
using the SVN.

And last but not least we can offer you support. If you have any
questions (incl. daps, stylesheets, svn, etc), contact us on this
list. The other translators are also subscribed here, so you might
benefit from their knowledge as well.

Regarding the BerliOS SVN:
You can anonymously checkout from the svn. "subversion" needs to be
installed on your machine. To check out the final 11.4 openSUSE
documentation, use the following command:

svn co \
http://svn.berlios.de/svnroot/repos/opensuse-doc/tags/documents/openSUSE/11.4/GM/en/

If you want to use the BerliOS SVN for your translations, please create
a BerliOS log in at https://developer.berlios.de/account/register.php
and let me know your Login Names.

When I know them I can grant you access to the project including
SVN check-in permission. Then I would copy the final Englisch 11.4
documentation sources to
http://svn.berlios.de/svnroot/repos/opensuse-doc/trunk/documents/distribution/nl
and you can start ... ;-)

--
Regards
        Frank

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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Re: Novell / opensuse documentatie vertalen

Karl Eichwalder
In reply to this post by Thomas Schraitle-3
Thomas Schraitle <[hidden email]> writes:

> Thanks for the fame, but I'm not involved in translations at all. ;)
> I think, Karl is the right person to ask (he reads opensuse-doc too) and he
> does all the good things in and with translations.

No, not documentation translation.  I'm somehow responsible for software
translations.

--
Karl Eichwalder                              SUSE LINUX Products GmbH
R&D / Documentation                          Maxfeldstraße 5
                                             90409 Nürnberg, Germany
GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer, HRB 16746 (AG Nürnberg)
--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Re: Novell / opensuse documentatie vertalen

Ben-90
In reply to this post by Frank Sundermeyer

Goodmorning all,

THX`s for all the info, i saw a lot of possibility`s for translating.
I going to try Daps i think.

@ Max, Yep there are some tools for the translation.
But i`m allready buzzy with opensuse reference in Draw, i will try to get  
it transfer in to Daps.

Ben Henderson


Op Mon, 18 Jul 2011 18:36:06 +0200 schreef MadMax <[hidden email]>:

> Hi All, Thank you for these detailed answers.
>
> @Jos, thanks for forwarding. It seems that some information could be  
> found on the wiki by me. But I'm happy with yours answers. I have to  
> learn some community communication stuff, I think. So if you have more  
> teaching to offer, I'm eager to learn.
> @Frank, thanks for the help offered regarding infrastructure. I'm not a  
> technical guy, so I have to put some effort in understanding the  
> directions you gave us. I have a fulltime day job, so I'll do this  
> trying in my spare evenings. I think I need till the end of the week to  
> come back on understanding the directions. And on the workload I have  
> asked for. :-)
> @Ben, do you understand the directions, help we got, and what to do?  
> Let's e-mail further (in Dutch) about tasks if you figured out what you  
> need.
>
> I will report back to you at the end of the week.
>
> Greetings,
>
> Max
>
>
> Frank Sundermeyer wrote:
>> On Mon, 18 Jul 2011 09:12:40 +0200 Thomas Schraitle wrote:
>>
>> Hi Max,
>>
>>>> I'm shamelessly replying to you sending this to the person whom I
>>>> think of when someone mentions openSUSE translations - Thomas
>>>> Schraitle. I've also CC'ed the opensuse-doc mailinglist (no idea if
>>>> I'm subscribed or what'll happen when I turn out not to be).
>>> Thanks for the fame, but I'm not involved in translations at all. ;)
>>> I think, Karl is the right person to ask (he reads opensuse-doc too)
>>> and he does all the good things in and with translations.
>>>
>> sounds like you want to translate our manuals. If so, we can offer you
>> all the infrastructure you need.
>>
>>> To create HTML or PDF, you need daps (Document Authoring and
>>> Publishing Suite), the successor of susedoc. You can install it from
>>> OBS, repo Documentation:Tools.
>> http://download.opensuse.org/repositories/Documentation:Tools/
>> to be precise. This is one part of the infrastructure we can offer. If
>> you need help with daps, just contact me. daps --help should give you a
>> first impression of what the tool can do. If you have already worked
>> with it's predecessor susedoc, there is a transition guide
>> at /usr/share/doc/packages/daps/README.upgrade_from_susedoc_4.x
>>
>> We can also offer you SVN access to our documentation SVN at BerliOS
>> (http://developer.berlios.de/projects/opensuse-doc/) and add a
>> directory for your translations at
>> http://svn.berlios.de/svnroot/repos/opensuse-doc/trunk/documents/distribution/nl
>>
>> The Hungarian, Japanese, Portuguese, and Russian translators are also
>> using the SVN.
>>
>> And last but not least we can offer you support. If you have any
>> questions (incl. daps, stylesheets, svn, etc), contact us on this
>> list. The other translators are also subscribed here, so you might
>> benefit from their knowledge as well.
>>
>> Regarding the BerliOS SVN:
>> You can anonymously checkout from the svn. "subversion" needs to be
>> installed on your machine. To check out the final 11.4 openSUSE
>> documentation, use the following command:
>>
>> svn co \
>> http://svn.berlios.de/svnroot/repos/opensuse-doc/tags/documents/openSUSE/11.4/GM/en/
>>
>> If you want to use the BerliOS SVN for your translations, please create
>> a BerliOS log in at https://developer.berlios.de/account/register.php
>> and let me know your Login Names.
>>
>> When I know them I can grant you access to the project including
>> SVN check-in permission. Then I would copy the final Englisch 11.4
>> documentation sources to
>> http://svn.berlios.de/svnroot/repos/opensuse-doc/trunk/documents/distribution/nl
>> and you can start ... ;-)
>>
>


--
Gemaakt met Opera's revolutionaire e-mailprogramma:  
http://www.opera.com/mail/
--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Re: Novell / opensuse documentatie vertalen

Frank Sundermeyer
In reply to this post by Frank Sundermeyer
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 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.

> 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
> 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.


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)

[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 <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
              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 <FILE> in editor and edit/translate it
   kate <FILE>
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
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:

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 <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-*)

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 <ENVFILE> projectfiles -p
Images: daps -e <ENVFILE> projectgraphics -p


--
Regards
        Frank

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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Re: Novell / opensuse documentatie vertalen

Bugzilla from madmax@teenspirit.nl
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 <para> 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<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
>                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<FILE>  in editor and edit/translate it
>     kate<FILE>
> 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 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<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-*)
>
> 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<ENVFILE>  projectfiles -p
> Images: daps -e<ENVFILE>  projectgraphics -p
>
>
So, to work then! I get do something, makes me excited.

Greetings,

Max


--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Re: Novell / opensuse documentatie vertalen

Thomas Schraitle-3
Hi Max,

On Wednesday 27 July 2011 MadMax wrote:

> [...]
> > 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.

What do you mean by "choice of variables"? From your paragraph I guess you
mean the element names, right?

In my opinion, you don't have to "learn" it in a classical way like a poem.
Usually most element names are self explanatory and can be guessed easily.
It's true, in comparision to HTML are DocBook element names a bit longer;
however, terseness was not a design issue for XML, neither for DocBook. :)
With a good XML editor, this is also not an issue.


> [...]
> I managed that already (with susedoc) and will continue with daps.
> More help will be asked. But I start with translating the <para> text.

Congratulations!

 
> [...]
> 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.

Sure, it's up to you to give meaningful log messages when you commit your
files. :)

I would recommend to submit your files as often as possible. Small changes are
easier to track and it's easier to revert them if something goes wrong. How
often you submit your files is subject to your personal preference.


> [...]
> So, to work then! I get do something, makes me excited.

Great! Whenever you need help, just ask.


--
Gruß/Regards,
    Thomas Schraitle

----------------------------------------------------------------------
SUSE LINUX Products GmbH   (o<  
Maxfeldstrasse 5           /\\   Documentation Specialist
90409 Nuernberg, Germany  _\_v   http://www.suse.com
http://lizards.opensuse.org/author/thomas-schraitle/
SUSE LINUX GmbH, GF: Jeff Hawn, Jennifer Guild,
Felix Imendörffer, HRB 21284 (AG Nürnberg)
--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Re: Novell / opensuse documentatie vertalen

Bugzilla from madmax@teenspirit.nl
Hi Thomas and Frank,

I committed my first xml file.


Thomas Schraitle wrote:

> Hi Max,
>
> On Wednesday 27 July 2011 MadMax wrote:
>> [...]
>>> 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.
> What do you mean by "choice of variables"? From your paragraph I guess you
> mean the element names, right?
>
> In my opinion, you don't have to "learn" it in a classical way like a poem.
> Usually most element names are self explanatory and can be guessed easily.
> It's true, in comparision to HTML are DocBook element names a bit longer;
> however, terseness was not a design issue for XML, neither for DocBook. :)
> With a good XML editor, this is also not an issue.
I don't mean the element names. I meant things like &instquick and
&productname. Where are these defined?

>
>
>> [...]
>> I managed that already (with susedoc) and will continue with daps.
>> More help will be asked. But I start with translating the<para>  text.
> Congratulations!
>
>
>> [...]
>> 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.
> Sure, it's up to you to give meaningful log messages when you commit your
> files. :)
>
> I would recommend to submit your files as often as possible. Small changes are
> easier to track and it's easier to revert them if something goes wrong. How
> often you submit your files is subject to your personal preference.
I have to get used to "often". I'm used to deliver my work at the end of
the job. I try to commit at least when I'm done with an article.
>
>
>> [...]
>> So, to work then! I get do something, makes me excited.
> Great! Whenever you need help, just ask.
>
>
I'll do.

Greetings,

Max
--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Re: Novell / opensuse documentatie vertalen

Frank Sundermeyer
On Thu, 28 Jul 2011 12:02:33 +0200 MadMax wrote:

Hi,

> I committed my first xml file.

congratulations!!
 
> I don't mean the element names. I meant things like &instquick and
> &productname. Where are these defined?

These things are called entities. Some entities are already predefined
by DocBook - I think (but am not sure) these are the same as for HTML:
(&amp; = &, &lt; = <, &gt; = >,...).

But DocBook also allows to define your own entities - useful to define
shortcuts (&sls; = SUSE Linux Enterprise Server) and useful for string
that may change in the future (&product; = Workingtitle).
Our custom entities are defined in

xml/entity-decl.ent
xml/network-decl.ent

--
Regards
        Frank

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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Re: Novell / opensuse documentatie vertalen

Bugzilla from madmax@teenspirit.nl
Ha, Thanks,

Some entities will be translated then. I preffer my "Books" with a Dutch
title.

Greets,

Max


Frank Sundermeyer wrote:

> On Thu, 28 Jul 2011 12:02:33 +0200 MadMax wrote:
>
> Hi,
>
>> I committed my first xml file.
> congratulations!!
>
>> I don't mean the element names. I meant things like&instquick and
>> &productname. Where are these defined?
> These things are called entities. Some entities are already predefined
> by DocBook - I think (but am not sure) these are the same as for HTML:
> (&amp; =&,&lt; =<,&gt; =>,...).
>
> But DocBook also allows to define your own entities - useful to define
> shortcuts (&sls; = SUSE Linux Enterprise Server) and useful for string
> that may change in the future (&product; = Workingtitle).
> Our custom entities are defined in
>
> xml/entity-decl.ent
> xml/network-decl.ent
>

--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Re: Novell / opensuse documentatie vertalen

Frank Sundermeyer
In reply to this post by Bugzilla from madmax@teenspirit.nl
On Wed, 27 Jul 2011 23:12:08 +0200 MadMax wrote:

Hi,

> Frank Sundermeyer wrote:
> > On Sat, 23 Jul 2011 13:30:00 +0200 MadMax wrote:

> 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.

yes - I am currently fixing bugs and adding missing functionality.
Seems we are almost done by now - I will release version 1.0 soon.

> 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

You do not have to bother with the DTD - this is handled by DAPS. The
only thing you need to make sure is to use correct declarations
(DocBook/NovDoc headers) in your XML files.

BTW: We are using a custom DTD called NovDoc. This is a subset of
DocBook 4.5 (so not all tags and attributes available in DocBook can be
used in NovDoc) and is 100% compatible with DocBook.

> > 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.

I did a bit of research on kate and it's XML support. Unfortunately
it's not 100% straight forward and whatsmore, kate from KDE 4.6
had a bug that affected XML support (the XML autocompletion). With
yesterday's KDE 4.7 release this has been fixed.
I am planning to add a README.kate to daps in order to explain how to
make kate DocBook ready. If time permits I will also create a Kate
snippet repository for DocBook and upload it to http://kde-files.org/.

--
Regards
        Frank

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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Re: Novell / opensuse documentatie vertalen

Frank Sundermeyer
In reply to this post by Bugzilla from madmax@teenspirit.nl
On Thu, 28 Jul 2011 12:26:56 +0200 MadMax wrote:

Hi,

> Some entities will be translated then. I preffer my "Books" with a
> Dutch title.

;-)

BTW: In case strings generated by the stylesheets like "Table of
contents", "Part" "Appendix"... are not translated correctly, just let
me know. This can be fixed by adjusting a specific file.

--
Regards
        Frank

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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Re: Novell / opensuse documentatie vertalen

Ben-90
Hej All,

I`m back again, i notice that you didn`t mis me at all

I saw there was a lot of mail contact in my absents (Danmark er god for  
ferie men der er ik internet)
Saw also that Max made a XML file, thats great.
@ Max Are you going to do all the translation again or using my Dutch  
translation instead.
there was no communication between us.

@ Frank can you please give me also the possibility for using the Berlios  
documents, i have a account as user benmh.
The software is installed on the machine.
I only have some problems with placing a picture in XML.

So i`m talking Dutch again and wil go on with the translation in to Dutch  
of openSUSE Reference.

Hilse
Ben Henderson



Op Thu, 28 Jul 2011 12:42:24 +0200 schreef Frank Sundermeyer <[hidden email]>:

> On Thu, 28 Jul 2011 12:26:56 +0200 MadMax wrote:
>
> Hi,
>
>> Some entities will be translated then. I preffer my "Books" with a
>> Dutch title.
>
> ;-)
>
> BTW: In case strings generated by the stylesheets like "Table of
> contents", "Part" "Appendix"... are not translated correctly, just let
> me know. This can be fixed by adjusting a specific file.
>


--
Gemaakt met Opera's revolutionaire e-mailprogramma:  
http://www.opera.com/mail/
--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Re: Novell / opensuse documentatie vertalen

Bugzilla from madmax@teenspirit.nl
Hoi Ben,

Nope, I didn't miss you. I was busy testing the translation workflow. ;)
I did translate the first document, mostly with your work. Changed only
a few things. I'm not planning to do all translations by myself. You
ought to help!
I e-mail later tomorrow to make arrangements of which workflow to
follow, and about dividing files between us. I'll begin with the startup
guide.

Greets,

Max

[hidden email] wrote:

> Hej All,
>
> I`m back again, i notice that you didn`t mis me at all
>
> I saw there was a lot of mail contact in my absents (Danmark er god
> for ferie men der er ik internet)
> Saw also that Max made a XML file, thats great.
> @ Max Are you going to do all the translation again or using my Dutch
> translation instead.
> there was no communication between us.
>
> @ Frank can you please give me also the possibility for using the
> Berlios documents, i have a account as user benmh.
> The software is installed on the machine.
> I only have some problems with placing a picture in XML.
>
> So i`m talking Dutch again and wil go on with the translation in to
> Dutch of openSUSE Reference.
>
> Hilse
> Ben Henderson
>
>
>
> Op Thu, 28 Jul 2011 12:42:24 +0200 schreef Frank Sundermeyer
> <[hidden email]>:
>
>> On Thu, 28 Jul 2011 12:26:56 +0200 MadMax wrote:
>>
>> Hi,
>>
>>> Some entities will be translated then. I preffer my "Books" with a
>>> Dutch title.
>>
>> ;-)
>>
>> BTW: In case strings generated by the stylesheets like "Table of
>> contents", "Part" "Appendix"... are not translated correctly, just let
>> me know. This can be fixed by adjusting a specific file.
>>
>
>

--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Re: Novell / opensuse documentatie vertalen

Thomas Schraitle-3
In reply to this post by Ben-90
Hi Ben,

On Friday 29 July 2011 [hidden email] wrote:
> [...]
> @ Frank can you please give me also the possibility for using the Berlios
> documents, i have a account as user benmh.

You should have now write permission. Please test it with your nl directory.
:)


> The software is installed on the machine.
> I only have some problems with placing a picture in XML.

Here is a small snippet. It inserts a title of an image which points to a
foo.png file:

  <figure id="fig.appl">
     <title>Give me an Meaningful Title</title>
     <mediaobject>
       <imageobject role="fo">
         <imagedata fileref="foo.png" width="80%"/>
       </imageobject>
       <imageobject role="html">
         <imagedata fileref="foo.png" width="90%" />
       </imageobject>
     </mediaobject>
  </figure>

Usually it's a good idea to place two imageobject inside mediaobject to
support different target formats. You can set the target formats in the role
attribute; for PDF it's "fo", and for HTML it's just "html". This is useful,
if you need different widths for PDF or HTML.

 
> [...]



--
Gruß/Regards,
    Thomas Schraitle

----------------------------------------------------------------------
SUSE LINUX Products GmbH   (o<  
Maxfeldstrasse 5           /\\   Documentation Specialist
90409 Nuernberg, Germany  _\_v   http://www.suse.com
http://lizards.opensuse.org/author/thomas-schraitle/
SUSE LINUX GmbH, GF: Jeff Hawn, Jennifer Guild,
Felix Imendörffer, HRB 21284 (AG Nürnberg)
--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Re: Novell / opensuse documentatie vertalen

Ben-90
Hi Thomas,

Thx.


Ben


Op Mon, 01 Aug 2011 09:42:22 +0200 schreef Thomas Schraitle <[hidden email]>:

> Hi Ben,
>
> On Friday 29 July 2011 [hidden email] wrote:
>> [...]
>> @ Frank can you please give me also the possibility for using the  
>> Berlios
>> documents, i have a account as user benmh.
>
> You should have now write permission. Please test it with your nl  
> directory.
> :)
>
>
>> The software is installed on the machine.
>> I only have some problems with placing a picture in XML.
>
> Here is a small snippet. It inserts a title of an image which points to a
> foo.png file:
>
>   <figure id="fig.appl">
>      <title>Give me an Meaningful Title</title>
>      <mediaobject>
>        <imageobject role="fo">
>          <imagedata fileref="foo.png" width="80%"/>
>        </imageobject>
>        <imageobject role="html">
>          <imagedata fileref="foo.png" width="90%" />
>        </imageobject>
>      </mediaobject>
>   </figure>
>
> Usually it's a good idea to place two imageobject inside mediaobject to
> support different target formats. You can set the target formats in the  
> role
> attribute; for PDF it's "fo", and for HTML it's just "html". This is  
> useful,
> if you need different widths for PDF or HTML.
>
>
>> [...]
>
>
>


--
Gemaakt met Opera's revolutionaire e-mailprogramma:  
http://www.opera.com/mail/
--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]