RE: [docbook-tc] Sample of Assembly

["Rowland, Larry" <larry.rowland@hp.com>]

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 <larry.rowland@hp.com>:
> I have coded up a sample of an assembly, which is attached.


> The attached file is presumed to be documenting a document build
> environment that uses Ant to provide build targets from the command line
> and also has a Web based GUI with a Subversion repository to provide
> authoritative builds based on pulling top of tree of source files and
> executing the same Ant targets used to build from the command line.


Could you provide a little more context please Larry?

I'm not familiar with the terms you're using?


TIA


-- 
Dave Pawson
XSLT XSL-FO FAQ.
Docbook FAQ.
http://www.dpawson.co.uk