27 Jul
2011
27 Jul
'11
21:12
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: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org