initial release

.gitignore

@@ -0,0 +1,2 @@
+*.bak
+*.log

README.md

@@ -1 +1,73 @@
-# RemoteBallotMarking
+# Remote Ballot Marking
+
+This repository contains the Hilton Roscoe Remote Ballot Marker (RBM). The RBM provides core remote ballot marking functionality, such as:
+
+- Support for N-of-M and RCV voting methods
+- Ballot definition using EML 410
+- Overvote protection
+- Undervote warnings (prior to save, print, etc.)
+- Ballot transcription (barcode) support with custom encodings and symbologies
+- Signed code and data with inspectable signatures
+
+Roadmap items:
+
+- Control of barcode symbology at data level
+
+## The RBM is a PDF
+
+The RBM is a packaged as a self contained PDF. Use of PDF accomplishes two key goals:
+
+- Enables a fully offline ballot marking experience
+- Provides support for multiple workflows
+  - Fill and print
+  - Print and fill (by hand)
+
+## Trying it out
+
+The easiest way to try out the Remote Ballot Marker is to open one of the sample PDFs, located under `pdf/`.
+
+## Getting Started
+
+- [Technical Background](./docs/INTERNALS.md)
+- [Non-technical Background](./docs/INTERACTION.md)
+- [Tasks for Election Officials](./docs/TASKS.md)
+
+## Ballot Styles
+
+Ballot Styles are defined using `EML 410`. Please read that documentation for creating and loading ballot styles.
+
+## Source Code
+
+The source code for the RBM is provided as a series of `xdp` files. Each file represents a portion of the `XFA-template`.
+
+## Generating PDFs from Source
+
+PDFs can be generated by stitching the XDPs together such that they form a single `xdp` fragment. This can be accomplished using commercial tools or the `XfaBuilder`.
+
+- [Packaging PDFs](./docs/PACKAGING.md)
+
+## Limitations
+
+The RBM is not designed to be a complete, turn key solution. The following features are considered out of scope:
+
+- Voter Authentication
+- Ballot Retrieval
+- Ballot Return
+
+> RBM should be considered a prototype. It is *not* intended to be used as-is.
+
+## Additional Info
+
+- [Platform](./docs/PLATFORM.md)
+  - PDF Readers
+  - Boilerplate
+  - AcroForms support
+  - [RBM Internals](./docs/INTERNALS.md)
+- Ballot Definition
+  - [Common Tasks](./docs/TASKS.md)
+  - [Localization and Customization](./doc/LOCALIZATION.md)
+  - [EML Extensions](./docs/EML-410_extensions.md)
+  - Barcode Support
+  - RCV Support
+- [PDF and Data Signatures](./docs/SIGNATURES.md)
+- [Packaging PDFs](./docs/packaging.md)

docs/ACROBAT.md

@@ -0,0 +1,25 @@
+# Tasks with Acrobat
+
+<!-- TOC -->
+
+- [Tasks with Acrobat](#tasks-with-acrobat)
+    - [Applying Certifying Signatures](#applying-certifying-signatures)
+    - [Loading Data](#loading-data)
+        - [Approach 1](#approach-1)
+
+<!-- /TOC -->
+
+## Applying Certifying Signatures
+
+## Loading Data
+
+> `RBM` does not consume EML 410 directly. Instead, the EML 410 payload must be wrapped by an RBM instance.  See [Data Formats](./DATA_FORMATS.md) for additional information.
+
+### Approach 1
+
+(requires Acrobat Standard or Pro)
+
+1. Click on Tools
+2. Click on Forms -> More Form Options
+3. Select Import Data
+4. You'll select a valid RBM file. Use files located at [xml](../xml) for examples. The PDF will bind to the fields of the form.

docs/BALLOT_DATA.md

@@ -0,0 +1,130 @@
+# Ballot Data
+
+This section describes that parts of EML 410 that are supported by RBM.
+
+<!-- TOC -->
+
+- [Ballot Data](#ballot-data)
+    - [Ballot](#ballot)
+    - [Contests](#contests)
+        - [Headers](#headers)
+            - [Default Contest Header](#default-contest-header)
+            - [Ballot Measure Contest Header](#ballot-measure-contest-header)
+            - [Instruction Contest Header](#instruction-contest-header)
+        - [Representing Candidate Contests](#representing-candidate-contests)
+            - [Write-In Contest Options](#write-in-contest-options)
+        - [Representing Ballot Measure Contests](#representing-ballot-measure-contests)
+    - [Voting Methods](#voting-methods)
+    - [Order and Rotation](#order-and-rotation)
+    - [Considerations for Selections Ballot Record](#considerations-for-selections-ballot-record)
+
+<!-- /TOC -->
+
+> This section uses [XPath](https://www.w3.org/TR/xpath-31/) conventions to make reference to various data points used in the ballot dataset.
+
+Generating ballot data is a prerequisite to generating ballot styles. Ballot data can be packaged using one or more EML 410 packets. The EML 410 packet format was developed as part of the [1622-2011 - IEEE Standard for Electronic Distribution of Blank Ballots for Voting Systems](https://ieeexplore.ieee.org/document/6130556). Examples of ballot data are available under `/xml/`.
+
+The following sections describe various parts of the ballot, and what data is required to define them.
+
+## Ballot
+
+> The RBM is initially bound to `/EML/Ballots/Ballot[0]` node of the dataset. If more than one `Ballot` is defined, only the first one will be rendered.
+
+The only item bound to the RBM that is general to the ballot is the `Precinct {Name}`, which is bound to `BallotIdentifier/BallotName`.
+
+## Contests
+
+The following items are bound to the RBM:
+
+- `ContestIdentifier/@IdNumber`
+- `ContestIdentifier/ContestName`
+- `HowToVote/Message[1]`
+- `MaxVotes`
+- `Messages[1]/Message[1]`
+- `BallotChoices` (partially, see below)
+
+### Headers
+
+All contests have a header. RBM provides three header section templates:
+
+- Default Contest Header
+- Ballot Measure Contest Header
+- Instruction Contest Header
+
+#### Default Contest Header
+
+The default contest header is used when no other header applies. It consists of:
+
+```header
+{RaceName}
+Vote for not more than {MaxSelections}
+```
+
+With `{RaceName}` bound to `ContestIdentifier/ContestName` and `{MaxSelections}` bound to `MaxVotes`
+
+> The text appearing in contest headers can be customized. See [Localization](./LOCALIZATION.md).
+
+The default template also includes an *undervote helper*. For details on its functionality, see [Undervote Helper](./INTERACTION#undervote-helper).
+
+#### Ballot Measure Contest Header
+
+The ballot measure contest header is used for all ballot measures. It consists of:
+
+```header
+{RaceName}
+{Instructions}
+{QuestionBody}
+```
+
+With `{RaceName}` bound to `ContestIdentifier/ContestName`, `{Instructions}` bound to `HowToVote/Message[1]`, and `{QuestionBody}` bound to `Messages/Message[@Type = MeasureText][1]`
+
+#### Instruction Contest Header
+
+Finally, the instruction contest header is used for any non ballot measure that wishes to provide custom instruction text. It consists of:
+
+```header
+{RaceName}
+{Instructions}
+```
+
+With `{RaceName}` bound to `ContestIdentifier/ContestName` and `{Instructions}` bound to `HowToVote/Message[1]`.
+
+### Representing Candidate Contests
+
+Candidate contest options are represented under `BallotChoices`.
+
+The following items are bound to the RBM:
+
+- `AffiliationIdentifier/RegisteredName`
+- `CandidateIdentifier/IdNumber`
+- `CandidateFullName/NameElement[1]`
+- `WriteInCandidate` (see below)
+
+> The default template will display the party name (`RegisteredName`) under the candidate's name, if provided.
+
+#### Write-In Contest Options
+
+A write-in contest option is generated once per emission of the `WriteInCandidate` element.
+
+> `MaxWriteIn` is not used by the RBM to determine the number of write-ins to generate. However, an upstream system can use that element to determine how many `WriteInCandidate` elements to generate.
+
+### Representing Ballot Measure Contests
+
+Ballot measures consist of the ballot measure text (addressed under [Ballot Measure Contest Header](#ballot-measure-contest-header)), and a number of contest options to allow a response to be recorded.
+
+The following items are bound to the RBM:
+
+- `ProposalItem/ReferendumOptionIdentifier`
+- `ProposalItem/SelectionText`
+
+## Voting Methods
+
+RBM supports two voting methods, `n-of-m` and Rank Choice Voting (`RCV`). The EML 410 schema refers to these two methods as `FPP` and `IRV`, respectively. A `VotingMethod` **must be** specified for every `Contest`.
+
+## Order and Rotation
+
+EML 410 provides a number of attributes and elements to store ordering data. However, the Remote Ballot Marker (RBM) *always* renders the ballot following reading order (i.e. the order elements appear in the file). Use of structures like `DisplayOrder` or `Rotation` are not prohibited - however, it is expected that a upstream system will use these attributes to transform the EML 410 instance into the proper reading order.
+
+## Considerations for Selections Ballot Record
+
+The Selections Ballot Record (SBR) consists of only the selections made by the voter. Each contest is tracked using the `ContestIdentifier/IdNumber`. Likewise, it uses the `CandidateIdentifier/IdNumber` for candidate contests, `ProposalItem/ReferendumOptionIdentifier` for ballot measure contests, and `WriteInIdentifier/IdNumber` for write-ins. The default encoding of the transcription barcode is based on a condensed version of the SBR. Thus, it is important that these codes are unique within a `Ballot`.

docs/BARCODES.md

@@ -0,0 +1 @@
+Placeholder

docs/DATA_FORMATS.md

@@ -0,0 +1,39 @@
+# Data Formats
+
+This section describes the data formats used by the Remote Ballot Marker (`RBM`).
+
+<!-- TOC -->
+
+- [Data Formats](#data-formats)
+    - [RBM Format](#rbm-format)
+    - [EML 410](#eml-410)
+    - [Selections Ballot Record Format](#selections-ballot-record-format)
+
+<!-- /TOC -->
+
+## RBM Format
+
+The RBM Format is a container format, encapsulating the following:
+
+- EML 410 instance for a single ballot
+- Selections Ballot Record (`SBR`)
+
+> The `SBR` is not provided by the election jurisdiction, instead it is generated by the `RBM` during the ballot marking process.
+
+For more information on the RBM format, see the `xsd/hr-rbm.xsd`.
+
+## EML 410
+
+An [extended version](./EML-410_extensions.md) of EML 410 is the primary format used by the RBM.
+
+> RBM supports vanilla EML 410. However, to take advantage of advanced rendering features, extensions must be used.
+
+## Selections Ballot Record Format
+
+The Selections Ballot Record (`SBR`) is a highly simplified format containing only the codes necessary to correlate them to indications on a ballot.
+
+The structure of this format is given below:
+
+![Image of Selection Ballot Record Format](./images/selections.png)
+
+> `RBM` currently generates a `Selection` for every potential effective indication on the ballot, even if there is no indication present. Refer to the `Selected` element to determine if the selection is indicated.

docs/EML-410_extensions.md

@@ -0,0 +1,64 @@
+# Extensions to EML 410
+
+<!-- TOC -->
+
+- [Extensions to EML 410](#extensions-to-eml-410)
+    - [Write-In Support](#write-in-support)
+    - [Styling Support](#styling-support)
+    - [Column / Page Breaking](#column--page-breaking)
+    - [Leaders and Trailers](#leaders-and-trailers)
+
+<!-- /TOC -->
+
+This document describes extensions to EML 410 to support the RBM tool.
+
+## Write-In Support
+
+A Write-In contest option will emitted for each occurrence of `WriteInCandidate` under
+`BallotChoices`.
+
+```xml
+<BallotChoices>
+    ...
+    <WriteInCandidate>
+        <Name/>
+    </WriteInCandidate>
+</BallotChoices>
+```
+
+## Styling Support
+
+If desired, certain content may override the default style sheet of the form. This "Rich Text" functionality is accomplished by emitting a `XHTML` fragment, with CSS instructions as required. The XHTML fragments comply with the XFA 3.3 "Rich Text Reference" and support all of the features described therein. Rich Text is permitted in the following locations (all under `Contest`):
+
+- BallotChoices/Candidate/CandidateFullName/NameElement
+- ContestIdentifier/ContestName
+- Messages/Message
+
+## Column / Page Breaking
+
+Column and page breaking can be restricted such that parts or all of a contest must appear on a single column or page. These directives appear under a `Contest` or `MeasureText`, and are of the form:
+
+```xml
+<KeepIntact Target="{subform}">{scope}</KeepIntact>
+```
+
+Where `{subform}` is the target of the keep intact directive, and `{scope}` is one of the following:
+
+|Option     |Description           |
+|-----------|----------------------|
+|none       |No directive          |
+|contentArea|May not break a column|
+|pageArea   |May not break a page  |
+
+## Leaders and Trailers
+
+If a column or page break is unavoidable, a subform can appear right before the break (the `trailer`), and right after the break (the `leader`) to indicate to the voter to refer to the next or previous page. These directives appear under a `Contest`, and are of the form:
+
+```xml
+<OverflowLeader Target="{subform}">{leader}</OverflowLeader>
+<OverflowTrailer Target="{subform}">{trailer}</OverflowTrailer>
+```
+
+Where `{subform}` is the target subform whose overflow causes the leader/trailer to appear, and `{leader}`, and `{trailer}` point to subforms containing the leader and trailer content.
+
+> It is not required to specify both a `leader` and a `trailer`

docs/GLOSSARY.md

@@ -0,0 +1,17 @@
+# Glossary of Terms
+
+## Ballot Data
+
+A list of contests and associated options that may appear on a ballot for a particular election.
+
+## Ballot Style
+
+Ballot data that has been put into contest order for a particular precinct and considers a particular set of voter situations. Voter situations include party affiliation (for closed primaries), and age of the voter (in states that permit 17-year-olds to vote in primary elections), among others.
+
+## Host Template
+
+The root form.
+
+# Orphan Paragraph
+
+Paragraph left from previous content area.