XML RESUME LIBRARY - Development System

This is the developer's layout for the source of the XML
Resume Library.  If you're seeing this file, it's
assumed you know CVS, Ant, XML, XSL, and are generally
aware of what you're doing.

The Ant build.xml File
======================

The build.xml file describes this project to the Ant
build system.  If you don't yet have Ant, you can get a
copy from http://jakarta.apache.org/ant/.  You can then
run "ant -projecthelp" to see a list of what's possible
for this project.

A useful alias for ant is "ant -find build.xml".  This
causes Ant to search upwards through a directory tree to
find the build.xml file instead of looking for it in
just the current directory.

Properties
==========

You can define properties to override the defaults in
the build.xml file by creating a .ant.properties file in
your home directory.

Currently, there's just one interesting property to override:

- resume.web.publish.dir

  This property indicates the directory into which we publish any
  web-accessible files from the system, such as the resume DTD.
  This property is used during "ant install".

Getting Help
============

If you want to know what each of the Ant targets do, run

   ant -projecthelp

DTD Changes
===========

If you change (add, remove, modify, or deprecate elements or attributes) the
DTD, please also do the following:

1. Update src/doc/manual/en/elementref/intro.xml, which is user-visible DTD
   change documentation.

2. Write or modify appropriate reference pages. If you've added elements, run
   "ant doc.manual.create-missing" to automatically generate skeleton
   documentation files. Then search for "TODO" in the generated files, replacing
   with appropriate content.

Deprecating elements takes a bit more work than adding or changing them:

1. Elements that are deprecated should be documented as so in the appropriate
   parts of the user guide. Specific information on doing so is in
   src/doc/manual/AUTHORING.

2. In addition, the XSLT stylesheets for resume generation should emit a message
   to the user upon encountering a deprecated element. (However, the element
   should still be formatted properly.) This message should be in
   src/www/xsl/lib/deprecated.xsl.

3. If possible, an "upgrade" XSLT file should be produced that automatically
   removes or converts deprecated elements in a user's resume. See
   src/www/xsl/misc/13x-140.xsl for an example.

Cutting a Release
=================

NOTE: See 
http://sourceforge.net/docman/display_doc.php?docid=10468&group_id=29512
for a better-formatted version of the following instructions

To cut and post a new release the XML Résumé Library, you will need two 
modules from CVS: resume and resume-website. Check them out into one 
directory so that you have the following structure: 

some-dir/resume
some-dir/resume-website

* * * *  Install the new release files

  cd resume
  ant clean
  cvs update -d		# to make sure you've got the latest changes
  cvs commit 		# to make sure your own changes are in
			# (cleaning up any merge conflicts)

**** Confirm functionality by: 
  ant run.test		# to run regression tests
  ant run.generate	# to generate new regression test data (optional)
Format the example résumés
Format the address test résumés
Format your own résumé

**** Update the documentation files: 

	ant doc.manual.check	# ensure there are no elements in the DTD 
				# without a reference page in the manual. 
If there are missing pages, run 
	ant doc.manual.create-missing
Then do a search-and-replace for "TODO" in all of the created files, 
making changes as appropriate.

Edit:
	src/doc/release/news/index.html 
		for user-visible changes (required with every release).  
	src/doc/manual/en/elementref/intro.xml
		for DTD changes.  (You can run 
		cvs update -p -r release-major_minor_sub \
		src/www/dtd/resume.dtd > resume.old.dtd 
		to retrieve the last release's DTD for easy diff-ing with 
		the current one.)
	src/doc/index.html for usage instructions on specific features 
	Other files as necessary 

**** Update etc/rcs2log if necessary. 

**** Run etc/rcs2log | etc/cltohtml | etc/replace_changelog.py 
	(required with every release).
**** Commit src/doc/release/changelog/index.html to CVS.  
**** Edit build.xml and update version numbers. 
**** Commit the changed documentation and support files. 
**** 	rm -rf ~/htdocs 
**** "ant release ftp upload.sf.net" as anonymous and
	upload the .tgz and the .zip files to the /incoming directory.  
**** ant install cvs tag release-major_minor_sub to tag the release.  
**** cd ../resume-website 
**** Edit src/www/index.html to add a news item announcing the release. 
**** Edit build.xml to match the version number in ../resume/build.xml. 
**** cvs commit 
**** ant install 
**** cd ~ chmod -R g+w htdocs 
**** tar czf htdocs.tgz htdocs 
**** scp htdocs.tgz shell.sf.net:

 * * * * Create the new release

Visit www.sf.net and log in, if necessary.
Go to http://www.sourceforge.net/projects/xmlresume/.
Go to Admin.
Go Edit/Release Files.
Click Add Release to the xmlresume package. Name the release major.minor.sub. 
Paste in the news and changelogs (in HTML format) and click Update.
Check the .tgz and .zip files and click Add.
Set the .tgz file's processor to Any, file type to Source .gz; click Update.
Set the .zip file's processor to Any, file type to Source .zip, click Update.
Check the box next to I'm Sure and send the notice.

 * * * * Update the website

ssh into shell.sf.net.
cd /home/groups/x/xm/xmlresume
rm -rf htdocs
tar xzpf ~/htdocs.tgz
rm ~/htdocs.tgz

Finally, check out the project's web page and see how it looks. Try 
downloading both the .tgz and .zip files and see if they work.

And good luck.


Cleaning Up
===========

To clean up files generated after a release, run "ant
clean".

User's Guide
============

The XML Resume Project User's Guide is written in DocBook
XML. This allows us to easily convert it to various output
formats. (We currently generate single-file HTML, multi-file
HTML, and text.)

More information about the XML Resume Project User's Guide
and the tools required to build it is in
src/doc/manual/README. If you're going to be writing
documentation, please read the AUTHORING file in the same
directory.

Formatting the Examples
=======================

Formatting the example resumes from the developer's
edition requires a "make" command line that redefines
the fo_style, text_style, and html_style symbols to
point to the development area's copies and not the
official copies via HTTP.  Additionally, you should use
a CATALOG aware processor so that the local copy of the
DTD is found instead of the last stable release via
HTTP.  Here's a sample invocation:

make xsl_base=../src/www/xsl/ \
     resume=my-test \
     clean \
     all

This formats my-test.xml into all four possible
formats (html, text, fo, pdf).