Woops,
I guess jargon makes sense to the people who use it, or they wouldn't
be using it, but it should be avoided when trying to explain things ;-)
To make this more real, I started out basing this on documenting a
system we actually use for production.
1) Our content is stored in Subversion, which is a source control
system. It stores all the files: XML source, images, and anything
else associated with the document. Authors check in files as they
work. Top of tree is the most recently checked in versions of the
files. Source control allows us to track changes and revert to
earlier versions of the content when necessary. It also allows
writers to collaborate by pulling copies of the source files
associated with a project onto their system from the central
repository. We do not have a formal content management system
(like Documentum or Vasont), because for what we do a strategy
combined with source control has proven more appropriate.
2) Ant is a process control system based on XML files called build
files. Targets are what you use to invoke actions. Thus
"ant build.to.validate" triggers the transforms that preprocess
all the files for conditions and inclusion to produce a canonical
DocBook instance that can be pulled into an editor for validation.
This works from the command line (a.k.a. shell) and can be invoked
using BAT files on Windows systems. Each document has a build file
that sets the specific conditions for that document and imports the
main build targets from common ant files. We adopted Ant because
it uses XML files, which can easily be edited with the same tools
the content is created with and can also be generated by XSLT
transforms for some complex build processes.
3) We also have a build server with a CGI-based Web exposure of the
Subversion repository that allows builds of documents based on the
content that is checked into the repository. The source tree is
exposed on the server and as document modules are navigated into,
the CGI code provide Web pages that allow the user to select a
target and trigger the build. Being a GUI, it would be nice if it
had a help system (we use training and a Wiki now).
4) All final builds (a.k.a. authoritative) are done on the build server
so that we know that what we are shipping is checked into the source
control system.
Again, sorry for the jargon -- I was feeling a little rushed getting
this out -- I had hoped to finish it this weekend but life kept getting
in the way :-)
Regards,
Larry
Original Message-----
From: Dave Pawson [mailto:dave.pawson@gmail.com]
Sent: Wednesday, May 20, 2009 9:28 AM
To: Rowland, Larry
Cc: DocBook Technical Committee
Subject: Re: [docbook-tc] Sample of Assembly
2009/5/20 Rowland, Larry