XMLResume2x: Manual

This manual is for version 0.2.1 of xmlresume2x!

How To Use xmlresume2x?

xmlresume2x is a CLI application, ie. you can only use it from the command line. You need to specify the XML resume file which you want to convert, the output format and the language, like this:

xmlresume2x -f latex-europecv -l en myresume.xml

The former converts the resume myresume.xml into a LaTeX file which uses the latex-europecv class. Have a look at the help screen for other available options.

If you are not satisfied with the way some things are transformed or named, you can specify your own configuration file. This allows you to override the default transformation settings.

The resume files have to conform to XML resume >=1.5.1, must not use deprecated elements and have to use the element <resume> as root element!

How It Works

The application itself is rather simple, the power lies in the configuration files. There are two types of configuration files, for formats and for languages. A format file is the equivalent to an XSL file: it defines how the XML file is translated. A language file contains phrases in a specific language which are then used in the format files.

When xmlresume2x is started, the given format and language files are read and the input file is translated accordingly.

Currently Available Formats And Languages

Formats: latex-europecv (for producing PDF and other formats supported by LaTeX), xhtml
Languages: English (en), German (de), French (fr)

Configuration Files

The configuration files are pure Ruby files, so you can use the full power of Ruby!

Basically, all you do in a configuration file is:

Define processors for specific XML elements
Define keywords for a specific language

Normally, these two actions are separated from each other and put into different files: one or more format files and one or more language files. This separation does not have to occur, as processors and keywords can be defined in any configuration file. However, this separation makes it easier to combine languages and formats.

The configuration files are normally located in the /usr/share/xmlresume2x directory. Format files should go into the sub directory format and language files in the sub directory lang.

List of available commands

This is a list of additional commands that can and should be used in configuration files (here is a description of them):

add_processor
processor
call_processor
keyword
get_value
get_children_value
load_config

Processors

Processors are the heart of the transformation process. You can create an unlimited number of processors which can be assigned to specific XML elements. Each processor defines how an XML element should be transformed (the XSL equivalent would be xsl:template). Let's take a look at an example:

processor 'contact' => 'ContactProcessor' do |contact|
  str = ''
  str << contact.phone.collect {|phone| "#{phone_location(phone._location)}: #{phone}" }.join( NEWLINE ) if contact.phone
  str << NEWLINE + contact.fax.collect {|fax| "#{fax_location(fax._location)}: #{fax}" }.join( NEWLINE ) if contact.fax
  str << NEWLINE + contact.pager.collect {|pager| "#{keyword(:Pager)}: #{pager}" }.join( NEWLINE ) if contact.pager
  str << NEWLINE + contact.email.collect {|email| "#{keyword(:Email)}: \\url{#{email}}" }.join( NEWLINE ) if contact.email
  str << NEWLINE + contact.url.collect {|url| "#{keyword(:Url)}: \\url{#{url}}" }.join( NEWLINE ) if contact.url
  str << NEWLINE + contact.instantMessage.collect {|im| "#{im_service(im._service)}: #{im}" }.join( NEWLINE ) if contact.instantMessage
  str
end

This defines a processor ContactProcessor which is assigned to the element contact. All the format files shipped with xmlresume2x use a convention for the processor names: <capitalized element name>Processor (useful when overriding a processor with a user defined one). The first parameter is always the element which should be transformed (there is an optional second parameter for passing options). The associated block defines how the contact is transformed.

REXML is used for reading in the XML resume. Two wrapper classes are used to simplify the use of the XML elements: ElementWrapper wraps a single REXML::Element objecct and ElementWrapperList wraps a bunch of them. Using these wrappers, you can do the following:

Access the first phone subelement from contact: contact.phone
Join all phones: contact.phone.join(', ')
Access the attribute location of the first phone subelement: contact.phone._location

So, subelements of an element are accessed by using the name of the subelement as method name. If there is more than one subelement of the same type, you can use the bracket notation to access the others: contact.phone[1]. Attributes of an element are accessed by prepending an underscore to the attribute name and using that as method name.

Keywords

Not all words in the result document are directly taken from the XML resume file. Some words, e.g. headers like Additional Information, are inserted to make reading easier. Naturally, these words are not the same in every language and therefore they have to be defined somewhere.

These keywords are normally defined in the language files. These files are Ruby source files too and contain statements like this:

keyword(
        # general keywords
        :Resume => 'Resume',
        :Of => 'of',
        :AdditionalInformation => 'Additional Information',
       )

The keyword function takes a Hash as argument to define new keywords or overwrite already defined ones. The key has to be a Symbol and the value has to be a String in UTF8 format. Any keyword can be defined this way and later, in a configuration file, used by calling the keyword function with a Symbol as argument.

Manual