Content-type: text/html Man page of SEDE


Section: User Commands (1)
Updated: Jun 2007
Index Return to Main Contents


sede - secure democracy  


sede [--help|--version|--version-short] [COMMAND [PARAMETER[S]]]  


Sede is an anonymous voter verified voting program, a toolbox to write polls and process them into results.

Sede is primarily a program for `vote administrators', but is also useful for voters to verify the integrity of the results. This program does not rely on trust on the part of voters, voters are presented extensive data to verify and (automatically) re-count. It offers voters a free vote (voters can but do not need to choose one of a limited set of options) and free comment space, providing power to voters and measuring their opinion with more accuracy. Voters can also organize their own votes from within the comment-space, as long as the vote-administration does not alter its content.

Method: Each vote contains three elements: a vote-code, a vote-field, and a comment-field. The vote-code is a string of numbers and letters. The vote-field is where the voter places his/her option of choice. The comment-field is where the voter can place a comment.

Vote-code: If a returned ballot contains a vote with a to the vote-code-database corresponding vote-code in it, this vote will be marked as being a valid vote; as opposed to sending back a vote with a fantasy vote-code, which will be marked as an invalid vote.

Vote: The vote is a field in the ballot, where voters can write their vote, like in a form. The vote can be one of suggested options, or it can be creative input from the voter. All valid votes will be counted, whether they conform to suggested options or not.

Comment: This is a second field belonging to a vote, but its content will not be counted with other comments. The voters can use this space to make their vote even more unique and recognizable for themselves. The voters can also use the comment space to communicate whatever they wish to communicate.

The votes, containing these three elements, will have their vote-fields added together. The count and the votes themselves will be made public, a website is generated for this purpose. If voters remember their vote-code, they can use it to check that their vote was correctly processed. Voters can re-add the published votes again, to check this was correctly done. Besides these lists, more lists and more types of additions are being published, to give voters an as complete as possible overview of what has taken place.

User interface: Sede is a program which operates on data stored in several directories. These operations are named commands, which can be given as an argument to the sede shell wrapper in ${PATH}, or be accessed interactively from a specialized prompt (run sede without arguments). Voters do not need to install or use this program.

Ballots can be encrypted, configurable on a per voter basis, using generally available command line programs.  

Table Of Contents

* Table Of Contents
* COMMANDS (simple arguments)
* COMMANDS in alphabetic order
* USER CONFIG FILE ~/.sederc



Sede gives each registered person a random vote-code per "poll/referendum", then sends (emails) each voter their ballot containing this (these) vote-code(s). After receiving the returned and filled-out ballots, processes them into result lists, which can then be published. In these published results each individual vote with their vote-code is present for verification by the voters, as are any attacks.

Voters do not have to install any special software to be able to vote (just an email client). Sede is a program for the administrators of the voting process, and can optionally be used by voters.

The way the persons are decided to be registered is left undefined, registrations minimally require a routing channel for the ballot. If registrations are taken in an anonymous way, the vote becomes anonymous to the vote administration as well.

Typical usage
> sede pollsconf c_template
> sede pollsconf c_pnames

  (edit a new ballot)
> sede makes

  (create ballots)
> sede sendallmail

  (mail all ballots to voters)
> sede processall

  (process all returned ballots)

  Results can then be published. 

The routing channel of the ballots does not need to be (all) email, it is possible to use sede as a back-end and handle voter-interfacing (on a per voter basis) differently.

New users are encouraged to start with one of the pre-configured example polls (_essence or _basic are a good start), and change the setup to their needs. There are a lot of things that can be configured, starting with a working setup will only make things easier. The one file to change for sure is: ${SEDE_ROOT_IN}/c_voters, the voters registration.

The program basically works like this: 4 data directories and 1 storage directory for inactive polls. A poll always starts in directory ${SEDE_ROOT_IN}/ (_IN as in "INput"), all the other data directories are empty at this point. Configuration files (names start with c_), master ballot, voter registration, it is all there, in ${SEDE_ROOT_IN}/.

Once this has been setup (voters are registered, master ballot is written, configuration is as desired), the second directory ${SEDE_ROOT_OUT}/ (_OUT as in "OUTput") can be filled (run `makes`) with actual ballots, the vote-code databases etc. This becomes an actual implementation of the poll configured in ${SEDE_ROOT_IN}/. By removing all this machine created data in ${SEDE_ROOT_OUT}/, and re-running the ballot creation command (`makes`), a new instance of the poll is created in ${SEDE_ROOT_OUT}/, with different vote-codes, but otherwise equal to the first. You might need to do this a couple of times (with a truncated voter registration file ${SEDE_ROOT_IN}/c_voters perhaps), if you have made programming errors in ${SEDE_ROOT_IN}/. Stepping modes for ballot creation are available, to help you track down bugs. A simple ballot can hardly contain bugs though.

Now the ballots can be routed toward voters (run `sendallmail`). Once voters have returned their ballots, these returns must be stored in the third data directory ${SEDE_ROOT_VIN}/ ("Voters INput"). It does not matter in what files they are stored, as long as it is in this directory. After this, on the basis of configuration in ${SEDE_ROOT_IN}/, the results can be processed by running `processall`: adding votes, weeding out false votes, etc. The results of this processing - you guessed it - are automatically put in the last data directory ${SEDE_ROOT_VOUT}/ ("Voters OUTput"). Again, by re-running the command `processall`, the generated data in ${SEDE_ROOT_VOUT}/ is simply re-created on the basis of data in ${SEDE_ROOT_IN}/ (configuration) and ${SEDE_ROOT_OUT}/ (databases) and ${SEDE_ROOT_VIN} (voter input).

In order to prevent unpleasant mistakes this far in the voting process, it is probably a good idea to test-run the returned ballots processing. For this, don't send ballots to voters, but simply copy them into ${SEDE_ROOT_VIN}/ (see `cps`). The program doesn't know this, it assumes the returns are from voters (actually, it has no opinion about this one way or the other). You may wish to edit some ballots in ${SEDE_ROOT_VIN}/ to make it more interesting. Then run `processall', and open up ${SEDE_ROOT_VOUT}/ in a web browser. You can also do this an infinite amount of times, until all issues, if any, are resolved.

${SEDE_ROOT_VINREAD}/ is a directory for a special need: while votes are being processed into result lists for publishing, if so configured, ${SEDE_ROOT_VINREAD}/ can be made to contain all the returned data in ${SEDE_ROOT_VIN}/, except the votes. This may be useful to inspect "the voter input remainder", without having to see the votes. Can also be useful to more easily find (grep) garbled votes that were rejected.

The vote is a section of "magic text" inside the text ballot. You can configure this "magic" (see ${SEDE_ROOT_IN}/c_findvote, ${SEDE_ROOT_IN}/c_findcode and ${SEDE_ROOT_IN}/c_find_votearea). The ballot can contain any number of such vote-areas. Each question on the ballot typically has a unique name, defined in ${SEDE_ROOT_IN}/c_pnames. The master ballot consists of text, into which the "magic text" areas are written, but which does (obviously) not contain any specific vote-codes, because these are different for each voter. In the master-ballot, a number of variables can be expanded (see the master ballot: ${SEDE_ROOT_IN}/c_template). One such variable will expand into the vote-code for any specific voter.

Sede has a lot of features. Among which are email attachment encryption (see the sede_divide_run flag for encryption, and rundir for decryption). The ballots are created from the master/source ballot, by expanding variables on it. After one time expanding variables, it can do it again and again. If-Then-Else on voter data is possible (see ^-ifelse), as is command expansion (see ^-execute), file inclusion (see ^-file) and other things. To avoid clashing with `$', used by many shell languages, the otherwise little used `^' character initiates active text in the master ballot (`^^' is literal `^'). Short (`^?') and long (`^-...') versions of variables are present (`^-' is the short variable which initiates a long variable name, to be precise).


COMMANDS (simple arguments)

Print usage.
Print version.
Print version in short format


COMMANDS in alphabetic order:

addmore [sendmail [EXTENSION]]
Addmore adds several new voters to a running poll. If you have added more then one voter to the end (!) of the voters registration file (${SEDE_ROOT_IN}/c_voters), addmore computes how many ballots are missing from the currently running poll, and makes ballots and flag-files (etc) for the new voters. With sendmail these new ballots are send over email after creation, with EXTENSION only the ballots that match EXTENSION are send (extension must be given including a dot, if applicable).

As an exception, addmore uses a file in the input directory: ${SEDE_ROOT_IN}/c_voters.addmore_save, to save the original (and final) ${SEDE_ROOT_IN}/c_voters temporarily.

See also sendlastmail and addvoter.

Adds similar votes, needs extracted voting-areas and ${SEDE_ROOT_IN}/c_findvote, creates all ${SEDE_ROOT_VOUT}/resultN files (where N is the poll number as defined by ${SEDE_ROOT_IN}/c_pnames line number). If ${SEDE_ROOT_IN}/c_pervoter's (see elsewhere) is configured for it, also computes frequencies for voting patterns over all polls in ${SEDE_ROOT_VOUT}/votingpatterns.
addvote_compact [givename]
Compacts raw vote results, so that voters who meant the same thing can be grouped under one result name (see `${SEDE_ROOT_IN}/c_compact'). Needs raw results as created by addvote. Works both before and after `givename' has been run, this program can be run on already generated (and published) results, after the `${SEDE_ROOT_IN}/c_compact' file has been tweaked/corrected in case of sub-optimal or erroneous content. This will only change the unformatted compact-result files, not their HTML formatted counterparts as created and pointed to by `givename'. Creates ${SEDE_ROOT_VOUT}/compactN and ${SEDE_ROOT_VOUT}/weighted_compactN (${SEDE_ROOT_VOUT}/o/POLLNAME-${SEDE_INDEX_COMPACT} and ${SEDE_ROOT_VOUT}/o/POLLNAME-${SEDE_INDEX_WEIGHTED_COMPACT).

With argument `givename' runs `givename cutname' on previously givename formatted results, and `givename' on raw results, after applying the changes. This brings HTML formatted result files back in sync. Running `addvote_compact' without argument makes it possible to first inspect the changed result-files, before putting the changes under the primary HTML links in the results.

See `${SEDE_ROOT_IN}/c_compact' for more details.

Adds votes taking their weight into account, needs addvote to be run before it. Creates ${SEDE_ROOT_VOUT}/weighted_resultN.
addvoter [ fake | faken N
] | [ unlock | lock ] | [ test ] step[:BALLOT:PASS:LINE:CHARACTER] | ballotstep[:B:P:L:C] | passstep[:B:P:L:C] | linestep[:B:P:L:C] | unitstep[:B:P:L:C] | echolinestep[:B:P:L:C] | echounitstep[:B:P:L:C] | jumpstep[:B:P:L:C] ]

Usage is almost the same as for makes (see above), but instead of making a new batch of ballots/records etc, it adds a ballot and records (etc) for one additional voter, whose registration has been appended to ${SEDE_ROOT_IN}/c_voters. If zero generated ballots are found, makes is called regardless of the number of voters in the voter registration file. When makes is called, the arguments test and one of the *step arguments are passed on to makes.

The argument fake generates a "wild" ballot under ${SEDE_ROOT_TMP}/fake.ballot. This ballot is created with as voter registration data `fake,field-2,field-3,field-4,...,field-50'. Creating it doesn't affect any other files (except those in ${SEDE_ROOT_TMP}). The argument faken N creates a "wild" ballot for voter number N (the voter registered on line N of ${SEDE_ROOT_IN}/c_voters), the votercodes are purely random and useless, but the ballot should look similar (unless you were doing an if-then-else on vote codes :-) ). This ballot gets stored under ${SEDE_ROOT_TMP}/fake.ballot_N. N has to follow immediately on the faken argument.

See also sendlastmail and addmore.

saves the data from all directories (except ${SEDE_ROOT_POLLS}), needs ${SEDE_ROOT_IN}/c_name for the basename of the archive, stores the archive under ${SEDE_ROOT_POLLS}.

Shortcut: `a'.

Generates in ${SEDE_ROOT_OUT} ballots (out_SERIAL_NUMBER_ballot*), secret_master_POLL_NUMBER and codespervoter records.

VOTECODELENGTH is the length of the vote code to be used, default 10.
PASSES is the number of passes it runs over the ${SEDE_ROOT_IN}/c_template, default 1.
CODE_UNIQUENESS signals vote code uniqueness (bitmask):
`0' per poll case sensitive unique
`1' all vote codes case insensitive unique
`2' per poll case sensitive unique,
`3' is all vote codes case insensitive unique.
STEPPING defines stepping:
`0' is no stepping,
`1' is per ballot stepping,
`2' is per pass stepping,
`3' is per line stepping,
`4' is per character stepping,
`5' is per line stepping with echo-mode on,
`6' is per character stepping with echo-mode on,
`7' is per character stepping with echo-mode on and jumping to the first occurence of `^'.
`:BALLOT:PASS:LINE:CHARACTER' is start stepping as if `^-step' had been encountered on the given coordinates (ballot BALLOT, pass PASS, line LINE, and character CHARACTER). CHARACTER value `0' is magic and stands for the end of line.
TEMPLATE_FILE is the template ballot file used, default ${SEDE_ROOT_IN}/c_template.
VOTERS_FILE is the voters registration file used, default ${SEDE_ROOT_IN}/c_voters.
SERIALSTART makes sede start from another serial number for the first ballot other then default 1.
CODEMODE defines how the template ballot code in ${SEDE_ROOT_IN}/c_template is treated during the first pass:
`0' means: all plain text outside variables is copied into the next pass and/or the end ballot.
`1' means: all plain text outside variables is ignored during the first pass (so you can indent and comment your template ballot code).
PASSWD_LENGTH defines the length of the password, default 9.

ballots ignores all ${SEDE_ROOT_IN}/c_* configuration files. This command is called in appropriate ways by the makes command, normally you should never need to operate it. See below at RETURN VALUES for the return values of the ballots command.

Checks code-uniqueness in ${SEDE_ROOT_OUT}/secret_master_M, looks at ${SEDE_ROOT_IN}/c_uniqcodes to determine if it should be question-specific or general, it gives a verbal indication, and leaves an indication file in ${SEDE_ROOT_TMP} if codes are not unique.
Finds and removes excess voting-areas which occur more then once, needs ${SEDE_ROOT_VOUT}/.voted_codesM (which is created by getvotes), needs ${SEDE_ROOT_IN}/c_findcode, creates ${SEDE_ROOT_VOUT}/doublevotesM. (See also `sede correlate' about vote precedence.)
Puts a default ~/.sederc file in the users ${HOME} dir, and creates default directories (under ~/.sede/), with example polls in it. Also sets ${SEDE_SEDERC_VERSION} to `sede --version-short'.
continue [y|n|a]
Low level continue/confirm command, reacts to ${SEDE_HALT} (defined in ~/.sederc). Returns 0 when argument is a, when user input does not match `n' or `N' when argument is y, and when user input matches `y' or `Y' when argument is n. Returns 1 when user input matches `n' or `N' when argument is y, and when user input does not match `y' or `Y' when argument is n. When the argument is n, the user is presented with `Continue [y/N]', when the argument is y, the user is presented with `Continue [Y/n]', when the argument is a, the user is presented with `Continue ...'.
Correlates votes from a voter with eachother: makes a long list where each voters votes appear next to eachother ${SEDE_ROOT_VOUT}/pervoter, and creates small files under ${SEDE_ROOT_VOUT}/POLL-NAME-${SEDE_INDEX_BROWSE}/VOTECODE, containing all votes of a voter. Needs ${SEDE_ROOT_VOUT}/votesN files generated by getvote(s). This program will mark votes for the same vote-code, that it encounters later in the collected votes as "ignored votes". Any sorting regarding precedence needs to be done prior to running correlate.
Move created ballots in ${SEDE_ROOT_OUT}, into the returns directory ${SEDE_ROOT_VIN}, skipping the voters and ballot-sending.
Reverses filename changes made by givename, restores them to their originals.
Does final "nicing-up" of resulting files in ${SEDE_ROOT_VOUT}: remove some key characters from ${SEDE_ROOT_VOUT}/pervoter, removes voted codes files, makes all files world-readable in ${SEDE_ROOT_VOUT}, sort votes.
edit [FILE[S] [-in|-out|-vin|-vinread|-vout|-polls|-tmp]]
Starts your editor (${EDITOR}) over FILEs, FILE can be a file-pattern. By default the file is sought in ${SEDE_ROOT_IN}, but with -out it is searched in ${SEDE_ROOT_OUT}, -vin it is searched in ${SEDE_ROOT_VIN}, -vinread it is searched in ${SEDE_ROOT_VINREAD}, -vout it is searched in ${SEDE_ROOT_VOUT}, -polls it is searched in ${SEDE_ROOT_POLLS}, -tmp it is searched in ${SEDE_ROOT_TMP}, (-in it is searched in ${SEDE_ROOT_IN}, for completeness). Without argument defaults to ${SEDE_ROOT_IN}/c_template

shortcut: `e'.

Erases and scrambles data that contains the link between voter and vote, it doesn't touch ${SEDE_ROOT_OUT}/code_record_M or saved files from mkrevote, it does scramble returned ballots in ${SEDE_ROOT_VIN}. Also scrambles a saved archive for the poll name in ${SEDE_ROOT_POLLS}. The command only works if the current poll is not "locked" (see makes).
eraseall Erases what erase erases, but also what mkrevote
makes and for completeness codespervoter. The command only works if the current poll is not "locked" (see makes).
fieldpipe [--designate | -d] FIELD [FIELD2]
fieldpipe --get | -g FIELD [FIELD2]
fieldpipe --see | -s
fieldpipe --move | -m FROM_FIELD [FROM_FIELD2] TO_FIELD
Reads data which has the same format as the voters registration file (typically ${SEDE_ROOT_IN}/c_voters) from standard input, and calls `sede votersfield' over that data with the given argument. See `sede votersfield' for the meaning of the arguments. Without arguments, fieldpipe defaults to `--designate'.
Example usage vim(1): open the voter-registration (${SEDE_ROOT_IN}/c_voters), highlight a line, and type: `:'<,'>!sede f encrypt'. That marks the field `encrypt' on the highlighted lines, so it can be edited (for instance).

shortcut: `f'.

get_voter M
Gets the voting voters, needs ${SEDE_ROOT_IN}/c_findcode, needs ${SEDE_ROOT_VOUT}/votesM and ${SEDE_ROOT_VOUT}/.voted_codesM, creates ${SEDE_ROOT_VOUT}/votersM poll-number (line number of the poll-name as defined in ${SEDE_ROOT_IN}/c_pnames) for which voting voters are extracted (see also sede get_voters). This latest file is needed by some subsequent modules in the processall row of commands, so you cannot simply not-run this module if you don't want a list of active voters.
Runs get_voter over polls 1 to N, where N is the number of polls defined in ${SEDE_ROOT_IN}/c_pnames.
getitem votecode next VOTECODE POLLNUMBER
With votecode next gets the `next' votecode for the next poll as stored in ${SEDE_ROOT_OUT}/codespervoter. VOTECODE is the vote code of a voter for POLLNUMBER poll. The return is the string NEXTPOLLNUMBER:VOTECODE;WEIGHT

This command is meant for higher level code, to have easy access to items without having to compute such things themselves.

Gets voting-areas from returned ballots, looks at ${SEDE_ROOT_IN}/c_find_votearea, creates ${SEDE_ROOT_VOUT}/votesM and ballots scrubbed of voting areas in ${SEDE_ROOT_VINREAD} (if requested, see ${SEDE_ROOT_IN}/c_mk_readable).
Runs getvote over all files in ${SEDE_ROOT_VIN}. Creates a list of vote codes which voted, for each poll: ${SEDE_ROOT_VOUT}/.voted_codesM.
givename [cutname] [hide[[:|+]MESSAGE]]
Makes the varies result files of a vote in ${SEDE_ROOT_VOUT} more presentable. It does this by creating more appealing and configurable filenames for the result-files, and creating an HTML document which links to these results. With `cutname', first runs `cutname' (see elsewhere), which resets the changes made: `givename' expects result files under their original names. With `hide', or if the web publication directory ${SEDE_ROOT_VOUT} is empty, places a place-holder in ${SEDE_ROOT_VOUT}/${SEDE_INDEX} (with small logo if `+' is used instead of `:', or if MESSAGE is empty); optional MESSAGE is prepended to that file.

`givename' creates three directories under ${SEDE_ROOT_VOUT}: `./c/', `./o/', `./s/'. Under `./c/' ("configuration") the configuration files are placed, excluding ${SEDE_ROOT_IN}/c_voters - the voter registration file -, but including ${SEDE_ROOT_OUT}/codespervoter - votecode records - if votes in abstention are published anyway (see ${SEDE_ROOT_IN}/c_abstention). Under `./o/' ("open") the result-files under their new names (see below), without an index file: voters get the system listing with important information like creation time and file sizes. Under `./s/' ("sede") the result-files again (hard linked) under their original hard-coded names (for a remote sede to recognize). The directory ${SEDE_ROOT_VOUT} contains the HTML-link documents, and the graphics-theme chosen for those HTML-link documents.

Renaming result files: `givename' renames result files in ${SEDE_ROOT_VOUT} with the name of the poll (as described in ${SEDE_ROOT_IN}/c_pnames) into the filename before a dash `-', and a ~/.sederc defined element for that file after that dash. The ~/.sederc variables defining the second filename element are:
Example: the file ${SEDE_ROOT_VOUT}/votes3, containing the votes for poll number 3, would become: ${SEDE_ROOT_VOUT}/$( head -3 ${SEDE_ROOT_IN}/c_pnames | tail -1 )-${SEDE_INDEX_VOTES}, which might be ${SEDE_ROOT_VOUT}/TeaOrCoffee-TheVotes, if the poll-name is "TeaOrCoffee" (line 3 of ${SEDE_ROOT_IN}/c_pnames), and ${SEDE_INDEX_VOTES} is "TheVotes" (variable defined in ~/.sederc).

`givename' generates `${SEDE_ROOT_VOUT}/defvote', containing only the search-patterns needed to re-count votes in an identifier="CONTENT" format.

Generating HTML: givename generates ${SEDE_ROOT_VOUT}/${SEDE_INDEX}: providing HTML link access to the result files and ${SEDE_ROOT_VOUT}/setup.html: providing HTML link access to the copied poll configuration files in ${SEDE_ROOT_VOUT}/c/. The following rules apply to this HTML generating process:

- All links point into `./', which is ${SEDE_ROOT_VOUT}.

- Only result files that are present in ${SEDE_ROOT_VOUT} when `givename' is running will be mentioned in ${SEDE_ROOT_VOUT}/${SEDE_INDEX}.

- If ${SEDE_ROOT_IN}/c_explainPOLL-NUMBER files are present, the heading above each consecutive poll chapter within ${SEDE_ROOT_VOUT}/${SEDE_INDEX} will itself be a link to a copy of ${SEDE_ROOT_IN}/c_explainPOLL-NUMBER in ${SEDE_ROOT_VOUT}. The ${SEDE_ROOT_IN}/c_explainPOLL-NUMBER files will be copied toward a ${SEDE_ROOT_VOUT}/POLLNAME-${SEDE_INDEX_EXPLAIN} name (see also above ${SEDE_INDEX_EXPLAIN}). This gives voters a chance to read what the vote was about (see ${SEDE_ROOT_IN}/c_explainPOLL_NUMBER).

- If a result file contains no data, a notice (not as a link, as normal text) will be put into ${SEDE_ROOT_VOUT}/${SEDE_INDEX}. This notice contains the ${SEDE_INDEX_...} filename part, with the content of ${SEDE_INDEX_NONE} following it immediately (see ~/.sederc). These notices are collected at the end of each poll chapter within ${SEDE_ROOT_VOUT}/${SEDE_INDEX}.

- ${SEDE_INDEX_UNWEIGHTED} is used as a signal that an addition is a simple addition of votes, ignoring the optional weight element of a vote. (See ~/.sederc).

- The first line of ${SEDE_ROOT_IN}/c_theme specifies the icons theme used:
* If the first line is empty, then there are no icon links (<img src=...>) included in ${SEDE_ROOT_VOUT}/${SEDE_INDEX} or ${SEDE_ROOT_VOUT}/setup.html.
* If not empty, the first line is subjected to shell variable expansion within a sede environment. Example: a first line containing `${SEDE_LIB}/extras/icons.flower.tar.gz' might be expanded into `/usr/local/lib/sede/extras/icons.flower.tar.gz', `${SEDE_ROOT_IN}/icons.flower.tar.gz' into `/home/me/.sede/in/icons.flower.tar.gz', and ~/archive.tar.gz into /home/me/archive.tar.gz. Environment variables are also expanded.
* The following icon-archives are (by default in ${SEDE_LIB}/extras/) available to provide the graphics. Some icon archives contain small icons, others may be very large and perhaps use up significant bandwidth (sizes excluding background images):
* icons.null.tar.gz (4k bytes; small);
* icons.color.tar.gz (7k bytes; colored beams);
* icons.blocks.tar.gz (10k bytes; symbolic black/white);
* icons.command.tar.gz (15k bytes; sede command used);
* (17k bytes; desktop);
* icons.orig.tar.gz (20k bytes; slightly off drawings);
* icons.button.tar.gz (35k bytes; round buttons);
* icons.bee.tar.gz (173k bytes; mathematical buzz);
* icons.flower.tar.gz (393k bytes; flower power);
The icons theme is also copied to ${SEDE_ROOT_VOUT}/icons.tar${SEDE_X_ZIP_EXT}.

- The second line in ${SEDE_ROOT_IN}/c_theme is expected to contain a HTML <body> (or <BODY>) tag for ${SEDE_ROOT_VOUT}/${SEDE_INDEX} and ${SEDE_ROOT_VOUT}/setup.html, with any arguments desired. For instance: `<body background="./background.jpg">' would set a background image.

- The third line in ${SEDE_ROOT_IN}/c_theme is used for the HTML title content. The data there is put between the HTML <title> and </title> tags. Variables are expanded according to Z-shell rules ($MYVAR, ${MYVAR}, $( MYCOMMAND )), in a sede environment. The special title `default-title' causes a combination of the overall poll name (as defined in ${SEDE_ROOT_IN}/c_name) and the present date/time to be used.

- The fourth line in ${SEDE_ROOT_IN}/c_theme is used for the opening tag of the pollname header, for instance <h1>. The content of this line is copied, it may contain more or less. For instance <hr> <h1 align="center">.

- The fifth line in ${SEDE_ROOT_IN}/c_theme is used for the closing tag of the pollname header, for instance </h1>. The content of this line is copied, it may contain more or less. This is therefore the place to define properties of the next paragraph: </h1> <p align="center"> for instance.

- The sixth line in ${SEDE_ROOT_IN}/c_theme is used for the tag that will be between poll item links. Basically: use <br> here if you want the links above each other, and leave empty to make them appear horizontally next to each other.

- The variable ${SEDE_INDEX_ALT} is used for the alt="..." option for all graphics tags <img ...> in ${SEDE_ROOT_VOUT}/${SEDE_INDEX}. Exceptions: the variable ${SEDE_INDEX_ALT_CONFIG} is used for the alt="..." option to the graphics tag <img ...> that points in ${SEDE_ROOT_VOUT}/${SEDE_INDEX} to ${SEDE_ROOT_VOUT}/setup.html, and as content for that link if no graphics theme is being used. The variable ${SEDE_INDEX_ALT_CONFIGBACK} is used for the alt="..." option to the graphics tag <img ...> that points in ${SEDE_ROOT_VOUT}/setup.html to ${SEDE_ROOT_VOUT}/${SEDE_INDEX}, and as content for that link if no graphics theme is being used.

- The variable ${SEDE_INDEX_CONFIG_TITLE} is put at the start of the body of ${SEDE_ROOT_VOUT}/setup.html. For example: SEDE_INDEX_CONFIG_TITLE='<h4 align="center">poll configuration</h4>'

- `givename' creates a copy of the addition result files in HTML format.

(See also: pollsconf.)

Gives short description of COMMAND, FILE, or VARIABLE.

Shortcut: `h'.

Gets the invalid votes, and removes them from ${SEDE_ROOT_VOUT}/votesM, (uses ${SEDE_ROOT_OUT}/secret_master_M), creates ${SEDE_ROOT_VOUT}/invalid_votesM.
Reads standard input, and searches for STRING, then removes newlines in input for up to N characters (excluding newlines), or the occurrence of STRING2. After the occurence of STRING2, when it is actively removing newlines, it prints an additional newline. Before the occurence of STRING, when it is not removing newlines, it prints an additional newline. The result is that text between STRING and STRING2 will end up on a single line with a maximum length of N characters after STRING. STRING and STRING2 are interpreted as text with the exception of the ? character, which matches every character in the input.
linerandom FILE
Randomizes the lines in FILE and echoes the result to standard output.
lss [-in|-out|-vin|-vinread|-vout|-polls|-tmp|-all]
Lists files: ${SEDE_ROOT_OUT} for -out, ${SEDE_ROOT_VIN} for -vin, ${SEDE_ROOT_VINREAD} for -vinread, ${SEDE_ROOT_VOUT} for -vout, ${SEDE_ROOT_POLLS} for -polls, ${SEDE_ROOT_TMP} for -tmp ${SEDE_ROOT_IN} for -in, all of the above for -all. Defaults to the current working directory.
makes [ u | unlock
| lock ] | [ t | test ] [ old ] [ step[:BALLOT:PASS:LINE:CHARACTER] | ballotstep[:B:P:L:C] | passstep[:B:P:L:C] | linestep[:B:P:L:C] | unitstep[:B:P:L:C] | echolinestep[:B:P:L:C] | echounitstep[:B:P:L:C] | jumpstep[:B:P:L:C] ]

Generate ballots, related records and ballot flag files, in short: everything to create ballots and records ready to be send to voters from the input files in ${SEDE_ROOT_IN}.

Without `test' or `t', a lockfile is created to prohibit overwriting or erasing the poll with subsequent calls to makes, or by other potentially damaging sede commands. With `unlock' or `u' does nothing but remove the lockfile, with `lock' does nothing but create the lockfile. The lockfile is simply the existance of a file `call_lock' in ${SEDE_ROOT_IN}, signalling the lock.

When you give `old' as an argument, vote-codes and passwords are not created new, but read from the flag-files: ${SEDE_ROOT_OUT}/flags_N. The flag used is sede_codes;POLLNUMBER;VOTECODE,PASSWORD. See ^-flag() for how to put flags in the flags-files.

With one of the *step arguments, goes into interactive stepping mode for debugging your ${SEDE_ROOT_IN}/c_template ballot: `ballotstep' steps per ballot, `passstep' steps per run (and re-run) over the ${SEDE_ROOT_IN}/c_template, `linestep' steps per line over the (current) ${SEDE_ROOT_IN}/c_template, `unitstep' steps per character over the (current) ${SEDE_ROOT_IN}/c_template. `echolinestep' is `linestep' while echoing input/output data, `echounitstep' is `unitstep' while echoing input/output data. `jumpstep' Is `echounitstep' and jump to the first occurence of ^, then become `echounitstep'.

`step' follows ${SEDE_BALLOTS_STEPMODE} defined in ~/.sederc (if it contains `ignore' or is unset/zero-length, `step' defaults to `echounitstep'). You can switch between stepping modes, and no stepping while stepping. Online help is available during stepping, see there on how to exactly operate stepping interactively (start a stepping mode and give `h'<enter> to see online help).

With the postfix :BALLOT:PASS:LINE:CHARACTER to a stepping argument, stepping begins at the given coordinates as if the ballot variable `^-step' had been encountered there (at ballot BALLOT, pass PASS, line LINE, and character CHARACTER (all numbers). CHARACTER value `0' is magic and stands for the end of line. If the coordinates are missed (because they didn't exist), then stepping starts immediately after where the coordinate would have been.

Shortcut: `m'.

Makes ${SEDE_ROOT_OUT}/code_record_M files from ${SEDE_ROOT_OUT}/secret_master_M files. M is the poll number. These files only store vote codes and passwords, no additional voter information optionally present in ${SEDE_ROOT_OUT}/secret_master_M .
mkrevote N
Saves voterdata for complaining voters (or voters who want to change their vote) for poll number N (as in ${SEDE_ROOT_IN}/c_pnames linenumber), needs hand-created `${SEDE_ROOT_OUT}/revote_codes_M', creates ${SEDE_ROOT_OUT}/secret_revotes_M which contains the data of the complaining voter for the vote he/she is complaining about.
Does nothing, except act like a standard sede command (say "done" if verbosity level allows it, and return true).
Get a list of vote codes who didn't voted, needs ${SEDE_ROOT_VOUT}/.voted_codesM, creates ${SEDE_ROOT_VOUT}/notvotedcodesM
Overview of installation/setup. With ${SEDE_SILENT} unset (verbose running) gives a lot of information, if it is set only reports on the current ${SEDE_ROOT_*} variable settings (see also silent).
pollsconf [ [c_]CONFIGURATIONFILE | check | c | n | all | help | v | t | p | v_f ]
Without arguments or with all, configure all poll-configuration files (${SEDE_ROOT_IN}/c_*) interactively. With CONFIGURATIONFILE prompts only for that file's configuration. With `check' or `c' presents an overview of the current configuration. With `n' gives the overall pollname (configuration of ${SEDE_ROOT_IN}/c_name). With `help', gives an overview of the meaning of all standard files in ${SEDE_ROOT_IN}.
The always preceding c_ in the poll configuration file names may be ommited in the argument, and if the configuration file name contains `_' characters, the trailing part without the `_' is also recognized.

Several shortcut arguments: v is equivalent to c_voters, p is equivalent to c_pnames, t is equivalent to c_template, v_t is equivalent to c_voters_fieldnames.

Shortcut: `pc'.

> sede pollsconf c_n_passes
> sede pc passes
these are identical commands (configure ${SEDE_ROOT_IN}/c_n_passes).

pollsconf automatically recognizes locally added theme archives (see c_theme) stored under ${SEDE_LIB}/extras/, with filenames starting with "icons".

processall [-v | --verbose] [-c | --continue] [COMMAND] [COMMAND]

When returned ballots are saved in ${SEDE_ROOT_VIN}, this command processes them into publishable results in ${SEDE_ROOT_VOUT}. With `-v' or `--verbose' it is more verbose. When you give as an argument a sede COMMAND which is called by processall, then processall aborts before running that sede command. If you give as an argument `-c' or `--continue', processall will start with the given command. Processall is a meta script, calling these sede commands in this order: rmprocessall, setup, getvotes, invalidvotes, putweight, get_voters, notvotedcodes, correlate, doublevotes, addvote, addvote_weight, addvote_compact, doti, givename.

Shortcut: `p'.

putaddress [addvoter]
Adds to (or creates it if not existing yet) ${SEDE_ROOT_OUT}/flags_N files the routing information for the corresponding ballot file, as pointed to by ${SEDE_ROOT_IN}/c_address (with a voters-file field number). With `addvoter' it processes only one flags_N file: for the last ${SEDE_ROOT_IN}/c_voters line. The address information in ${SEDE_ROOT_OUT}/flags_N is preceded by a line break and `sede_address;'.
Adds weight information to votes, needs ${SEDE_ROOT_OUT}/votesN (see getvote(s)).
Randomizes the lines in the ${SEDE_ROOT_IN}/c_voters file. This can be used to erase links between voters and their ballots. Unless you're using rundir (for instance to decrypt ballots), you can randomize ${SEDE_ROOT_IN}/c_voters immediately after ballot creation without affecting the voting process.
returns VALUE
Low level return-value command, returns the value it has been given.
rmout [COMMAND]
Removes output-data in ${SEDE_ROOT_OUT}, ${SEDE_ROOT_VIN}, ${SEDE_ROOT_VOUT} ${SEDE_ROOT_TMP}, and ${SEDE_ROOT_VINREAD}, or runs COMMAND over the otherwise affected files.
Removes all that `processall' will create, everything in ${SEDE_ROOT_VOUT}.

Shortcut: `rmp'.

Removes ${SEDE_ROOT_VOUT}/votesPOLL-NUMBER files, these files act like setup for vote-processing: if a ${SEDE_ROOT_VOUT}/votesPOLL-NUMBER file for a poll exists, the voter returned data available is generated for this poll while running processall. Without arguments the whole setup (if any) is removed. With just POLL-NUMBER (1, or 2, or 3, etc.) the ${SEDE_ROOT_VOUT}/votesPOLL-NUMBER files 1 to POLL-NUMBER are removed, with `-p POLL-NUMBER [POLL-NUMBER..[...]]', only the setup of the mentioned polls is removed.
Runs (system) commands within an environment as set by ~/.sederc and /etc/sede. The content of ${SEDE_RUN_SHELL} (see elsewhere) is used to set an interpreter. COMMAND and optional ARGUMENTS (or more shell commands) are put in the file ${SEDE_ROOT_TMP}/run_x, and it is executed. The settings of ${SEDE_SILENT} and the poll lockfile (${SEDE_ROOT_IN}/call_lock) do not affect execution.

> sede run 'ls $SEDE_ROOT_POLLS'
see what poll archives are stored.

run returns with the error value of the executed command.

Runs runfield with appropriate arguments over every file in a directory. It executes command[s] found in COMMANDFIELD in the voter registration (${SEDE_ROOT_IN}/c_voters) over files *_VOTERNUMBER_* located by default in ${SEDE_ROOT_VIN}/ or in [.]/DIRECTORY when it is given. Through this command you can operate complex commands over a group of files that have been tagged in their filename with the number of the voter the file belongs to. The file is assumed to belong to the voter who is registered on a line VOTERNUMBER in ${SEDE_ROOT_IN}/c_voters, when the latest occurence of underscore `_' NUMBER underscore `_' in the filename is VOTERNUMBER. The filename found replaces the literal string `^FILE' (excluding quotes) in the command found (see runfield).
File `a_8_bla_3_.cpt' is assumed to belong to the voter registered on line 3, the "voter serial number is 3". If a field named "decrypt" is defined in ${SEDE_ROOT_IN}/c_voters_fieldnames, then by running sede rundir decrypt, that field is executed over a_8_bla_3_.cpt: sede runfield decrypt 3 a_8_bla_3_.cpt [go]. That field in ${SEDE_ROOT_IN}/c_voters on the third line, could (for instance) hold the commands necessary to decrypt files belonging to voter 3.

When specifying multiple COMMANDFIELDs, it is possible the file can no longer be found because its name was changed. Unzipping usually removes a suffix, encryption adds one, etc. If a file moved, a new filename can be defined by having the command in COMMANDFIELD put a filename in ${SEDE_ROOT_TMP}/newname. If that filename is not fully qualified, it is assumed to be local to ${SEDE_ROOT_VIN}, unless [.]/DIRECTORY was given as an argument, in which case it will be assumed local to that directory instead.

If the file was moved by the commands, but no new name was defined in ${SEDE_ROOT_TMP}/newname, then rundir tries to guess a name for use with the next COMMANDFIELD. First rundir will look if the filename stripped of its latest postfix exists, if so that file will be used for the next COMMANDFIELD as `^FILE' (see runfield). If no file without latest postfix is found, the original filename is stripped of all postfixes, but not including the latest occurence of `_N_' which is left intact even if present in a postfix. That reduced filename is then matched against all files that have the same beginning as the thus reduced name, and the one with the latest ctime (see file system) is used.
Original name: ./filename._8_.a.b.c.gz
New name: ./filename._8_.a
Match name against: ./filename._8_*
Found name: ./filename._8_.a

With "steprundir", rundir halts before executing commands (calls runfield without its `go' argument).

Note: if you plan on using rundir, don't scramble the lines in the voter registration between the moment the files are being generated, and have been processed by rundir, otherwise the "voter serial numbers" won't match with the file names anymore.

Runs commands registered for voter VOTERNUMBER, an integer indicating the line in ${SEDE_ROOT_IN}/c_voters where the voter is registered. The commands are read from the field FIELDNAME as defined by ${SEDE_ROOT_IN}/c_voters_fieldnames. Commands found are passed to `sede run' and are (therefore) assumed to be regular shell commands, hence sede commands must be preceded by `sede ' (unless you've set the ${PATH} to include SEDE commands, see set.path).

Every occurrence of the literal string ^FILE in the command line found in ${SEDE_ROOT_IN}/c_voters, is replaced by the argument INFILE to runfield. Similarly every occurence of the literal string ^SERIAL is replaced by the `voter serial number' (the line number on which the "current voter" is registered in ${SEDE_ROOT_IN}/c_voters, which is assumed to be defined in the filename by the latest occurence of `_NUMBER_' in that filename). The commands may contain redirections, and multiple commands can be concatenated by using `;' etc.

With `go' (after INFILE), runfield prints the command found and asks for confirmation.

Warning: be sure the commands in the voter-registration are really what you want them to be, `rm ~/*' will be executed without hesitation and with serious consequences.

runfield serves (also) as a back-end to rundir, and the flag sede_divide_run;. Typical usage would be to encrypt/decrypt ballots using password type encryption tools. runfield uses run to execute commands.

voter registration: ${SEDE_ROOT_IN}/c_voters:
,,,,export SECRET="mY Very s0cret cey"; ccrypt --encrypt --envvar SECRET ^FILE,,,,,,
field names definitions: ${SEDE_ROOT_IN}/c_voters_fieldnames:

,,,gzip ^FILE,echo "another secret" > ${SEDE_ROOT_TMP}/key, ccrypt --encrypt -k ${SEDE_ROOT_TMP}/key ^FILE, sede scramble ${SEDE_ROOT_TMP}/key;rm ${SEDE_ROOT_TMP}/key, ccrypt --decrypt -k ${SEDE_ROOT_TMP}/key ^FILE,,,,
field names definitions: ${SEDE_ROOT_IN}/c_voters_fieldnames:

Adding the flag (with ^-flag[...] in the template ${SEDE_ROOT_IN}/c_template):
would then encrypt that attachment according to the specified commands. For each voter, other encryption commands can be registered. For decryption, see rundir.

runfield returns with the error value of the executed command, unless an error was encountered before the command(s) could be executed, in which case it returns false.

Note: using MIME (/etc/mime.types, /etc/mailcap) might make usage of attachments much easier for voters, and would set the appropriate MIME flags in the e-mail for voter software to recognize.

saves all files in ${SEDE_ROOT_IN} into an archive in ${SEDE_ROOT_IN}/.backup_HOUR.tar.gz, where HOUR is the current hour as given by ` date(1) +%H `.

Shortcut: `s'.

scramble FILE
Scrambles FILE with random data.
secondary [BALLOT_NUMBER]
If ballots contain un-expanded ^-votecode(POLL), or ^-password(POLL) variables, if appropriate flags are set these can be filled with their proper content. Works also for short or upper-case variants of these variables. Uses sede_codes;POLL;VOTECODE,PASSWORD flags in flags-file (see ^-flag). With BALLOT_NUMBER only operates on that ballot.
Checks the sede environment, gives verbose output for manual checking.
see [-in|-out|-vin|-vinread|-vout|-polls|-tmp]
Starts ${SEDE_BROWSER} over ${SEDE_ROOT_VOUT}/${SEDE_INDEX}, or over a directory: ${SEDE_ROOT_OUT} for -out, ${SEDE_ROOT_VIN} for -vin, ${SEDE_ROOT_VINREAD} for -vinread, ${SEDE_ROOT_VOUT} for -vout, ${SEDE_ROOT_POLLS} for -polls, ${SEDE_ROOT_TMP} for -tmp ${SEDE_ROOT_IN} for -in.
sendallmail [sendstep|nosendstep] [EXTENSION]
Sends all ballots that match the optional EXTENSION, if no extension is given all ballots are send (using sendmail). With sendstep sends ballots stepwise, asking for confirmation to continue after each ballot, allowing you to read messages, and asking for confirmation before running any commands called through ^-flag[sede_divide_run;...] (see sendmail, and ${SEDE_ROOT_TMP}/.sendmail_step). With nosendstep sends without stepping and removes any stale ${SEDE_ROOT_TMP}/.sendmail_step).
Send the ballot for the last voter in ${SEDE_ROOT_IN}/voter (using sendmail).
sendmail BALLOT_FILE
Sends BALLOT_FILE, needs ${SEDE_ROOT_OUT}/flags_BALLOT_NUMBER. Doesn't send empty ballots having only 1 or 0 characters. If ${SEDE_ROOT_TMP}/.sendmail_step exists: halts after sending a ballot, and lets runfield ask for confirmation before running any sede_divide_run command fields. If sendmail seems stuck in stepwise sending/execution, there is probably a stale ${SEDE_ROOT_TMP}/.sendmail_step file laying around. sendmail writes a send log in ${SEDE_ROOT_OUT}/sendlog.

mail agent:

sendmail uses by default as mail agent mailx (mail), in which case the ballot is send out in one piece ignoring flags specifying attachments.

If it is non-empty, the executable in ${SEDE_EXEC_MAILSEND} is called for each ballot, with pointers in the environment to the current ballot: ${ADDRESS} ${SUBJECT} ${BODY} ${FLAGS} ${NUMBER}. ${ADDRESS}: the email address of the recipient, ${BODY}: the filename pointing to the ballot, ${SUBJECT}: the email subject, ${FLAGS}: the filename of the ballot flags file (see ^-flag, ${SEDE_ROOT_IN}/c_template), and ${NUMBER}: the serial number of the ballot.

As a special case, if ${SEDE_EXEC_MAILSEND} points to a file named `mutt', the ballot is cut up into attachments (according to the flags if any), and mutt arguments are given to ${SEDE_EXEC_MAILSEND}. Note: mutt is executed and given two linebreaks, to break through its startup user dialog.

A second special case: if ${SEDE_EXEC_MAILSEND} starts with `self ' (`self' + SPACE), then the command immediately following `self ' is executed for each ballot, with an environment set as with non-empty, non-mutt ${SEDE_EXEC_MAILSEND} (${ADDRESS} ${SUBJECT} ${BODY} ${FLAGS} ${NUMBER}), and with the base email and all subsequent attachments (if any) in the positional argument list (${BODY} points to the original uncut ballot). You are then able to use ballot-cutting, but process the parts according to your own design, without being troubled by mutt formatted arguments/linebreaks.

sendmail Reacts to several flags in ${SEDE_ROOT_OUT}/flags_BALLOT_NUMBER:

YOUR_SUBJECT will be the subject of the email, this header overrides all other subject definitions. The latest occurence of this flag will be used.

SUBJECT_FILE is opened as a file under ${SEDE_ROOT_IN}, and its first line used as the subject. The latest occurence of this flag will be used. It has a lower precedence than sede_subject;, but it overrides the poll-wide subject definition in ${SEDE_ROOT_IN}/c_address (line 2).

YOURHEADER is put into the header area of the message (user defined header).

(This flag is only effective when ${SEDE_EXEC_MAILSEND} in ~/.sederc is pointing to mutt.)

YOUR_FILE is made an attachment to the message, it will if not containing a full path be sought within ${SEDE_ROOT_IN}.

(This flag is only effective when ${SEDE_EXEC_MAILSEND} in ~/.sederc is pointing to mutt, or starting with `self '.)

The ballot is cut in two sections from the first occurence of (grep -E) pattern PATTERN, the above section remains the primary email, the second section becomes an attachment as ATTACHMENT_NAME. ATTACHMENT_NAME defaults to attachment-N, where N is the serial number of the attachment.

Repeat occurences of this flag in ${SEDE_ROOT_OUT}/flags_BALLOT_NUMBER will operate on the newly shortened primary email, so the ballot can effectively be cut up into many attachments. You can write the flags in the natural order though, they are processed latest to first (bottom to top of the flags file), the attachments are attached like their order on the original ballot. The line matched by PATTERN is deleted altogether. It is important to get this flag into the flags file in the correct order.

(This flag is only effective when ${SEDE_EXEC_MAILSEND} in ~/.sederc is pointing to mutt, or starting with `self '.)

The same as sede_divide, except it also operates commands on the attachment. COMMANDTITLE is passed to runfield (as its FIELDNAME argument), along with the current voter number (the line the current voter is registered on in ${SEDE_ROOT_IN}/c_voters_fieldnames, as VOTERNUMBER) and the current attachment (as INFILE). This causes the commandline that is registered for the current voter under the field COMMANDTITLE (field-names are defined in ${SEDE_ROOT_IN}/c_voters_fieldnames) to be executed. Every occurrence of ^FILE within the command line found there is replaced by the name of the current attachment file.

If the name of the attachment is lengthened by the commands but retains its former base, and only one matching file is found, that file is assumed to be the attachment file. So, if a command adds a postfix, the attachment should be found without trouble. If the file ${SEDE_ROOT_TMP}/newname contains a filename, that filename will be used instead. ${SEDE_ROOT_TMP}/newname is deleted before the command-line is executed, and after its content has been examined if it has been created (by you).

An unlimited number of COMMANDTITLEs can be used, each commandline found in ${SEDE_ROOT_IN}/c_voters can contain any number of commands and redirections (including no command at all). sendmail catches errors occuring with executing these commands, and will promt the user.

(This flag is only effective when ${SEDE_EXEC_MAILSEND} in ~/.sederc is pointing to mutt, or starting with `self '.)

sede_attachment;YOUR_FILE And sede_divide;PATTERN;ATTACHMENT_NAME can be used intermixed, causing the attachments to become ordered like these flags are. These flags are processed bottom-up, so the latest flag is processed first, then the attachments are added in the natural order: the order of their location on the original ballot, and the order of the flags that describe the attachments. For both hold that if the filename (YOUR_FILE or ATTACHMENT_NAME) is identical to `sede_delete_this_attachment', the attachment is not added, but ignored. It is important to get this flag into the flags file in the correct order.

(This flag is only effective when ${SEDE_EXEC_MAILSEND} in ~/.sederc is pointing to mutt, or starting with `self '.)

Note: all flags starting with sede_ are reserved for future expansion, use them at your own risk of namespace collision with future versions of sede.

sendmail returns `30' as error value after a user-abort.

set.path [first|last|never]
Sets sede library and sede user library (${SEDE_EXEC_DIR}) in your ${PATH}. With first sets sede first in your search-path, with last sets sede last, with never removes sede from the search-path, and also unsets the sede environment variables. If no argument was given, reads the value `first', `last', `never' from ${SEDE_SHELL_ORDER}. set.path Refuses to run with `never' if ${SEDE_SHELL_USE} is `yes'.

This  command  has to run  in the current  shell: `. sede set.path [ARGUMENT]', to be effective. Doing that leaves the environment augmented with sede variables that the sede commands need. Changing the value of these variables changes the behaviour of subsequent sede commands (also if you go through the sede "shell wrapper" as in `sede nop').

After running . sede set.path with `first' or `last', and then with `never', nothing is changed (except the history record of your system shell).

Sets up ${SEDE_ROOT_VOUT}/votesPOLL-NUMBER files, if such a file exist for a poll, data is processed for it by processall. With just one POLL-NUMBER, a setup is created for polls 1 to POLL-NUMBER, with -p a setup is created only for the given POLL-NUMBERs, without any arguments a setup is created for all polls.
shell [ --help ] | [ --zsh | --bash | --csh | --sh | --ksh [COMMANDSFILE] ] | [ --noprompt ] [ --log [ LOGFILE ] ] [ INITFILE ]
Issue (sede) commands interactively in a (special) subshell (see also set.path).

Some additional commands are interpreted by shell: abort-on, abort-off,
buf-all, buf-some, buf-off,
bye, exit, quit,
echo-on, echo-off,
exec-on, exec-off,
halt-on, halt-off,
path-on, path-off,
p:exec, p:[default], p:none, p:user,
scroll-hist[:BUFFER], -,
search-on, search-off,
sede-first, sede-last, sede-never,
silent-on, silent-off,
verbose-on, verbose-off,
which COMMAND,
?, ??,
CTRL-L, `,'
-[1|2|3|...16][ POSTFIX], ^[^[^]][ POSTFIX],


Starts --SHELL (zsh, bash, csh, sh, ksh) with an environment that sede commands understand, and the ${PATH} variable pointing to sede commands according to the setting of ${SEDE_SHELL_ORDER}. With --csh does the same but if COMMANDSFILE is present, ${SEDE_SHELL_LOGINSHELL}=on is ignored. You'll have to make sure not to (completely) reset variables in your shell init process, otherwise it doesn't work. ${SEDE_SHELL_USE} can be used to test for sede during shell init. All other arguments to sede shell are ignored if --SHELL is given (see set.path for a similar effect in the current shell, which probably also works for other shells than directly supported by shell). If it doesn't work (commands are not found), setting SEDE_SHELL_LOGINSHELL=off in ~/.sederc might help (bash, ksh, sh).

Without `--SHELL', `sede shell' presents its own (Zsh adapted) interface, with some features potentially usefull to a sede user. sede shell has no job-control, or multi-lined commands.

With --noprompt doesn't print a prompt, and the startup notice is suppressed.

--log [LOGFILE]
With --log writes a logfile of executed commands into /tmp/.PID.sede_x.log, or into LOGFILE if it is given. If ${SEDE_SHELL_ABS_LOG} is `on', the log is "absolute" (see ${SEDE_SHELL_ABS_LOG}) log file name.

With INITFILE, runs INITFILE in the shell process itself (interpreted as sede shell commands), then waits for user input (unless exit, bye or quit were executed, in which case sede shell exits).


The sede shell build-in commands are executed first. If none matched the input given, sede commands and system commands are searched in the order ${SEDE_SHELL_ORDER} defines. System commands are only searched if ${SEDE_SHELL_PATH} doesn't block it. ${SEDE_SHELL_EXEC} can block all normal execution of all commands except build-ins. Three build-ins control these variables interactively (`path-[on|off]', `sede-[first|last|never]' and `exec-[on|off]'. System commands are executed in the current environment (though you can execute them in a subshell, see `;').


Since it is possible to execute commands in the shell process itself, sede shell variables can be adjusted directly (using Z-shell syntax), causing changes in behaviour of subsequent sede commands.

The most important variables are the ${SEDE_ROOT_*} variables, and the ${SEDE_SHELL_*} variables (which are all explained at ~/.sederc). Only in sede shell are shortcut-versions for the ${SEDE_ROOT_*} variables in the environment. These shortcuts (to processing directories) have a name consisting of the trailing part of the long name in lower case: ${SEDE_ROOT_IN} -> ${in}, ${SEDE_ROOT_OUT} -> ${out}, same for: ${vin}, ${vinread}, ${vout}, ${polls}, ${tmp}. These short-cut variables are continues copies of the longer versions, you can read them but not change them. Change the long versions instead.

The internal sede shell variables start with `SEDE_S_'.


When a command is executed in sede shell, it can find the content `yes' in ${SEDE_SHELL_USE} in the environment.

Sede shell saves its history buffers in ~/.sede_history when it is exitted (not killed), and reads them back in at startup. If sede shell is killed, the history is not written to ~/.sede_history. The history buffers are not a proper record of what was executed, use the log file for this purpose.

Some commands work on ~/.sederc (`silent'). Such and other changes to ~/.sederc do not become effective within sede shell, unless the ~/.sederc is executed within sede shell (`. ~/.sederc', or start a new instance of sede shell from a clean environment).

BUILT-IN COMMANDS: on error these return 1 (false), otherwise 0 (true).

`abort-on', `abort-off'
Abort on error, or don't, respectively. Default: ${SEDE_SHELL_ABORT} in ~/.sederc (`on' or `off').

`buf-all', `buf-some', `buf-off'
Puts the print-history-buffers tag into the prompt-string: for buf-all the tag for all buffers, buf-some the tag for some buffers, buf-off removes these print-history-buffers tags from the prompt (%B and %b). Default: defined in ~/.sederc (${SEDE_SHELL_PROMPT}) (see special characters).

Prints the (non-empty) history buffers into the logfile or to FILE if it is given. If no logfile is in use, uses the default /tmp/.PID.sede_x.log.

`bye', `exit', `quit
End shell.

Alters working directory. Default: directory into which sede shell started.

`echo-on', `echo-off'
Print the to be executed command to the screen before executing it. Default at startup: ${SEDE_SHELL_ECHO} in ~/.sederc (`on' or `off').

`exec-on', `exec-off'
Set executing commands, or not executing commands (except built-ins). Default: ${SEDE_SHELL_EXEC} in ~/.sederc (`on' or `off').

Print the user-prompt string.

Print the current setting of verbose-[on|off], abort-[on|off], path-[on|off] sede-[first|last|never] exec-[on|off] search-[on|off] echo-[on|off].

`halt-on', `halt-off'
Halts before executing the command for user confirmation. Default at startup: ${SEDE_SHELL_HALT} in ~/.sederc (`on' or `off').

Asks for an alpha-numerical password, then clears the screen and locks the input stream until the correct password is given. When no trailing arguments are present, or when `;' is used, it prints its own prompt. With `:' (`lock-input:[:]'), prints the user prompt (p:user) instead of its own prompt. With `SYSTEMCOMMAND' after a single `:' or `;' (`lock-input:SYSTEMCOMMAND', `lock-input;SYSTEMCOMMAND'), runs SYSTEMCOMMAND once, before printing a prompt. When `:' or `;' are doubled `::', `;;', runs SYSTEMCOMMAND before every new prompt that is printed. With `^' instead of `SYSTEMCOMMAND', substitutes the content of the latest history buffer for `SYSTEMCOMMAND'. A leading `;', if present, is first stripped from the history buffer. Commands are executed and logged in the logfile (if any) as "subshell system commands" (like shell builtin `;COMMAND'). Reports on breaking in attempts. Does only protect the current process, not other instances of sede shell. Reacts to ${SEDE_SHELL_VERBOSE}. 3 seconds timeout after false input.

`path-on', `path-off'
If a command is given, try the wider system beyond sede (according to ${SEDE_SHELL_ORDER}), or don't try the wider system, respectively. Default: ${SEDE_SHELL_PATH} in ~/.sederc (`on' or `off').

`p:none', `p:[default]', `p:user', `p:reset'
Giving `p:none' removes printing of any prompt string. Giving `p:' or `p:default' gives you the default prompt (`'). Giving `p:user' gives you the "user prompt", which can be configured. At startup, the user prompt is set from ${SEDE_SHELL_PROMPT} (see ~/.sederc), but it can be changed by calling `P:PROMPT' (see elsewhere). Giving `p:reset' resets the value of the user prompt to the value of ${SEDE_SHELL_PROMPT} (see ~/.sederc).

`p:none' can be set at startup with the argument --noprompt to shell. p:default, p:user, and p:none override (alter) the --noprompt argument and ~/.sederc settings from the moment they are called.

Set the user-prompt string. Some special sequences are recognized for the user prompt. The prompt is echoed using echo(1) -en "...", so some C escape sequences are also expanded (\a, \n). The prompt is also set to the user prompt if it was the default prompt.
%- : only `%-' is erased, no other `%...' are expanded, has to be postfixed to the prompt, otherwise it is ignored (much faster prompt)
%P : current overall pollname (${SEDE_ROOT_IN}/c_name)
%X : `lock' if poll is locked, `OPEN' if not
%x : `X' if poll is locked, `O' if not
%a : bell
%B : all history buffers are printed, has to be pre-pended to the prompt otherwise it is ignored
%b : some history buffers are printed, has to be pre-pended to the prompt otherwise it is ignored
%D : complete time/date
%d : current working directory
%% : a literal %
%! : command serial number
%? : latest exit code
%^ : the latest command
%. : trailing part of current working directory
%~ : working directory with ${HOME} replaced by ~.
%H : current hour
%h : hostname
%l : current tty line
%L : shell nesting level (starting from 0)
%M : current minute
%n : a line break
%s : a space (` ')
%S : current second
%u : program user
Default: defined in ~/.sederc.

Pushes COMMAND on the history stack.

`scroll-hist[:BUFFER]', `-',
Scroll back the history buffers one step. If BUFFER (a number) is present, delete that buffer and scroll the older buffers back in its place.

`search-on', `search-off'
Print information updates on how the command-search is progressing past the built-in searching. Default: search-off.

`sede-first', `sede-last', `sede-never'
If a command is given, search for a sede command first before trying ${PATH}, search sede last, or never search for a sede command, respectively. Default: ${SEDE_SHELL_ORDER} in ~/.sederc (`first', `last' or `never').

`silent-on', `silent-off'
Set/unset ${SEDE_SILENT} in the environment, setting the verbosity level of sede commands. This built-in doesn't affect ~/.sederc like sede silent does. Default defined in ${SEDE_SILENT}, in ~/.sederc (`yes' or `no').

Prints a comment containing the present date/time in the logfile. If no log file was being used, then also start log recording. Content trailing `stamp-log' is ignored, but will be present in the log.

`verbose-on', `verbose-off'
Alters verbose level of shell. Default: for interactive use defined in ${SEDE_SHELL_VERBOSE} in ~/.sederc (`on' or `off'); for non-interactive use follows ${SEDE_SILENT}.

`which' COMMAND
See which COMMAND would get executed.

`?', `??'
Give overview of sede shell built-ins (which are explained now), `??' explains each command shortly.

`CTRL-L', `,'
(^L, or a lone comma): clear screen.

Re-run older commands. For the form `^[^[...]]', the buffer number equal to the number of ^'s is re-executed. For the form `-N', the Nth buffer is re-executed. If SPACE + POSTFIX is appended, it is appended to the command when it is executed.

The command prefixes: `,', `;', and `' affect the history buffers, the prefix `?' only puts COMMAND in the history buffers. Other sede shell built-ins don't affect these buffers.

Force COMMAND as a sede command.

Force COMMAND as a system (${PATH}) command.

Sets exec-off echo-on search-on for COMMAND. COMMAND is recorded into the history buffers.

(dot space) Force COMMAND as a system (${PATH}) command, within the sede shell process.

Ignored up to end-of-line, # is only recognized if it is the first character in the input.

Bang expansion, search in the history buffers for the first command to match MATCH. MATCH is a literal pattern matched with the leading edge of the history buffers: `e' and `ech' match `echo'.

Run COMMAND according to the settings of sede-[first|last|never] and path-[on|off].

show [c | w]
Show conditions of release with argument `c', and warranty information with `w'. Show authors list if called without any arguments.
silent [on|off|yes|no]]
Without an argument, flips the value of ${SEDE_SILENT}, changing the current verbosity level. With off or no makes commands verbose, with on or yes makes commands more silent.

This command doesn't seem to work properly if the environment is preset, but it does. It just alters the value in ~/.sederc, it cannot touch the local environment because it is executing in a subshell. In a preset environment (set.path, shell --SHELL), flip the value of ${SEDE_SILENT} yourself, in sede shell use the built-ins silent-on and silent-off.

Truncates all ${SEDE_ROOT_VOUT}/votesM files and puts the untruncated version into ${SEDE_ROOT_VINREAD}.
Truncates FILE's lines to TRUNC_LENGTH, and delivers result to stdout.
unpackpoll ARCHIVE
Unpacks a poll saved by allsave. ARCHIVE is a full filename of the archive without a path, it is assumed to exist under ${SEDE_ROOT_POLLS}. If the argument doesn't end on `.gz', `.tar.gz' is automatically augmented to the given name. The command only works if the current poll is not "locked" (see makes).

Shortcut: `u'.

Checks whether the version in ${SEDE_ROOT_IN}/c_version is the same as the current sede version as reported by sede --version-short. If not, offers some advice. It does not upgrade the sede program itself, but notifies users if the program has been upgraded, and what to change if anything.
utils [ html2text | delvote ARGUMENTS | cute [ARGUMENTS] ]
`utils' is a common interface for small utilities. Each utility is discussed directly below:
utils html2text
Looks at each file in ${SEDE_ROOT_VIN}, checks if it contains `<html>', if so it prepends the file with `<pre>', and postfixes it with `</pre>', then pipes it through lynx and replaces the original file with the result. The aim is to reparse rogue html markup in the ballot returns (some webmailers tend to add it), and end up with presentable voting areas for voters who reply in html markup. It might be a good idea to keep the orginials handy somewhere else because original files get destroyed in the process. If you save multiple returns into one file, any voter who places a </pre> tag will affect the formatting of text below it, to prevent such, save each return into its own file before running this utility.
Deletes the ${SEDE_ROOT_OUT} records for the targeted vote. If BALLOT_NUMBER is given, it is assumed to be the ballot-number for the targeted voter, and that ballot-file is truncated. The targeted votes can only be in the end-results after processing returns as false-votes.
preline:CONTENT Place CONTENT in front of each line in the raw vote addition files.
votersfield --get FIELD [ --extra FIELD2 ] [ FILE ]
votersfield --cut FIELD [ --extra FIELD2 ] [ FILE ]
votersfield --put PUT_FILE FIELD [ FILE ]
votersfield --see [ FILE ]
votersfield --designate FIELD [ --extra FIELD2 ] [ FILE ]
Does mutations on FILE, a file in the format of the voters registration file (see ${SEDE_ROOT_IN}/c_voters), and echoes the result to standard output. Votersfield chooses by default the voters registration file ${SEDE_ROOT_IN}/c_voters. FIELD can be specified as numerical, in which case it is interpreted as a field number (counting from 1). Or FIELD can be specified with characters that are not decimal numbers (other then 0-9), in which case it is assumed to be a field name, as defined in ${SEDE_ROOT_IN}/c_voters_fieldnames.

With --see (or -s), marks each field `,CONTENT,' with its field number and field name as defined in ${SEDE_ROOT_IN}/c_voters_fieldnames: `,CONTENT(FIELD-NUMBER=FIELD-NAME),'.

With --designate (or -d) marks only FIELD with its field number and name. Giving optional `--extra FIELD2' marks all fields from FIELD to and including FIELD2 with their field number and field name.

--get (or -g): echoes FIELD to standard output.

--cut (or -c): echoes all but FIELD to standard output.

--put (or -p): integrating PUT_FILE and FILE in FIELD in FILE, and echoes the result to standard output. If FIELD does not exist on a line it is created. If FIELD equals 0, then the content of PUT_FILE is not echoed to standard output.

votersfield returns 1 if nothing happened, for instance if the --get field did not exist in the input. If no other error occurred it returns 0. See also `fieldpipe'.

Give the path to COMMAND, or an error message if COMMAND wasn't found.


Most sede commands are scriptable, there are several ways to script sede. Setting ${SEDE_HALT} to `no' causes user-wait/confirm's to be pushed through automatically (see continue).

All variable names starting with `SEDE_' may be used for future expansion.

Ways to execute a script:


Use the sede executable in the path, and call it from a script with suitable arguments. The downside to this is that you cannot alter the variables defined in ~/.sederc and have them in an altered state for the next call to sede.

sede shell FILE
cat FILE | sede [shell]

Using sede shell, the script can be equal to sede shell interactive commands. The commands-file can be piped, or be given as an argument. Since sede starts by default shell, you can run `echo COMMANDS | sede'. FILE has to end on an exit command (exit, bye, or ^D), otherwise after the end, sede shell is waiting for user input. Commands have to be delimited by line breaks.

sede shell --zsh|--bash|--csh|--sh|--ksh FILE
cat FILE | sede shell --zsh|--bash|--csh|--sh|--ksh

Puts sede commands in the search path of a regular shell. The commands file can be piped, or given as the second argument. Where the sede commands are in the ${PATH} is controlled by ${SEDE_SHELL_ORDER}. After the shell starts, sede commands will be using the local environment which has been suitably augmented for sede commands. If the environment set by sede is changed, results change for subsequent commands (see sede_env).

 ./FILE  ## using sede shell [ARGS] `interpreter'

 ./FILE  ## using . sede set.path

Stand-alone sede script. The first possibility is to put:
#!/PATH/sede shell
#!/PATH/sede shell --noprompt
#!/PATH/sede shell --SHELL
on top of your sede script, choose for SHELL one of zsh, bash, csh, sh, or ksh. (Between the first and second argument only one space.)

The second form is to set your shell environment/path with the system command `. sede set.path [ARGUMENT]', somewhere before you want to use sede commands.



~/.sederc file is (almost) always executed before a command, to set the proper environment variables. If these variables already existed in the environment, the value in ~/.sederc is ignored. Configuring a variable using `export SEDE_...=...' in your shell init, rather then in ~/.sederc, can make it easier to upgrade to new ~/.sederc versions (probably plug&play).
Defines the stepping mode for the ^-step ${SEDE_ROOT_IN}/c_template variable, and for sede makes step. It's content should be a step-argument as for makes, or `ignore', in which case ^-step won't start a stepping mode, and makes step defaults to `echounitstep'.
Defines a browser (html viewer) to be used by sede see. You can give arguments to your browser as well, the browser will be started with the given target as the latest argument. If it is already defined in the environment, it can be commented out.
Directory with optional user commands. The commands in this directory are executed in an environment set by ~/.sederc and /etc/sede, and take precedence over standard commands. The settings of ${SEDE_SILENT} and the poll lockfile (${SEDE_ROOT_IN}/call_lock) do not affect execution. Any commands can know if they are executed by sede shell, instead of as an argument to sede, by testing for `SEDE_SHELL_USE=yes'.
See sendmail for the details.

If non-empty, use a different emailing command than the default (mailx, mail). If a user command is supplied, it has access to the to be send ballot through variables in the environment.

${SEDE_EXEC_MAILSEND} has two special contents that behave differently: pointing to an instance of `mutt', or starting with `email ' (`email' + SPACE).

If set to `no', causes all user-waits and/or questions for continuation to be pre-answered with `yes', and don't cause a user-input-wait (${SEDE_ROOT_IN}/c_template debugging is not affected). (See also continue)
The content for the alt="..." portion of the <img ...> tags that point to theme grahpics in ${SEDE_ROOT_VOUT}/${SEDE_INDEX}.
The last part of the name of the link to the browsing directory where all votes are stored under their code. (Don't use spaces or `-'.)
The last part of the name of the compacted results (see ${SEDE_ROOT_IN}/c_compact) in the end results. (Don't use spaces or `-'.)
The content for the link in ${SEDE_ROOT_VOUT}/${SEDE_INDEX}, toward ${SEDE_ROOT_VOUT}/setup.html, or if a graphics theme is being used: the content for the alt="..." option to the <img ...> graphic tag pointing to this file.
Put at the start of ${SEDE_ROOT_VOUT}/setup.html
The content for the link in ${SEDE_ROOT_VOUT}/setup.html, toward ${SEDE_ROOT_VOUT}/${SEDE_INDEX}, or if a graphics theme is being used: the content for the alt="..." option to the <img ...> graphic tag pointing to this file.
The last part of the name of the list of votes which votes multiple times. (Don't use spaces or `-'.)
The last part of the name of the poll-explain-file, the file that the poll titles in ${SEDE_ROOT_VOUT}/${SEDE_INDEX} can link to (files are copy off ${SEDE_ROOT_IN}/c_explainPOLL_NUMBER files).
The last part of the name of the list of false votes. (Don't use spaces or `-'.)
The text to be placed after an empty/non-existing item in the results.
The last part of the name of the codes which did not vote (abstention). (Don't use spaces or `-'.)
The last part of the name of the list of all votes grouped per voter in the end results. (Don't use spaces or `-'.)
The last part of the name of the raw results in the end results. (Don't use spaces or `-'.)
The text to be placed under additions when weighted-voting is active, to highlight if an addition is a simple one vote is one point addition, ignoring the weight element.
The last part of the name of the list of voters for a poll. (Don't use spaces or `-'.)
The last part of the name of the list of votes for a poll. (Don't use spaces or `-'.)
The last part of the name of the voting-patterns (how voters vote accross polls) in the end results. (Don't use spaces or `-'.)
The last part of the name of the weighted compacted (see ${SEDE_ROOT_IN}/c_compact) results in the end results. (Don't use spaces or `-'.)
The last part of the name of the raw weighted results in the end results. (Don't use spaces or `-'.)
Here you can configure the device file for random vote-code strings to be configured. Use `/dev/urandom' for quickness, or `/dev/random' for a higher level of randomness (you may have to give it random keyboard input during ballot creation).
The string that is prefixed to vote which is in abstention (no vote cast by voter), in the per-voter results (see ${SEDE_ROOT_IN}/c_pervoter). After this string comes the poll-name and the vote-code.
A string that is put on an empty line to delimit votes belonging to different polls in the results and the like.
The string that is prefixed to multiple occuring votes for the same vote-code, which are not chosen to be counted, in the per-voter browse directory files (${SEDE_ROOT_VOUT}/POLLNAME-${SEDE_INDEX_BROWSE}/VOTECODES).
The string that is prefixed to the add-up of votes which are in abstention.
The string that is prefixed to the add-up of double vote-codes in the results.
The string that is prefixed to the add-up of false votes in the results.
A string that is present in the results before totals of voters, to mark the total as a total of voters.
A string that is present in the results before totals of votes, to mark the total as a total of votes.
A string that is prefixed to each vote before publishing, if weighted voting is active (see ${SEDE_ROOT_IN}/c_weight). After this string comes the weight of that vote, then a space and then the vote. The string should not contain special sed characters.
Directory with files that define a poll, everything that will be on the ballot, the voters, and how the results will be processed etc, but not an actual instance of this poll (ballots, records etc, all that goes in ${SEDE_ROOT_OUT}).
~/.sederc: SEDE_ROOT_IN="/YOURDIR"

(Warning: do not point this variable - or any variable in the SEDE_ROOT_* group - to data not relating to sede. Sede commands operate on these directories with impunity!)

Directory with files that are generated from files in ${SEDE_ROOT_IN} by running sede makes: ballots, records etc. When this directory is filled by sede makes, the poll is in its second phase, ready to have the actual ballots routed to voters.

(Warning: do not point this variable - or any variable in the SEDE_ROOT_* group - to data not relating to sede. Sede commands operate on these directories with impunity.)

Directory in which files are placed by running sede allsave: a poll archives directory.

(Warning: do not point this variable - or any variable in the SEDE_ROOT_* group - to data not relating to sede. Sede commands operate on these directories with impunity.)

Temporary files, debugging files during stepping mode (see makes), and logfiles (see ^-execute).

(Warning: do not point this variable - or any variable in the SEDE_ROOT_* group - to data not relating to sede. Sede commands operate on these directories with impunity.)

Directory where returned ballots are to be saved (under any filename(s)).

If all ballots are saved in the same file, the command getvotes runs about 10 times quicker than if you store each ballot in a seperate file. A caveat with this is that if a long comment space is chosen, and the voter removes the end marker for a voting area (see ${SEDE_ROOT_IN}/c_find_votearea), characters from the next returned ballot might be swallowed into the voting area.

(Warning: do not point this variable - or any variable in the SEDE_ROOT_* group - to data not relating to sede. Sede commands operate on these directories with impunity.)

Directory where returned ballots with voting-area stripped are placed after running sede processall if ${SEDE_ROOT_IN}/c_mk_readable is set.

(Warning: do not point this variable - or any variable in the SEDE_ROOT_* group - to data not relating to sede. Sede commands operate on these directories with impunity.)

Directory in which files generated by running sede processall are placed. These files are the poll results and would be eligible for publication. It should not be a problem to make this directory world readable/browsable even before results have been processed, that way voters can follow the vote processing as it happens.

(Warning: do not point this variable - or any variable in the SEDE_ROOT_* group - to data not relating to sede. Sede commands operate on these directories with impunity.)

Set the command interpreter shell for commands executed by run. The content of ${SEDE_RUN_SHELL} will be put on the first line of the script-file, on the second line comes the command given to run. ${SEDE_RUN_SHELL} is expanded, SEDE_RUN_SHELL="#!$( which zsh ) --" will result in: "#!/usr/bin/zsh --" for instance.
This variable reflects the sede version (`sede --version-short') that the ~/.sederc file matches with. It is used to detect mismatches between the system version, and a user's ~/.sederc file. See also sede upgrade.
Set if by default sede shell aborts on encountering an error (a non zero return value): `on' or `off' (abort or don't abort). Is set/unset local to a sede shell by `abort-on', `abort-off'.
Defines if the sede shell log will be absolute, that is, record the startup settings for: verbose-[on|off], abort-[on|off], path-[on|off], exec-[on|off], sede-[first|last|never], echo-[on|off], and record the history buffers at startup. Logs are also working command files, they can be re-executed. An absolute log can be re-executed later or elsewhere with the same startup settings in effect. Values can be `on' or `off' (absolute, not-absolute, respectively).
Set if by default sede shell echoes the command it is going to execute: `on' or `off' (echo or don't echo). Is set/unset local to a sede shell by `echo-on', `echo-off'.
If set sede shell does not execute commands: `on' or `off' (execute or don't execute). Is set/unset local to a sede shell by `exec-on', `exec-off'.
Defines if sede shell builtin `echo-on' asks for user confirmation before execution (`on' is user-confirmation, `off' is not).
Starts sede shell as a login shell if set to `on', if set to `off' starts shell without login argument.
Inhibits the startup-message for sede shell if set to `off', sede shell starts with startup message if set to `on'.
Set how sede shell by searches for the "unescaped" commands it gets ("escaped" is with `;', `' or `,'): can be `first': searches first for a matching sede command, or `last': searches last for a matching sede command, or `never': searches never for a matching sede command (see shell). Is set/unset local to a sede shell by `sede-first', `sede-last', `sede-never'.
Set the default for searching for (unescaped) system-commands: `on' or `off' (search the system or not). Is set/unset local to a sede shell by `path-on', `path-off'.
Set the user prompt content for sede shell, some special triggers are recognized (see sede shell built-in p:user and P:), variables within are expanded.

If at startup of sede shell it is empty, the default prompt is used instead (`^ ', which is fast). If it has content, its content is taken to be the "user prompt": expanding `%...' sequences and expanding variables which is relatively slow (see shell, P:PROMPT for the `%...' sequences).

Variable expansion within the ${SEDE_SHELL_PROMPT} variable ($MYVAR, ${MYVAR}, $( MYCOMMAND ), etc), has two possible moments for expansion. The first is at startup of sede shell, this happens when the variable is not escaped, and the right hand side is not between single quotes: SEDE_SHELL_PROMPT="$( date )^%s". This prompt string will reflect the date/time of startup, and never change. The second expansion moment is for each new prompt, this happens when the variable is escaped `\', or the right hand side is between single quotes: SEDE_SHELL_PROMPT="\$( date )^%s", SEDE_SHELL_PROMPT='$( date )^%s'.

Set the default verbosity level of sede shell: `on' or `off' (verbose or not verbose). Is set/unset local to a sede shell by `verbose-on', `verbose-off'.
If this variable is set to yes, standard output for commands is suppressed. When the command has an `are you sure ?' warning, setting ${SEDE_SILENT} to `yes', suppresses this warning.



First line is `yes' or `no'. If it is `yes', then "passive abstentions", vote-codes for which no vote was returned, will be in the generated end-results (see processall) on a list, and in the optional files listing all votes of a voter (see correlate, and ${SEDE_ROOT_IN}/c_pervoter). If it is `no', then vote-codes which have not voted are ignored and are not found in the publishable end-results. This can be used to protect the vote-codes for people who may yet vote later with their ballot, if the vote-codes of "passive abstentions" are published, these vote-codes obviously cannot be used for voting anymore (although see: ^-password, for a potential way around that).
First line is the field-number in the voters-file where the address of the voter is stored. If using the sendmail command, you can put on the 2nd line an email subject for those ballots which had no subject flags expanded for them (see ^f). If not routing a ballot through email, you could put an address or fax or other routing information in the field in ${SEDE_ROOT_IN}/c_voters, defined on the first line here, and use the data to route the (optionally marked, see ${SEDE_ROOT_IN}/c_template, ^f) ballots with your own program.
If the first line consists of `copy', all text outside any variable is copied straight from the ${SEDE_ROOT_IN}/c_template into the ballot (normal behavior). If the first line consists of `ignore', then on the first pass only, all characters outside any variable are ignored. This allows you to indent and comment your ${SEDE_ROOT_IN}/c_template code any way you like, as long as you don't use `^' in comments.
With this file you can condense returned votes that mean ultimately the same thing (according to you), into one result. For instance to count `Yes' and `yes' under one name, because in the raw results they show up as two different results, and are added separately, while they might mean the same thing most often. When this file has `yes' as its first line, compacted results are generated. The raw results are always present regardless of the setting of ${SEDE_ROOT_IN}/c_compact.

The format of this file below its firts line is: on each line, one vote-condensing under a name can be defined, each line is expected to have this form:

POLL_NUMBER,ANSWER_TITLE,PATTERN,PATTERN,PATTERN,... PATTERN will be augmented with `^' before it and `$' behind it automatically. If you want to match an empty vote, try `B'.

POLL_NUMBER is the number of the poll to which this condensing relates to, the number corresponds to the poll name under the same line number in ${SEDE_ROOT_IN}/c_pnames.
ANSWER_TITLE is the title under which the results will be grouped, it can contain spaces (and comma's, see shortly below).
PATTERN,... are an unlimited number of grep -E patterns to which the created raw results are matched. The field separator in this file is the comma in the same way as in the voter registration file: to use a literal comma, write `\,', to write a literal `\', double it, a `\ followed by a non-comma and non slash is left unchanged.

When votes are counted multiple times because they are matched by multiple patterns from different lines, the total doesn't match the raw vote results total anymore, an error message is printed in the compacted results.

${SEDE_ROOT_IN}/c_explainPOLL_NUMBER (optional)
For each poll an ${SEDE_ROOT_IN}/c_explainPOLL_NUMBER can be created containing what the question was for that poll. In the end-results the poll-titles will point to the content of this file (after it has been renamed according to POLL_NAME-${SEDE_INDEX_EXPLAIN}.
When ballots are generated, records of voters and their vote code and password are created for each poll (in ${SEDE_ROOT_OUT}/secret_master_N). The fields in the voters-file (${SEDE_ROOT_IN}/c_voters), that are stored there are defined in ${SEDE_ROOT_IN}/c_fields. Format is a comma seperated list of numbers, starting from first field on the left as 1. This data about voters is available for publication on the voted voters list, when returns are being processed (see ${SEDE_ROOT_IN}/c_voters_list to select fields from the ${SEDE_ROOT_IN}/c_fields selection to end up in the publicated results). If you leave the first line empty, no voter-data will be stored in the records. This means that you won't know (easily) who had which code/password pair. This data can later be scrambled to protect anonimity (when the voter registration is non-anonymous)
This file defines how the voting-areas are to be found between all other data in the returned ballots, therefore you should try to write something that can be successfully and exclusively matched. It contains a voting-area-type name on the first line, and accompanying patterns as defined by that type.
In the below <_2_> stands for the second line in this file, <_3_> for the third line etc, ^-title(n) stands for the question-title found in ${SEDE_ROOT_IN}/c_pnames, ^-votecode(n) stands for either a generic fixed-length code-matching string (generic vote areas), or for actually assigned vote codes only (valid votecodes vote areas). Note: this step in processing the returns isn't meant for hashing out invalid codes, but what the hey, now you can do it here too (though it is slow). Matching is done by giving the pattern to grep(1) -E.
Generic vote code voting areas:
`one', match against:
`pnames', match against:
`genc_pnames', match against:
`pnames_genc', match against:
`spread', first join lines by searching for <_2_>, and deleting newlines up to the occurrence of <_3_>, or the elapsing of ${SEDE_ROOT_IN}/c_trunc_at characters (excluding newlines). The joined lines will be preceded by a newline after been found (everything before <_2_> gets ignored), the patterns (<_2_> and <_3_>) are taken literal, but `?' matches all characters. Then match:
`spread_r', same as `spread', but then match against:
Valid Vote codes:
`valid', match against:
`valid_pnames', match against:
`pnames_valid', match against:
Should contain a pattern or string on its first line, which matches text in the returned ballots just before the vote code. The pattern is cut (using sed(1)) from the voting area after it has been joined on one line. It should leave a line beginning with the vote code (for instance `1a3B5c7D9# comments: ..blablabla...'. The pattern is augmented with `.*' at the beginning, so a literal string without meta characters will do. If weighted voting is requested (see ${SEDE_ROOT_IN}/c_weight), the voting area after been joined on a line, will be prefixed by the string `${SEDE_RESULTS_WEIGHT}N', defining the weight of the vote. Example (for the same voting-area as in the above example (${SEDE_ROOT_IN}/c_findvote)):
would do.
The second line should contain a similar pattern but located just behind the vote code. The pattern is augmented with `.*' at the end, and operates on a line already processed by the pattern on the first line. A single character that doesn't ever occur in the vote code, which is located right behind the vote code would work. Example:
Defines what should be cut (using sed(1)) from the voting-area once it has been collected on a single line (see ${SEDE_ROOT_IN}/c_find_votearea), to end up with the voter input which is the vote itself (something like `yes' or `no' etc). The first line in the file contains what is before the vote, this pattern is augmented with `.*' at the beginning. The second line should match what is behind the vote just leaving the vote, it is augmented with `.*' at the end. The pattern on the first line is removed before the second pattern is applied. If weighted voting is requested (see ${SEDE_ROOT_IN}/c_weight), the voting area after been joined on a line, will be prefixed by the string `${SEDE_RESULTS_WEIGHT}N ', defining the weight of the vote. Example: if a voting-area looks like:
Q1 votecode#1a3B5c7D9# vote: ... Comments: ...
Then for instance ${SEDE_ROOT_IN}/c_findvote's first and second lines could be:
votecode#[A-Za-z0-9_]*# vote:[ \.]
[ \.]Comments:
If you want to read additional comments voters might have included in their returns, setting this file's first line to `yes' will remove from the returns the votes so you may read them without compromising the anonymity of the voters needlessly. The readable returns are placed in ${SEDE_ROOT_VINREAD}, the originals are left unchanged in ${SEDE_ROOT_VIN} (returned ballots are expected to be in a file or files in ${SEDE_ROOT_VIN}).
When sede expands variables in the ${SEDE_ROOT_IN}/c_template, this can result in new yet to expand variables in the result. To expand these you can ask for a second expanding-run over the resulting ballot by writing a single 2 on the first line of this file. To expand-run only once write a 1. To expand-run more than one times, increment the number according to the depth of your maximum nesting (no limit).
You can give all the data in all directories a name on the first line of this file, under which it will be stored as a gzip(1)ped tar(1) archive (plus .tar.gz) in the directory ${SEDE_ROOT_POLLS} (see allsave and unpackpoll).
The first line contains a number which is interpreted as the length of the "passwords" to generate with the ballots (see ^-password).

The password can be used to authenticate something (a voter for instance) after the results have been published, because after the results publication all vote codes become public record.

Note: this can be augmented by a second password which has been agreed upon during voter registration, ideally this password would never pass over an insecure channel (but through snail mail for instance).

${SEDE_ROOT_IN}/c_pervoter decides if processall will generate a browsable directory with vote-code files for each poll, and/or a list of all votes grouped per voter and a `voting patterns' computation (see ${SEDE_ROOT_VOUT}/votingpatterns), or none of these. If the first line contains `no', then none of these is generated. If it contains `yes:all', then all of the above is generated. If the first line contains `yes:list', then the list of votes and voting patterns are generated. If the first line contains `yes:browse', then only browsable directories containing files having the name of vote-codes will be generated. These options can take a modifier (extra option) `:together', only if it is present the votes for the same voter are grouped together: yes:[all|list|browse][:together]'.

The by `yes:browse' generated directory files have the following name: POLLNAME-${SEDE_INDEX_BROWSE}/VOTECODE. With the `:together' modifier, these filenames point to the same file containing all votes for that voter.

Without the `:together' modifier, the file ${SEDE_ROOT_VOUT}/pervoter is alphabetically sorted, to eliminate the information of which votes all belonged to the same voter. With the `:together' modifier, the first first vote for any vote-code found in the ${SEDE_ROOT_VIN}/* files (or file) will be displayed above the other votes for that poll and vote-code. This first vote is the chosen vote which is going to be counted. All other rogue or accidental votes are discarded from the tally, but are still displayed in the per-voter results (below the chosen vote for each vote code), and in the POLLNAME-${SEDE_INDEX_BROWSE}/VOTECODE files (if present).

Contains one question-title per line, for each line a vote-code and password pair per voter is generated during ballot generating (for one ballot).

The poll-names come back into the ballot in most voting areas (see ${SEDE_ROOT_IN}/c_find_votearea, and ^-title(N)), and it comes back on the end-results page and in filenames of result lists.

Some expansions might result in the same text for each voter, therefore it is a waste of time to expand them on all occurrences for all voters. If the first line of this file is `yes', then the ${SEDE_ROOT_IN}/c_template is pre-expanded one time (by default), and the result used as the base ${SEDE_ROOT_IN}/c_template for all voters. You can change the amount of passes over the ballot in this stage by using the overriding ^l(n) variable. If you use preprocessing, you have to protect voter-specific expansions from being expanded too soon (see ^;). When calling makes with `test' the pre-expanded ${SEDE_ROOT_IN}/c_template can be examined at ${SEDE_ROOT_TMP}/c_template.
The ${SEDE_ROOT_IN}/c_template is a file from which all ballots are being generated It may contain anything or nothing. An empty ${SEDE_ROOT_IN}/c_template results in empty ballots. It is something of a cross between a data file and programming code (see below for the "programming language").

Processing the ${SEDE_ROOT_IN}/c_template:

The ${SEDE_ROOT_IN}/c_template is processed into ballots by passing over the ${SEDE_ROOT_IN}/c_template one or multiple times by the `makes' (and/or `addvoter') command. During each pass, encountered variables (see below) are expanded. There are two stages: the optional "pre-processing" stage passes over the ${SEDE_ROOT_IN}/c_template and creates a secundary ${SEDE_ROOT_IN}/c_template. If pre-processing was requested (see ${SEDE_ROOT_IN}/c_preprocess), the secundary ${SEDE_ROOT_IN}/c_template is used for the subsequent voter-specific stage, otherwise the original ${SEDE_ROOT_IN}/c_template is used directly. During the pre-processing stage the "voter data" used is dummy data. By default pre-processing constitutes one pass, but it can be reset by the appropriate ${SEDE_ROOT_IN}/c_template variable (see below).

After the optional pre-processing, the actual ballots are being generated by passing over the ${SEDE_ROOT_IN}/c_template with as "voter data" each line in the voter registration in turn. By default it passes as many times as ${SEDE_ROOT_IN}/c_n_passes defines, but as with pre-processing this can be reset by the appropriate ${SEDE_ROOT_IN}/c_template variable.

If ${SEDE_ROOT_IN}/c_codemode is `ignore', then the first pass made over the original ${SEDE_ROOT_IN}/c_template (as you wrote it) ignores all data outside any variable. If ${SEDE_ROOT_IN}/c_codemode is `copy', then all data outside variables is copied into the next pass (which is normal behaviour for all subsequent passes, regardless of the setting of ${SEDE_ROOT_IN}/c_codemode).

Unusual variables:

Most variables result in text in the ballot, but not all. Some exceptions exist, notably the flags variable: writing to the corresponding flags file for the ballot being generated, and the vote-weight variable, which (ultimately) writes data in ${SEDE_ROOT_OUT}/codespervoter.


All variable names are case insensitive, only the lower case forms are listed.

^-allstep or

^-ballot or

^-break or

^-execute(SYSTEMCOMMAND) or

^-execute[SYSTEMCOMMAND] or
^![SYSTEMCOMMAND] (second form, plus logfile)

^-execute{SYSTEMCOMMAND [[>]FILE]} or
^!{SYSTEMCOMMAND [[>]> FILE]} (third form, no forced re-direction)

^-file(FILE) or

^x[FILE|LINENUMBER] (second form, line number)

^-flag(yourflag) or

^-flag[yourflag] or
^f[yourflag] (second form, plus line break)

^-getenv(VARIABLE) or

^-get_loop or


^-loop(PASS) or

^-mark_at(PASS) or

^-mark_at[PASS] or
^:[PASS] (second form, count-up)

^-mark_end or

^-mark_now or

^-password(POLL_NUMBER) or

^-password<POLL_NUMBER> or
^p<POLL_NUMBER> (second form, less ambiguous)

^-password[POLL_NUMBER] or
^p[POLL_NUMBER] (third form, optical machine)

^-print"TEXT" or

^-print'TEXT' or
^.'TEXT' (second form, different delimiters)

^-question(FILE1|FILE2) or

^q[HEADFILE|OPTIONSFILE] (second form, multiple options)


^-step or

^-title(POLL_NUMBER) or

^-votecode(POLL_NUMBER) or

^-votecode<POLL_NUMBER> or
^c<POLL_NUMBER> (second form, less ambiguous)

^-votecode[POLL_NUMBER] or
^c[POLL_NUMBER] (third form, optical machine)

^-voter(FIELD_NUMBER) or

^-voter[NAME] or
^v[NAME] (second form, voter field names)


Template variables details:

^-allstep or ^a
(debugging) Same as `^-step', but puts `^-allstep' back into the output stream (next pass), so it is encountered again on the next pass. This variable will be present in the end-ballot, but can be usefull to more easily track the progress of a piece of code from pass to pass (you'll have to remove it for the final ballot generation).
^-ballot or ^#
Prints the serial number of the current ballot, which is the same as the line number the current voter occupies in the voters-file (${SEDE_ROOT_IN}/c_voters).
^-break or ^b
Print a line break.
Runs SYSTEMCOMMAND, and puts the standard output of the command into the ballot excluding the trailing newline (if any). The variables defined in ~/.sederc and /etc/sede are available on the command line. SYSTEMCOMMAND is written to a file, this file is executed and its output is redirected. To use `)'in SYSTEMCOMMAND escape it `\)'. To use a `\' just before the argument closing `)', escape it `\\)'. If `\' is not in just before the closing `)', it should not be escaped. Examples:
^!(date) get the date
^!(who|wc -l) the number of users on the system
^!(${SEDE_ROOT_IN}/X/script) call `script', a file under the input directory.
^^!(dc -e "^v(3) 15 + p") get voter field 3 and add 15 to it (requires 2 passes, see ${SEDE_ROOT_IN}/c_n_passes and ^l(n)).
Runs SYSTEMCOMMAND (a shell command), and puts the standard output of the command into the ballot excluding the trailing newline (if any). Appends output of the command to a logfile: ${SEDE_ROOT_TMP}/execlog (with ballot number and return-value). The same escaping rules as for ^!(SYSTEMCOMMAND) apply, but with `\]'.
Runs SYSTEMCOMMAND (a shell command). The same escaping rules as for ^!(SYSTEMCOMMAND) apply, but with `\}'.
^-file(FILE) or ^x(FILE)
Prints the content of FILE up to end-of-file excluding the final newline. FILE must be under the input-directory, but can contain subdirectories. Example: ^x(X/info.txt)
Prints only line LINE_NUMBER of FILE. FILE must be under the input-directory, but can contain subdirectories. When |LINE_NUMBER is ommited, the first line is assumed.
Example: ^x[dirx/info.txt|5] prints the 5th line of ${SEDE_ROOT_IN}/dirx/info.txt.
^-flag(yourflag) or ^f(yourflag)
This variable puts nothing into the ballot, but puts the text between the two braces into the corresponding ${SEDE_ROOT_OUT}/flags_N file of the ballot. There are some standard flags you can use, see sendmail. You can access the flags file with your own software to do whatever. A facility is provided if you want to use your own emailing script with which you can access the flags_N file easily (see ${SEDE_EXEC_MAILSEND}). The last line of ${SEDE_ROOT_OUT}/flags_N is reserved for an address flag (see ${SEDE_ROOT_OUT}/flags_N, and sendmail). All standard flags begin with `sede_'.
^-flag[yourflag] or ^f[yourflag]
Same as ^f(yourflag), but gives an additional line-break (newline) after `yourflag' in the ballot flag files.
^-getenv(VARIABLE) or ^e(VARIABLE)
Expands into the content of environment variable `VARIABLE'.
^-get_loop or ^g
Expands into the current number of passes over the ballot still to go, counting down to 0, the final run. This variable is just here as a convenience for debugging your ${SEDE_ROOT_IN}/c_template.
If-then-else structure. Evaluates if TEXT1 (between the first ?...?) matches the text TEXT2 (between the second ?...?). If there is a match the structure results in MATCH (third ?...? part), if no match it results in NO_MATCH (fourth ?...?).

If you want to use a literal `?', escape it with `\', if you want to use a literal `\': double it (single `\' without trailing `?' is treated as a normal character). The maximum length that can be tested is 100 characters.
Example: ^^?male?^v(10)?Mister?Lady?
Example: ^^?^!(date +%w)?6?today free\???
Example: ^^?^v(25)?henry.*template.*?^x(henry/template)??

^-loop(n) or ^l(n)
Set the number of passes to a new value, setting it to 0 means the current pass is the final pass. This can cause an infinite loop. You can detect a loop by seeing the program hang and no ballots appearing in ${SEDE_ROOT_OUT}, and/or having the ballot generating command being killed by the underlying systems (Linux seems to do this because of rapid repeated file accesses iirc, and correctly interpreting this as a run-away loop). Note that using this variable can affect ^-mark_at.
Example: ^l(4): set current countdown to 4.
Example: ^l(0): make this the final pass.
^-mark_at(PASS) or ^:(PASS)
Expands to a literal ^ if the current pass number (countdown to zero, see ^g, ^l(PASS) and ${SEDE_ROOT_IN}/c_n_passes) is equal or less than PASS. Until a matching pass is executing, it remains a ^:(PASS) variable inside the template-ballot ${SEDE_ROOT_IN}/c_template. If the command is processed before the PASSth pass, the short form is put back into the output-stream for later examination on later passes.
Example: ^:(1), expands to ^ on the before-last pass.
^-mark_at[PASS] or ^:[PASS]
Almost the same as ^-mark_at(PASS), only PASS doesn't represent the pass countdown number, but a number to be substracted from the original number of passes (defined in ${SEDE_ROOT_IN}/c_n_passes). When the current pass (countdown to and including 0) has a lower or the same value as that substraction, a ^ results. Simply put: PASS is a count-up from the first pass: ^-mark_at[0] and ^^ are equivalents, both will result in ^ on the first pass. ^-mark_at[1] and ^^^^ are also the same, resulting in ^ on the second pass.
^-mark_end or ^;
Prints one literal `^', but only on the final pass over the ${SEDE_ROOT_IN}/c_template for the current voter, until that pass it remains an unexpanded `^;' variable. When pre-expanding, on the final-pass during pre-expansion (see ${SEDE_ROOT_IN}/c_preprocess) it will be expanded (into ^).

Note that if you use the ^l(n) variable with n = 0, you can change the ballot to its final expansion in the middle of ballot expansion, and this would start expanding `^;' from that point onward, but not above it (if sede was not yet on the final pass).

If the variable is found before the latest pass, the short form is put back into the output-stream for later examination.

Example: ^-mark_end-question(questionA|optionsA)
If preprocessing 1 pass, postpones expansion of ^-question until after pre-processing.

^-mark_now or ^^
Prints one literal `^', expands on every pass over the ${SEDE_ROOT_IN}/c_template. This can be used to nest variables and have them use each other in some specific order.
^-password(POLL_NUMBER) or ^p(POLL_NUMBER)
Prints the password for poll POLL_NUMBER for the current voter, corresponding with line POLL_NUMBER in the poll-titles file (${SEDE_ROOT_IN}/c_pnames). Example: ^p(5) Note: passwords are not (yet) created uniquely, two or more passwords can be the same.
^-password<POLL_NUMBER> or ^p<POLL_NUMBER>
Same as ^p(POLL_NUMBER), but in a format which is less ambiguous for human readers. Example: ^p<5>
^-password[POLL_NUMBER] or ^p[POLL_NUMBER]
Same as ^p(POLL_NUMBER), in a format which can be read by primitive optical/mechanical machinery if setup accordingly (series of dots on certain distances). Example: ^p[5]
Prints the title of poll POLL_NUMBER, which is stored on line POLL_NUMBER in the poll-titles-file ${SEDE_ROOT_IN}/c_pnames. Poll numbers are for internal use by the program and can be used for ballot programming, eventually the poll-numbers are not in the end results and don't need to be on the ballot. Example: ^t(5)
^-question(FILE1|FILE2) or ^q(FILE1|FILE2)
Prints the text in FILE1 per ballot randomly to the left or right of the text in FILE2. Text in both files should therefore be a rectangle of the same number of lines and characters per line. FILE1 and FILE2 must be under the input-directory ${SEDE_ROOT_IN}, they can contain subdirectories.
Example: ^q(choice_a|choice_b). The content of the files is considered up to end-of-file or `#', if you want to write a literal `#', escape it with `\', if you want to write a `\', double it (single `\' not followed by `#' or `\' is treated as normal characters).
Prints the text in HEADFILE up to end-of-file or `#', then prints (below it) sections of OPTIONSFILE in a random order per ballot. Sections in OPTIONSFILE end on `#'. Text between section-ending `#', and the next newline is ignored. The file is considered up to `##' or end-of-file. If you want to use a literal `#', escape it with `\', if you want to write a `\', double it (a `\' without trailing `#' or `\' is treated as a normal character). FILE1 and FILE2 are expected under the input-directory, they can contain subdirectories.

Example options file:
# this is ignored

^-roguecode or ^r
This prints a string which looks exactly like a vote-code, but isn't. Every time this variable is called, it gives another fresh `rogue' vote-code. These pretend "vote codes" are not stored anywhere, they are merely generated in the same way as the real vote-codes, and therefore look exactly the same.
^-step or ^s
(debugging) Start the stepping-mode defined in ${SEDE_BALLOTS_STEPMODE}. If ${SEDE_BALLOTS_STEPMODE} is `ignore', doesn't start a stepping mode (see `makes' for the meaning of stepping modes). If ${SEDE_BALLOTS_STEPMODE} is of zero-length or unset, follows a step argument from the command line (for `makes': `passstep'/`echounitstep' for instance), if no such argument was given defaults to `echounitstep'.
^-print"TEXT" or ^."TEXT"
Print TEXT, everything including linebreaks (see ${SEDE_ROOT_IN}/c_codemode).
^-print'TEXT' or ^.'TEXT'
Print TEXT, everything including linebreaks.
^-votecode(POLL_NUMBER) or ^c(POLL_NUMBER)
Prints the vote code for poll POLL_NUMBER for the current voter, corresponding with line POLL_NUMBER in the poll-titles file (${SEDE_ROOT_IN}/c_pnames). Example: ^c(5)
^-votecode<POLL_NUMBER> or ^c<POLL_NUMBER>
Same as ^c(POLL_NUMBER), but in a format which is less ambiguous for human readers (but cannot be processed automatically as vote code). Each character in the votecode is surrounded by its two surrounding characters in the alphabet or numerical value, preceded by a character which varies for upper-case characters (:), lower-case characters (.), numbers (+, and the underscore (*). Example: ^c<5>
^-votecode[POLL_NUMBER] or ^c[POLL_NUMBER]
Same as ^c(POLL_NUMBER), in a format which can be read by simple optical/mechanical machinery if setup accordingly (series of dots on certain distances). Just as the human-enhanced-readable format, cannot be processed by sede without back-translation into alphanumerical code. Example: ^c[5]
Field FIELD_NUMBER for the current voter on its voters-file line, FIELD_NUMBER is the field number counting from 1, left to right (see ${SEDE_ROOT_IN}/c_voters). Example: ^v(5)
^-voter[NAME] or ^v[NAME]
Field of the current voter on its voters-file line, NAME is a string found in ${SEDE_ROOT_IN}/c_voters_fieldnames (see ${SEDE_ROOT_IN}/c_voters and ${SEDE_ROOT_IN}/c_voters_fieldnames). Example: ^v[preferences]
Changes the weight of the vote for the current voter for question POLL_NUMBER (for poll-name as defined by line POLL_NUMBER in ${SEDE_ROOT_IN}/c_pnames) to WEIGHT. Repeat occurances of this variable with the same POLL_NUMBER value are ignored, only the first one is valid. The results of the variable during pre-processing are ignored. Usually WEIGHT would be a number (later processed by dc(1)), it defaults to 1. Using variable-nesting, each voter can be given a different weight.
Example: ^w(5|18), for poll 5 (poll title ^t(5)), the voter who gets the variable expanded like this on his/her ballot, gets 18 votes instead of the default 1.
Example: ^w(1|.5), for poll 1 (poll title ^t(1)), the voter gets just a half vote.
Example: ^:(1)w(1|^:(2)V(9)), the weight for each voter for poll 1 is contained in the 9th voter registration field for each voter.
Defines the appearance of ${SEDE_ROOT_VOUT}/${SEDE_INDEX} and ${SEDE_ROOT_VOUT}/setup.html. On it's first line is expected a theme icons archive filename (variables are expanded first). On its second line a complete <body ...> tag. On its third line the HTML title but without the <title> </title> tags (variables are expanded first; the title `default-title' causes a default title to be generated). On the fourth and fifth line: HTML content (tags) that will be put before and after the pollname, respectively. On the sixth line HTML content (tags) that will be put between poll items, and their graphic (if any).

See givename for more explicit information.

A vote, votecode and comment are combined on single lines per poll per voter (see ${SEDE_ROOT_IN}/c_template, spread* voting area types), right after the voting-area's have been found in the returns. ${SEDE_ROOT_IN}/c_trunc_at defines on its first line as an integer, a maximum length beyond which the rest of this voting-area-line is removed (basically to enforce a maximum comment-length on each vote).

When you allow (large) comment spaces, it becomes possible for one vote-area to `eat' the next vote-area if the voter has removed the ending tag in case of multi-lined voting-area's (see ${SEDE_ROOT_IN}/c_template, spread* voting area types). You can defend against this to either save every vote to its own file in ${SEDE_ROOT_VIN}/, or have some kind of buffer between ballots: a block of text (for instance mail-headers), the vote-ending tag, a block spaces, etc. Ofcourse you could place a vote-ending tag in the leading text of the ballot above all vote-areas, if a voter doesn't remove this defence he is save from ballot-eating from another voter if all votes are saved into the same file.

Vote codes must be unique between voters per poll, but by writing `all' on the first line of this file, all vote codes are uniquely created. `perpoll' causes vote codes to only be unique for the polling they belong to.

By writing `case_insensitive' on the second line, all codes are created in such a way that they are unique regardless of their (upper/lower) case for their alphabetic component. `case_sensitive' causes upper and lower case to be regarded as different during ballot generating.

Neither do alter the way the vote codes are processed, or which voter codes can occur. It is meant to not run into trouble on (file-) systems or web servers (or whatever), which use case insensitive filenames, should the vote code be used as a filename (see ${SEDE_ROOT_IN}/c_pervoter). The World Wide Web features case sensitive filenames, though.

This file has on its first line the version of sede it works with: sede --version-short.
This file defines how long the vote code is going to be. On the first line alone is to be written the number of characters that this code should be long.
Contains data about your voters: one voter per line, using fields separated by comma's. There is no limit on the number of fields per voter. The first field will be used as a postfix to the generated ballot-file for that voter (maximum length: 100 characters). If you want to use a literal comma, escape it: `\,', if you want to use `\', double it (`\' alone and not followed by `,' is treated as a normal character). Fields can be given names of convenience, see ${SEDE_ROOT_IN}/c_voters_fieldnames.

The data in this file is used throughout SEDE, it is at the core of running polls/referenda. It is used to identify your voters, for which you can then proceed to write a template ballot (${SEDE_ROOT_IN}/c_template). It is used to find addressing data (e-mail addresses for instance) for the ballots, for encrypting and decrypting commands (or other commands operating on ballots) if you want to (see runfield). You can call fields into the ballot (see ^-voter), even modify the ballot using the if-then structure switching on the content of fields, see ^-ifelse?. You can store in it anything you wish to remember about your voters.

The line-number a voter is registered on is known as its voter number or serial number, but after ballot creation you can choose to randomize the line positions, to erase that link between voters and polls: ballots will be stored under names containing this serial number for instance (see randomvoters).

As a security improvement, you might want to register voters under some kind of alias (number) in this file, and keep the alias-voter correlation file in a different location. Notice that ${SEDE_ROOT_IN}/c_voters is part of poll archives, and would be duplicated many times in the process of storing polls in archives (see allsave).

${SEDE_ROOT_IN}/c_voters_fieldnames (optional)
Defines identifiers for fields in the voters registration file. The file is expected to contain a comma delimited list of names just like a line in the voters registration file ${SEDE_ROOT_IN}/c_voters, but you cannot escape comma's to avoid their field seperating powers.
If ${SEDE_ROOT_IN}/c_voters_fieldnames looks like: `blabla,what-ever,test,something', then ^-voter[test] is the same as ^-voter(3).

Using field-names that consist of only decimal digits (,,,8,77,007,,,) makes it impossible to use that name with `sede votersfield'.

If the first line is `yes', then a list of voting-voters will be in the processall results, if its not then this list is excluded. If the total number of voters of a voting (or subgroup voting) is known and can be independantly verified by all voters, it is not necesary for unmanipulatability, to publish a list of actual voters, because all vote codes will be accounted for in the results and the number must simply be the exact same as the total of voters. This uses the possibility that non-voting voters may check that their code hasn't voted, but for this they have to receive their votecode regardless of their interest in the vote.

The second line contains which fields from the ${SEDE_ROOT_OUT}/secret_master_N files (excluding the stored vote codes and passwords) are to be present in the voted voters list in the end results (in ${SEDE_ROOT_VOUT}). The chosen fields are expected as a range, written delimited by a `-': FIELDSTART-FIELDEND. The fields (defined like they are defined in the voters registration file) are numbered most left 1 and counting to the right, restarting this count on each new line. For instance: 3-5 means that fields 3, 4 and 5 in all ${SEDE_ROOT_OUT}/secret_master_N files will be in the end results. It is impossible to select the vote code or password present in ${SEDE_ROOT_OUT}/secret_master_N.

If the first line of this file is `yes', then all votes are preceded by their weight after they have been found in returned ballots. This weight is as defined during ballot generation (see ${SEDE_ROOT_IN}/c_template -> ^w(n|WEIGHT)). A secondary add-up of the vote is created besides the straight results, giving the add-up of the vote with potentially different weight's per vote than 1 (fractions are also possible).


Running `sede makes' results in these files in ${SEDE_ROOT_OUT}:
The files code_record_M are the same as secret_master_N but without the voter registration data. M stands for the poll number.
This file lists the vote codes for each voter, which was called into the ballot, or for which the password was called into the ballot. This file is later used to compute which votes were from the same voter.

It has the vote-codes for each voter on the same line. The line consists of a comma-delimited list of vote-code definitions. A vote-code definition in codespervoter has this format: `POLL-NUMBER:VOTE-CODE;WEIGHT,'. The poll numbers increase to the end of the line. If a voter does not participate in a vote, that definition is absent.

Contains user flags for the ballot (see ^f(flag)), and the routing address of ballot N (${SEDE_ROOT_OUT}/out_N_ballot*) on its last line. Flags used by sede:
* Used by makes and secondary:
* Used by putaddress (see also ${SEDE_ROOT_IN}/c_address):
* Used by sendmail:

Flags beginning with `sede_' are reserved for future expansions of sede.

The ballots are called `${SEDE_ROOT_OUT}/out_N_ballot*'. N stands for the line in the voters registration file the ballot was generated for (serial number), * is the content of the 1th field on the voter's line in ${SEDE_ROOT_IN}/c_voters.
The files secret_master_M are records of selected voter fields (see ${SEDE_ROOT_IN}/c_fields) and their vote codes and passwords (see ^c(n), ^p(n)). M in the filename stands for the question number, these records are created per poll in one secret_master_N file. Each line describes one voter.



After saving the returned ballots in ${SEDE_ROOT_VIN}, and running `processall', several (types of) output files will result:
This file is a HTML page which links to the other resulting files in a simple way, meant for the voters to see first. It displays the results of the returned ballots processing by linking to the result lists. See givename for more details.
Files which have valid vote codes as their filename, containing all votes of that voter (not only the vote for POLLNAME). The directory in which they are placed is called "browseN" before renaming by givename.
Contains the compacted tally (see ${SEDE_ROOT_IN}/c_compact). Called "compactN" before renaming by givename.
Contains vote codes which were returned with more than one unique voting-area for POLLNAME, prepended with how many times they were returned. Called "doublevotesN" before renaming by givename.
To this file (if it exists) is linked to from the relevant poll title in ${SEDE_ROOT_VOUT}/${SEDE_INDEX}. You can use this for instance to let this file contain the question, so that users can click on the question-title and refresh their memory about what this particular vote was about. Called "${SEDE_ROOT_IN}/c_explainN" before renaming by givename.
Contains voting-areas which were returned with non-existing vote codes for POLLNAME. Called "invalid_votesN" before renaming by givename.
Contains the codes that haven't returned their voting-area for POLLNAME. Called "notvotedcodesN" before renaming by givename.
This file groups votes per voter, all votes for all polls in one file. Called "pervoter" before renaming by givename.
Tally of the vote for POLLNAME. Called "resultN" before renaming by givename.
Contains the voters that did validly vote on POLLNAME, data taken from ${SEDE_ROOT_OUT}/secret_master_M, and therefore defined by ${SEDE_ROOT_IN}/c_fields. Called "votersN" before renaming by givename.
Contains the valid voting-areas for POLLNAME: vote code, vote and comment (one per line). Called "votesN" before renaming by givename.
Tally of voting patterns. A voting-pattern is what a single voter voted on all polls. Called "votingpatterns" before renaming by givename.
Contains the compacted tally of the weighted results (see ${SEDE_ROOT_IN}/c_compact). Called "weighted_compactN" before renaming by givename.
Weighted tally of the vote for POLLNAME (see ${SEDE_ROOT_IN}/c_weight and ^-weight(POLL|WEIGHT)). Called "weighted_resultN" before renaming by givename.


Contains the sede shell history buffers (see shell).
System wide configuration file:

This variable points to the location of the sede library directory, which contain commands that can be called through the shell-wrapper (sede), and some other things in ${SEDE_LIB}/extras/.

This variable holds the current version number. See also `sede upgrade'.

${SEDE_ENVIRONMENT_SET} This variable signals that the sede environment has been set. Sede library commands abort if it doesn't have the correct magic content: `Sre9:D8pkeM'. This is a safeguard. Running sede commands outside a proper sede environment may result in the recursive deleting of all files in your home directory. (See also the ${SEDE_ROOT_*} group of variables.)

If this variable has the value "no", then new users who are using `sede checkout` to install their initial installation, which is required to using most sede commands, are not asked to interactively approve of the license and no-warranty situation for the program. If it is anything but "no", they'll be asked to agree before user defaults are installed. This variable is not present in the environment as most are.

The $PATH programs sede needs. The latest part of the variable name after the latest underscore `_', contains the name under which the service is normally known. The exception is: ${SEDE_X_ZIP_EXT}, it contains the extension the in ${SEDE_X_ZIP} defined program uses, for instance ".gz" for gzip.

Sede commands written in shell-language (almost) never directly access system programs (system commands like ls, cat, chmod), but go through the above variables to find the needed service. This abstraction gives the system administrator the power to use a different program for the wider system, but point /etc/sede to a version that works with sede if there is a mismatch between system and sede needs.

Example: suppose the version of dc on a system has a different output format then where sede is developed for. Hence sede won't work properly. Installing a version of dc that does work, in some directory (doesn't have to be in the $path ofcourse) and pointing SEDE_X_DC=/usr/local/somedir/somewhere/dc should cause that version to be used instead, while not affecting the whole system.



The environment is defined in ~/.sederc and /etc/sede, and exported by sede; but if a variable was already set to a non empty content, the variable is not reset. Below are the variables that have not been explained already under ~/.sederc or /etc/sede. The variables contained in those files are also put into the environment.
If this variable has a non-zero length, the content is taken to be the filename of an alternative ~/.sederc, causing sede to ignore ~/.sederc and use that file instead.
This variable is put in the environment containing `yes' when running sede shell. This variable is unset by sede, and set by sede shell.


Commands return `false` (1) on error, 30 if ${SEDE_ENVIRONMENT_SET} was unequal to its magic string, or the return value of the final command it executed. The ballots command (which generates ballots for makes) has more return values. makes will report these return values if non-zero. Some commands may also produce other return values (notably continue), see documentation there.

ballots return values:

Successful run.
Tricky format warning occurred, an unrecognized variable was encountered (non fatal).
Only during stepping: a pass over the ${SEDE_ROOT_IN}/c_template did not change anything (non fatal).
Only during stepping: both the condition for exit value 1 and 2 are met (non fatal).
Usage error (abort).
User pre-abort, existing lockfile ${SEDE_ROOT_IN}/call_lock (abort).
File opening failed (abort). When in a run-away loop (the ${SEDE_ROOT_IN}/c_template can be programmed into an infinite loop using ^-loop(n)), the operating system might prevent a file-opening on an otherwise correct file, after a number of quick open/close itterations.
First field in ${SEDE_ROOT_IN}/c_voters contained too many characters (abort).
An output filename was too long (abort).
Filename for ^q (see ${SEDE_ROOT_IN}/c_template) was too long (abort).
Dynamic memory allocation failed (abort).
Error in if-then structure in ${SEDE_ROOT_IN}/c_template (abort).
A call for a poll-name in ${SEDE_ROOT_IN}/c_pnames, or a call to a vote code (^c), or password (^p) had an out-of-bounds poll number (${SEDE_ROOT_IN}/c_pnames line number doesn't exist) (abort).
Closing file failed (abort).
Too long number in numerical part of vote code (^c), password (^p), poll-title (^t), change-passes (^l), put-^ (^:), weight (^w), file-line (^x[), voterfield (^v), or ${SEDE_ROOT_IN}/c_fields call (abort).
Non-numerical character in numerical part of vote code (^c), password (^p), poll-title (^t), change-passes (^l), put-^ (^:), weight (^w), file-line (^x[), voterfield (^v), or ${SEDE_ROOT_IN}/c_fields, -call (abort).
Environment not adequately set (abort).
Input filename too long (abort).
Execution string read from ${SEDE_ROOT_IN}/c_template too long (abort).
Too high or too low poll-number for weight-change call ^w(POLL_NUMBER|WEIGHT) (fatal).
Too long weight string in weight-change call ^w(POLL_NUMBER|WEIGHT) (fatal).
Opening character for calls which use ( ), < > or [ ] to delimit their input, was not recognized for the call it was used for (fatal).
Buffer overflow when creating a system command to grep flags from the flag_N files.
Template variable ^-voter[NAME] encountered, but ${SEDE_ROOT_IN}/c_voters_fieldnames doesn't exist (fatal).
A field in ${SEDE_ROOT_IN}/c_voters_fieldnames was too long for assigned space (fatal).
Template variable ^-voter[NAME]: NAME doesn't exist in ${SEDE_ROOT_IN}/c_voters_fieldnames (fatal).
Buffer overflow for reading environment variable name (^-getenv(NAME)).
Environment variable not found for ^-getenv(NAME) call.
Too high poll-number present in flag `sede_codes;POLLNUMBER;VCODE,PASSWD', higher then present in ${SEDE_ROOT_IN}/pnames.
Too long or too short votecode or password in flags file in flag `sede_codes;POLLNUMBER;VCODE,PASSWD', longer/shorter then present in ${SEDE_ROOT_IN}/c_votecode or ${SEDE_ROOT_IN}/c_passwd .
${SEDE_ENVIRONMENT_SET} did not contain its magic string, or was not found in the environment.


Email to:
<> or
Website: or  




Some commands use the shell wildcard `*' to match against a lot of files, but this can overflow; corrective action is being taken but not yet completed.

"sede shell" When giving a command containing a double quoted newline `\\n', the command is incorrectly absorbed by the history buffers and log file.

"sede shell --SHELL" is dodgy. Sometimes the PATH of the original environment isn't copied by the new shell process, causing sede commands to not be in the path. Users may want to use "% . sede set.path" instead, which accomplishes the same as "sede shell --SHELL".  


Sede is released under the terms of the Free Software Foundation's `General Public Licence' (GPL) version 2, or (at your option) any later version. This License is Copyrighted by Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

See `sede show [c|w]', or the file `Licence' in the source package for the complete text.



PVote, GNU.FREE, Recount



Table Of Contents
COMMANDS (simple arguments)
COMMANDS in alphabetic order:

This document was created by man2html, using the manual pages.
Time: 06:51:30 GMT, June 16, 2007