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).