would anybody be so nice to outline the setup for a set of books for me or point me to some examples? Let's say I want to have three books Book_A, Book_B, and Book_C. How should the MAIN-, DC- and Book-XML files look like? Especially the headers for DocBook 5. I just started learning XML and DocBook so I am sure that I can not completely follow the DAPS documentation. Is a root file MAIN.xml like the following a good start?
I just started learning XML and DocBook so I am sure that I can not completely follow the DAPS documentation. Is a root file MAIN.xml like the following a good start?
Sorry, forgot to mention that in my previous answer.
Yes, that is a good start if you would like to maintain a set of different books. With this setup, it is possible to create cross references from one book into another.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
would anybody be so nice to outline the setup for a set of books for me or point me to some examples?
we have a couple of public Git repositories, published under a free license (usually GFDL). The following links point to the official SUSE documentation:
The repositories contain everything of our documentation. Look for the MAIN*.xml files. They have a <set> element and books are xincluded.
The filenames can be choosen freely. Of course, it would be good practise to invent some common, consistent naming scheme. Our main entry point is the mentioned MAIN*.xml files. Books are named book*.xml and articles contain art*.xml. Chapter files don't have any convention. Oh, by the way, files which are used for different books are named common*.xml.
That's our convention. You are free to choose whatever you like.
Oh, keep in mind, the files make heavy use of "profiling" (some kind of "conditional text").
If you have any question, just ask.
Have fun!
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
wow! Thank you for the fast and very helpful answer. The examples from the SUSE documentation will help me a lot. Everything is fine with your documentation. The problem is lack knowledge on my side. I have to get used to some main concepts. For example, when you write
In this example, art.daps.quick is the root ID of the DAPS Quick Start, contained in MAIN.DAPS.xml
I did not know that root ID actually is a tag within the quick start xml file. But now I have some guidance with the SUSE documentation.
Thank you very much.
Best regards,
Willi
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Everything is fine with your documentation. The problem is lack knowledge on my side.
Ok, thanks. Let us know when you find some issues in our documentation.
I have to get used to some main concepts
Yes, I know, if you don't use it daily (as we do) some concepts looks quite strange at a first glance. ;)
I did not know that root ID actually is a tag within the quick start xml file.
Actually it's an attribute. The term "root id" is coined from the upstream DocBook XSL stylesheets: It is used to identify a specific part of your complete documentation.
For example, if you have a book and you are only interested in transforming a single, specific chapter from that book, you need something to identify this chapter. Of course, this identification should be unique throughout the whole book.
In DocBook, this "uniqueness" is created by the id (DocBook 4) or xml:id (DocBook 5) attributes. And this is the "root id" which you can point to.
That's the reason why we have so many different DC* files: they point to the MAIN* file, but contain the ID (root id) for a specific book or article.
Hope that makes sense. :-)
Last edit: Thomas Schraitle 2015-12-04
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
View and moderate all "DAPS General Discussion" comments posted by this user
Mark all as spam, and block user from posting to "Discussion, old (read-only)"
Dear All,
would anybody be so nice to outline the setup for a set of books for me or point me to some examples? Let's say I want to have three books Book_A, Book_B, and Book_C. How should the MAIN-, DC- and Book-XML files look like? Especially the headers for DocBook 5. I just started learning XML and DocBook so I am sure that I can not completely follow the DAPS documentation. Is a root file MAIN.xml like the following a good start?
Is there a best practice for organizing the files if I would like to have separate files for books and chapters, like
book_set/
DC-Book_A
DC-Book_B
DC-Book_C
--images/
--xml/
MAIN.xml
book.book_a.xml
book.book_b.xml
book.book_c.xml
book.book_a.ch_preface.xml
book.book_a.ch_overviews.xml
book.book_a.ch_howtos.xml
book.book_b.ch_preface.xml
book.book_b.ch_overviews.xml
book.book_b.ch_howtos.xml
Thank you very much.
Best regards,
Willi
Sorry, forgot to mention that in my previous answer.
Yes, that is a good start if you would like to maintain a set of different books. With this setup, it is possible to create cross references from one book into another.
Do you miss anything particular? Any recommendations how to improve the documentation?
If you like, enter an issue on our GitHub project: https://github.com/openSUSE/daps/issues/new
Regarding the files, we have something in our DAPS documentation:
http://opensuse.github.io/daps/doc/cha.daps.user.features.html#sec.daps.user.basics.files
Hi Willi,
we have a couple of public Git repositories, published under a free license (usually GFDL). The following links point to the official SUSE documentation:
The repositories contain everything of our documentation. Look for the
MAIN*.xmlfiles. They have a<set>element and books are xincluded.The filenames can be choosen freely. Of course, it would be good practise to invent some common, consistent naming scheme. Our main entry point is the mentioned
MAIN*.xmlfiles. Books are namedbook*.xmland articles containart*.xml. Chapter files don't have any convention. Oh, by the way, files which are used for different books are namedcommon*.xml.That's our convention. You are free to choose whatever you like.
Oh, keep in mind, the files make heavy use of "profiling" (some kind of "conditional text").
If you have any question, just ask.
Have fun!
View and moderate all "DAPS General Discussion" comments posted by this user
Mark all as spam, and block user from posting to "Discussion, old (read-only)"
Hello Thomas,
wow! Thank you for the fast and very helpful answer. The examples from the SUSE documentation will help me a lot. Everything is fine with your documentation. The problem is lack knowledge on my side. I have to get used to some main concepts. For example, when you write
I did not know that root ID actually is a tag within the quick start xml file. But now I have some guidance with the SUSE documentation.
Thank you very much.
Best regards,
Willi
Hi Willi,
you're welcome! :-)
Ok, thanks. Let us know when you find some issues in our documentation.
Yes, I know, if you don't use it daily (as we do) some concepts looks quite strange at a first glance. ;)
Actually it's an attribute. The term "root id" is coined from the upstream DocBook XSL stylesheets: It is used to identify a specific part of your complete documentation.
For example, if you have a book and you are only interested in transforming a single, specific chapter from that book, you need something to identify this chapter. Of course, this identification should be unique throughout the whole book.
In DocBook, this "uniqueness" is created by the
id(DocBook 4) orxml:id(DocBook 5) attributes. And this is the "root id" which you can point to.That's the reason why we have so many different
DC*files: they point to theMAIN*file, but contain the ID (root id) for a specific book or article.Hope that makes sense. :-)
Last edit: Thomas Schraitle 2015-12-04