Re: DOCBOOK-APPS: Experiences as Authors

[Ian Castle <ian.castle@coldcomfortfarm.net>]

On Thu, 2002-11-28 at 18:53, Stephan Wiesner wrote:
> Hi list,
> I would like to get some feedback on how others actually write their
> documents. And I don't mean those with one or two DocBook documents, but
> those with tons of them.
> 
> Of special interest is: how do you handle stuff that reappears like
> biblioentries, glossary, quotes, about the author. How do you keep it up
> to date if it is included/refrenced in different documents.

I have a "library" of common items - such as copyright notices and so
on. Each one is an entity. The documents include the entity at the
relevant point. If an entity definition changes, then it only needs to
be changed in the one place.

Everything is in CVS. Documents tend to be modular (say one chapter per
file).

make is used to drive the production of the document.

Multiple authors are able to work on documents using whatever editor
they like. 

Common material is kept in a central place.

Catalogs are used to avoid the use of file system specific names. This
means that people can work on the documents on different machines,
remotely, and even with different operating systems.

Example:

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" [
<!ENTITY % library
  PUBLIC "-//LOOK Systems//ENTITIES Standard Terms Library//EN">
%library;
<!ENTITY module1 SYSTEM "module1.xml">
<!ENTITY module2 SYSTEM "module2.xml">
<!ENTITY module3 SYSTEM "module3.xml">
<!ENTITY module4 SYSTEM "module4.xml">
<!ENTITY module5 SYSTEM "module5.xml">
<!ENTITY module6 SYSTEM "module6.xml">
<!ENTITY module7 SYSTEM "module7.xml">
<!ENTITY module8 SYSTEM "module8.xml">
<!ENTITY module9 SYSTEM "module9.xml">
<!ENTITY module10 SYSTEM "module10.xml">
<!ENTITY module11 SYSTEM "module11.xml">
<!ENTITY module12 SYSTEM "module12.xml">
]>
<book>
...
  <legalnotice>&LegalWording;</legalnotice>
...

..

&module1
..

</book>


So the entity &LegalWording is contained in the Library of terms, which
is referred to by a public identifier.
The book is made up of a number of entities (each module).






> 
> 
> To get started, I will now describe how I do it. However, otherwise I
> would not write this mail, I am not really happy with this.
> 
> I wrote a tool that helps me manage my glossary, bibliography and
> blockquotes and just copy those elements I need to a new document. This
> works very good, except when I have to change something and have to find
> all documents including those elements. I could just reference them
> instead of inclusion, with entities for example, but then I might have a
> lot of work if I switch to a different computer.
> 
> 
> Any comments are appreciated
> 
> Stephan
-- 
Ian Castle <ian.castle@coldcomfortfarm.net>