
Keeping Docs in SVN
-------------------

The xml documents are kept in a SVN repository as well. Explode and
implode are used to synchronize with DocBookWiki (the XML chunks), and
the SVN commands to synchronize with the SVN repository. This is
usefull for keeping track of modifications, as a backup way, to
synchronize them with another DocBookWiki, to modify the docs with an
editor (e.g. Emacs) and then synchronize (merge modifications) with
the DocBookWiki, etc.

These tasks are automated and simplified by the scripts in SVN/.
Initially, when docbookwiki is installed, the script 'init.sh' is
called to initialize the svn repository. By default it creates a
standard local svn repository. However, 'init.sh' can also be called
later, in order to setup a svn repository different from the standard
one, for example a remote repository:

  bash$ ./init.sh help
  Usage: ./init.sh [svn_dir] [repository]
  where 'svn_dir'     is the name of the SVN directory that will keep the docs
  and   'repository'  is the SVN repository, e.g. http://server/path

  bash$ ./init.sh 
  ./init.sh: It seems to be already initialized, use './clean.sh' first

In order to re-initialize the SVN repository, it has to be cleaned
first using the script 'clean.sh'.

Whenever a document is imported in docbookwiki, it is added
automatically to the SVN repository, and whenever a book is deleted
(cleaned) from docbookwiki, it is deleted from the SVN repository as
well. However, the list of the docs that are maintained in SVN is
different from the list of docs that are in docbookwiki. Documents can
be added or deleted from SVN independently from the import and clean
of docbookwiki. The scripts 'add_book.sh' and 'del_book.sh' can be
used for this purpose.

  bash$ ./add_book.sh 
  Usage: ./add_book.sh book_id [lng]
  where lng can be en, de, fr, it, sq_AL, etc. (default is en)

  bash$ ./del_book.sh 
  Usage: ./del_book.sh book_id [lng]

The list of all the documents in SVN is kept in the file 'book_list'
(which is updated automatically whenever a new book is added or
deleted). The list of documents kept in SVN can be different from the
list of all the documents in docbookwiki. After the installation both
of the lists are the same, however later you can delete some books
from SVN. Or you can clean SVN (delete all the books, repositories
etc.) initialize it again to another repository (maybe a remote one),
and then add back some of the books of docbookwiki.

The documents for which downloads of other formats are generated are
the documents that are kept in SVN, since they are checked out from
there. A document that is imported in docbookwiki but is removed from
SVN is a document which you do not want to maintain (make
modifications, commit and then update the downloads). Usually such a
document is imported in docbookwiki just for publishing it online.

Some other scripts in the directory SVN/ are these:

    * 'commit.sh' can be used to commit to SVN the latest changes made
      in the docbookwiki copy (only the changes in the public copy,
      not the unapproved changes):

        bash$ ./commit.sh
        Usage: ./commit.sh book-id [lng]
        where lng is en, de, fr, it, al, etc. (default is en)

        bash$ ./commit.sh docbookwiki_guide

    * 'update.sh' can be used to get from SVN the latest changes and
      apply them to docbookwiki:

        bash$ ./update.sh
        Usage: ./update.sh book-id [lng]
        where lng is: en, de, fr, it, al, etc. (default is en)

    * 'sync.sh' can be used to synchronize the changes both ways:

        bash$ ./sync.sh
        Usage: ./sync.sh book-id [lng]
        where lng is: en, de, fr, it, al, etc. (default is en)

      It doesn't work yet for media files, they have to be syncronized
      manually.

Besides these, there are also the scripts 'commit-all.sh',
'update-all.sh' and 'sync-all.sh' which perform the actions to all the
books in SVN.


Automatic Email Notification on Commit
--------------------------------------

The script 'SVN/email-notifications.sh' is used to enable/disable
automatic notifications on commit:

  bash$ ./email-notifications.sh 
  Usage: ./email-notifications.sh [ on | off | ls ]

Whenever the docs are committed in SVN, notification emails are
generated and sent automatically about the modified books and their
diffs. This is done by the svn hook 'post-commit' , which calls the
script 'commit-email.pl' to send emails to the admin of
DocBookWiki. The email of admin is taken from the variable ADMIN_EMAIL
in 'books.conf' during installation, however 'post-commit' can be
modified manually later, to change the email to which the
notifications are sent.

'commit-email.pl' calls the script 'txt_diff.sh' to get the
difference. 'txt_diff.sh' gets the old and new revisions from SVN,
converts them to text format and then makes a unified diff of
them. This is done to make the diffs more readable. However if there
are problems with converting to text format (e.g. validation
problems), it will produce no output at all.

The script 'content/SVN/commit_all.sh' can be executed automatically
every night by cron:

  bash$ crontab -e
  02 5 * * * /var/www/html/tools/docs/content/SVN/commit_all.sh

It will commit in SVN any modifications made in the books during the
day, and will send automatically email notifications.


