dmr Input Format

dmr expects semi-structured input written in reStructuredText. This document explains the structure of a dmr resume document; for technical details, see the dmr.input API docs.

This document will include examples; for a full working example, see http://github.com/stpierre/resume.

class dmr.data.Document(source=None, contact=None, sections=None)

Every dmr resume must start with a top-level title that contains the full name of the person whose resume it is. For example:

============================
 Dennis MacAlistair Ritchie
============================

Immediately after the title there should be an Address Block for the person whose resume it is, followed by any number of other Sections.

That’s it – a top title, an address block, and then other sections. All of the data is held in other sections.

Parameters:

• source (docutils.nodes.document) – The docutils.nodes.document representing the original doctree.
• contact (dmr.data.Contact) – The contact for the resume (i.e., the person whose resume it is).
• sections (list of dmr.data.Section subclass objects) – A list of sections in the document.

Address Block

class dmr.data.Contact

An address block is a line block giving the contact information for a resume, an employer, a reference, or similar. It consists of six different types of lines:

• The name is freeform and must come on the first line, if it is needed at all. See below for when a name is required and when it’s not.
• Any number of phone numbers may be provided; they must come after the name, but there is no other ordering requirement. A phone number is any line that consists of dashes, parentheses, plus signs, whitespace, and digits, preceeded by an optional identifier. E.g., (555) 555-5555, cell: (02) 1234 5678, and +44 01 56 60 56 60 are all valid phone numbers. Additionally, any line containing a docutils reference that uses the tel: protocol will be considered a phone number.
• Any number of email addresses, which also must come after the name. Any line containing something that is automatically recognized by docutils as a reference and whose URI starts with mailto: is considered an email address. (Note that it’s usually unnecessary to specify mailto: explicitly; docutils is pretty smart about finding email addresses. If you’re still using that old bangpath address, though, you might need to.)
• Any number of URLs, which also must come after the name. Any line containing something thing that is automatically recognized by docutils as a reference and which uses neither the mailto: nor the tel: protocol will be considered a URL.
• The first contiguous set of lines that are not any of the above types will be considered the physical address.
• All lines that are not any of the above types wil be considered other data. Other data must come after the physical address, and the physical address must be separated from the other data by a phone number, URL, or email address. See the examples below.

If the address block describes a reference, then the first line must be that person’s name. Otherwise, the name will be taken from the title of the section the address block is in, and must not be included in the address block itself. (See below for examples to clarify this.)

Outside of the few ordering requirements listed, order is neither required nor respected; the order of address elements in the output document is specified by the output format class. The canonical output order is: name, address, phone, email, url, other. No output format is required to honor that.

Examples

So the start of a resume might look like:

============================
 Dennis MacAlistair Ritchie
============================

| 1234 No. Such Ln.
| Berkeley Heights, NJ 07922
| (908) 555-5555
| dmr@lucent.com

Whereas a personal reference might look like:

References
==========

| Dennis MacAlistair Ritchie
| 1234 No. Such Ln.
| Berkeley Heights, NJ 07922
| (908) 555-5555
| dmr@lucent.com

Note the different ways the name is specified.

Physical address matching is greedy, so if you have several unrecognizable lines in a row, they will all become the physical address. Consider this example:

============================
 Dennis MacAlistair Ritchie
============================

| 1234 No. Such Ln.
| Berkeley Heights, NJ 07922
| "I invented C."
| (908) 555-5555
| dmr@lucent.com

In this case, the physical address would have three lines – “1234 No. Such Ln.”, ‘Berkeley Heights, NJ 07922”, and “‘I invented C.’” In order to treat the final line as “other data” instead of as the physical address, it must be separated from the physical address by another data type. E.g.:

============================
 Dennis MacAlistair Ritchie
============================

| 1234 No. Such Ln.
| Berkeley Heights, NJ 07922
| (908) 555-5555
| dmr@lucent.com
| "I invented C."

Sections

The resume will be divided into any number of sections, which hold the real data. There are four different types of sections, most of which are very simple:

Text

class dmr.data.Text(name)

A Text section contains only freeform text – an objective, for instance. This is the simplest section.

A section header with no content (e.g., “References Available Upon Request”) will be treated as a Text section.

Examples

Objective
=========

To obtain a rewarding, high-level position inventing C.

References Available Upon Request
=================================

Parameters:name (docutils.nodes.Text) – The name (title) of the section

List

class dmr.data.List(name)

A List section contains only a bulleted list – for example, a list of publications, or related experience.

Examples

Other Qualifications
====================

* Invented C.
* No seriously.
* Invented a lot of UNIX, too.

Parameters:name (docutils.nodes.Text) – The name (title) of the section

References

class dmr.data.References(name)

A References section contains only a series of Address Blocks.

Examples

References
==========

| Dennis MacAlistair Ritchie
| 1234 No. Such Ln.
| Berkeley Heights, NJ 07922
| (908) 555-5555
| dmr@lucent.com

Parameters:name (docutils.nodes.Text) – The name (title) of the section

Experience

class dmr.data.Experience(name)

The Experience section is by far the most complex section. It is useful for job experience, education history, and anything that consists of multiple discrete items with dates and descriptions. It may take one of two formats:

With Positions

For most job experience sections, you’ll want to use the format that allows you to specify both employers and positions. In this case, the Experience section must consist only of any number of subsections, each of which describes an employer. Each employer section must itself contain:

• An Address Block (optional), giving the employer’s contact information; and
• Any number of subsections, each of which describes a position held at that employer.

Note

This makes it simple and efficient to specify multiple jobs you held at a single employer.

Each position subsection is a Job Section.

See the examples below.

Without Positions

In this format, you only specify employers, not positions. This is useful for education sections, where you often wish to list the school, but a “position” as such is nonsensical. (Of course, more complex education sections will likely wish to use the format with positions in order to present more data.)

The positionless format is simply the format with positions with one level of subsection removed. The Experience section must consist only of any number of subsections, each of which is a Job Section.

See the examples below.

Examples

This is an example of an Experience section with positions:

Experience
==========

Bell Labs
---------
| 600 Mountain Ave.
| New Providence, NJ 07974

Scientist
~~~~~~~~~
1967 - 1975

* Invented C.
* Invented C while inventing UNIX.
* Wrote *The C Programming Language*.

Research Fellow
~~~~~~~~~~~~~~~
1975 - 1996

* Developed ANSI C (C89).
* Won the Turing Award and the Hamming Medal.

Lucent Technologies
-------------------

Chair, System Software Research Department
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1996 - 2007

* Got about a zillion more awards for being the guy who
  invented C.

This is an example of an Experience section without positions:

Education
=========

Harvard University
------------------
1959 - 1963

* B.S., Physics
* B.A., Applied Mathematics

Harvard University
------------------
1963 - 1967

* PhD, Applied Mathematics
* Dissertation: "Program Structure and Computational
  Complexity"

Parameters:name (docutils.nodes.Text) – The name (title) of the section

Job Section

class dmr.data.Job(employer=None, position=None, dates=None, start=None, end='Present', description=None)

Representation of an element in a Experience section. We call it a “Job,” but it could be schooling or anything else with dates and a bullet list description. It contains:

• An Address Block (optional), giving the employer’s contact information; and
• A Date Range (optional), giving the dates in the position; and
• A bulleted list of your duties at that employer.

Parameters:

• employer (dmr.data.Contact) – The employer (or school, etc.)
• position (str) – The position at said employer. This is completely optional, for instance for education history.
• dates (dmr.data.Dates) – The date range for the given job. Either provide dates or start and end, but not both.
• start (str) – The start of the date range for the given job. Either provide dates or start and end, but not both.
• end (str) – The end of the date range for the given job. Either provide dates or start and end, but not both.
• description (list of strings) – The itemized description of the position.

Date Range

class dmr.data.Dates

A date range is a one-line paragraph giving a range of dates. The dates themselves are not parsed; only the start and end of the range are determined. The start and end may be separated:

• By the word ‘to’ surrounded by whitespace;
• By a hyphen surrounded by whitespace;
• By a hyphen with optional whitespace around it, if neither date contains a hyphen.

In other words, the following are all valid:

1 February 2013 to 27 February 2013
2-1-2013 to 2-27-2013
2013-1-2 - 2013-27-2
1 Feb 2013-27 Feb 2013
1999-2004
Marceau, Nonidi 9 Ventôse an 221 - Présent

The following are invalid:

2013-1-2-2013-27-2
1 février 2013 à 27 février 2013

The latter invalid example is a localization problem, which someone should probably solve some day. However, it should be noted that the actual display of the separator between the dates is left to the output format; the separator used in the source file is not preserved. (I.e., non-English-language resumes can use the hyphen as a separator, and the appropriate word or separator in the output formatter.)

Exclusions

Sections, jobs, and job positions – basically, anything under a reST section heading – can be excluded or included for different formats. This lets you write a full “long form” resume that might take several pages for presentation on a website, and publish a shorter, two-page PDF resume with selected content only.

The simplest way to specify sections to exclude is by title. For instance, consider a resume with both of the following sections:

References Available Upon Request
=================================

References
==========

| Someone Reliable
| 123 Not a Fake St.
| Real City, XX 54321

You could generate your resume with either of the following:

dmr --exclude=References
dmr --exclude="References Available Upon Request"

You can exclude multiple sections by giving multiple --exclude options.

That could be tedious, though, especially if you have many sections you want to exclude or include. In that case, you can add different sections to named section groups. E.g.:

References Available Upon Request
=================================

.. group short-form

References
==========

.. group long-form

| Someone Reliable
| 123 Not a Fake St.
| Real City, XX 54321

Now you can run:

dmr --exclude=long-form
dmr --exclude=short-form

To take it one step further, you can ensure that your PDF resume is always the short form by default, and otherwise your resume is always the long form by default by using in-document configuration. To do so, you’d add the following to the top of the document:

.. options
   exclude short-form
.. options=latex
   exclude long-form
   include short-form

Note that includes always take precendence over excludes, no matter where they’re specified. So if you have an include in /etc/dmr.conf, that section cannot be excluded. This isn’t a significant drawback in practice, because all sections are included by default, so there’s very little reason to explicitly include a section in /etc/dmr.conf.

See Global configuration options for details on the syntax of specifying exclude and include lists.