Citation Master

From TNG_Wiki
Jump to navigation Jump to search
Citation Master
Summary Customize the format and content of citations (individual pages) and sources (browsing page).
Validation
Mod Updated 22 Dec 2017
Download link v11.1.2.7
TNG 11.1.2

v11.1.0.7
TNG 11.1

v11.0.0.7
TNG 11.0

v10.1.0.7
TNG 10.1.0

v10.1.0.3a *
TNG 10.1.0

v10.0.2.7 **
TNG 10.0.2

v9.2.2.3
TNG 9.2.2

Download stats
Author(s) Bill Herndon
Homepage Citation Master
Mod Support Citation Master support.
Contact Developer Email me.
Latest Mod v11.1.2.7 for TNG 11.1.2
v11.1.0.7 for TNG 11.1.0+
v11.0.0.7 for TNG 11.0.0+
v10.1.0.7 for TNG 10.1.0+
v10.1.0.3a for TNG 10.1.0 and 10.1.1 with Responsive Tables
v10.0.2.7 for TNG 10.0.2+
v9.2.2.3 for TNG 9.2.2+
Min TNG V 9.2.2
Max TNG V 11.1.2
Files modified
admin_editsource.php
admin_mergesources.php
admin_newsource.php
admin_sources.php
browsesources.php
languages/English/sources_help.php
personlib.php
rpt_fam.php
rpt_ind.php
showsource.php
Related Mods
Notes
** No testing has been performed against TNGs 10.0.0 or 10.0.1, but it's likely that version 10.0.2.7 is compatible.


Purpose

Have you ever wanted to to display your citations and sources in a bibliographic format--something more in line with contemporary publishing standards? Do you have lots of custom source tags or do you use source tags that aren't supported directly in the tng_sources table (...and consequently don't get displayed)? Then Citation Master can help by allowing you to define the format and content of citations.

Developer

Bill Herndon

Requirements

  • A working TNG installation (9.2.2 - 11.1.1)
  • An installed current version of the Mod Manager

Features

Citations and Sources

Citation Master supports changing the format and typeface of source fields, the punctuation that surrounds a source field, and the separator that follows a source field. Text can be prepended or appended to source fields, and dates can be formatted. Using these features, TNG users can build source and citation styles based on common standards such as the Chicago Manual of Style (CMoS), IEEE, or American Psychological Association (APA) style. In fact, these styles are included in the standard installation and can be used 'out-of-the-box'. Users can also create sets of formatting instructions and then assign these to source types, so that citation/source formatting changes based on the type of the source (e.g., "Book" vs. "Census"). These changes are supported by a formatting engine that reads a configuration file of formatting instructions and source specifications.

Page References

For pages generated by getperson.php, a page reference suitable for copying to other genealogy websites can be generated. For this feature, the source formatting engine uses standard information about the page such as the individual's name, the site name, the site author, and the current date to create the reference. APA, IEEE, and CMoS formats for this reference are included in 'out-of-the-box'. Users can also supply their own reference styles by modifying the formatting instructions in a Citation Master configuration file.

Internationalization

Citation Master currently supports Czech, Danish, Dutch, English, French, German, Italian, Norwegian, Polish, Brazilian Portuguese, Spanish, and Swedish. Additional languages can be supported by adding the required entries to the reelevant cust_text.php files.

Administration

Citation Master adds an additional Format tab to the administrator page for sources. Administrator users can create, delete, edit load, and save Citation Master configuration files using this interface.

Examples

Sources

The following is an example from the source browsing page on Lindell-Herndon Genealogy:
(The format approximates the IEEE citation style):

Example-sources.png

Citations

This image depicts citations on a individual's page:

Example-citations.png

References

This image depicts the format for a page reference.

Example-reference.png

Admin Interface

The admin interface is available on the Format tab of the Admin Sources page:

Example-admin.jpg

Installation

  • Download the .zip file to your mods directory and unpack it.
  • Install the mod using the Mod Manager.
  • Set the active Citation Master configuration file using the Mod Manager's parameter feature.

Upgrading

General Instructions

  • Disable the mod using the Mod Manager.
  • If you've customized one of the Citation Master configuration files, back it up by saving it under a different filename or moving it out of the mods directory.
  • Install the new version of the mod.
  • Restore any copies of modified configuration files.
  • Enable the mod using the Mod Manager.
  • Use the Mod Manager's parameter feature to set the active configuration file.

Upgrading to 10.0.2.4 or 10.1.0.4

This release makes some changes to Citation Master configuration files that are not backwards compatible. If you're using a pre-10.X.Y.4 config file, you'll need to edit that file and replace each instance of egenea_source_fmt with citem_format_spec.

Formatting Source Fields

Sources, citations, and references are formatted by applying Typefaces, Surrounds, Separators, and Formats to TNG source fields represented by GEDCOM tags. In addition, text can be prepended or appended to the data of a source field.

Typefaces

4 typefaces are supported.

Typeface Version(s)
plain
bold
italic
uline (i.e., underline)
v1 - v8

Multiple typefaces are supported to get the effect of combinations such as bold-italic. See the examples for information on how to create formatting instructions that specify multiple typefaces.

Surrounds

7 types of surrounding punctuation are supported.

Surround Version(s)
singles (i.e., single quotes)
doubles (i.e., double quotes)
v8
parens (i.e., parenthesis)
quotes
brackets (i.e., square brackets)
braces (i.e., curly braces)
angles (i.e., angle brackets)
v1 - v8

quotes is supported for backwards compatibility. singles and doubles are preferred to disambiguate between single quotes and double quotes.

Separators

7 separators are supported.

Separators Version(s)
space
comma
colon
period
semi (i.e., semi-colon)
dash
v1 - v8
break (i.e., HTML <br/>) v8

A single space is appended to most separators, with the exception of space itself and break. This ensures that double spaces aren't inserted by the formatting engine and that a space doesn't appear on the first line after an HTML break.

Multiple separators are supported so that HTML line-breaks can follow punctuation such as a comma or period. See the examples for information on how to specify combinations of separators.

Formats

Source date fields can be formatted by using the standard PHP notation defined here. For example the string "F j, Y" instructs Citation Master to format a date field in the form: "January 1, 2017".

Format Version(s)
format v7 - v8

Prepend and Append

Text can be prepended or appended to the data of a source field.

Version
prepend
append
v8

How Citation Master Works

To format the fields that make up a source or citation, Citation Master uses a rendering engine that reads a configuration file containing Format Instruction Sets and Source Specifications. The former are lists of formatting instructions associated with GEDCOM tags that representing source fields. Any source/citation field natively supported by TNG, in addition to any custom event types associated with the source/citation can be formatted in this fashion.

Format Instruction Sets

PHP arrays are used to associate GEDCOM tags with format instructions. A typical set of instructions for a group of source fields might look like the following:

 $book_format_inst = array(
   'AUTH' => array(
     'typeface' => 'plain',
     'separator' => 'comma'
   ),
   'TITL' => array(
     'typeface' => array('bold', 'italic'),
     'separator' => 'space'
   ),
   'PUBL' => array(
     'surround' => 'parens',
     'separator' => array('comma', 'break')
   ),
   '_CDTE' => array(
     'format' => 'F j, Y',
     'surround' => 'angles',
     'separator' => 'comma'
   )
 ... 

Four instruction sets are depicted and associated with the AUTH (author), TITL (title), PUBL (publisher) and the _CDTE (citation date) fields. The first will be displayed in plain typeface (not required, but there is no harm in specifying it) and will be followed by a comma. The second will be displayed in bold-italics and followed by a space. The third will default to plain typeface, surrounded by parenthesis, and followed by a comma and then a line-break. The fourth field, a date, will be formatted according to the PHP format string 'F j, Y', placed in angle brackets, and followed by a comma.

Note that the comma separator for the last field _CDTE will be suppressed by the formatting engine in favor of a trailer specified at the level of source specification (see below).

Standard Source/Citation Fields

TNG supports a number of standard source/citation fields which are represented in Citation Master by the GEDCOM tags in the following table. In addition, a set of GEDCOM tags are supported that represent information useful in generating page references such as the page URL.

Tag Description Sources Citations References Version(s) Notes
TITL Long Title Yes Yes Yes (1) v1 - v8
TTLS Short Title Yes Yes Yes (1) v1 - v8
AUTH Author Yes Yes Yes (1) v1 - v8
PUBL Publisher Yes Yes Yes (1) v1 - v8
REPO Repository Yes Yes Yes (1) v1 - v8
TEXT Actual Text Yes Yes Yes (1) v1 - v8
CALN Call Number Yes Yes Yes (1) v1 - v8
PAGE Page No Yes No v1 - v8
NOTE Notes No Yes No v1 - v8
QUAY Quality No Yes No v1 - v8 TNG refers to this as reliability
_CDSC Description No Yes No v7 - v8
_CTXT Actual Text No Yes No v7 - v8
_CDTE Date No Yes No v7 - v8 When used, requires a format instruction
_RNAM Individual's Name No No Yes v8 As the name appears on the page for which a reference is being generated
_RAUT Site Author No No Yes v8 Set from mod parameters using variable $citem_author
_RTTL Site Name No No Yes v8 Set using the TNG global variable $sitename
_RURL Page URL No No Yes v8 Derived from the PHP _SYSTEM global array
_RCDT Current Date-Time No No Yes v8 When used, requires a format instruction

(1) Citation Master supports identifying a single source record in mod parameters, where the fields from that source record are made available to the formatting engine when generating a page reference. In this manner all of the standard TNG source fields (just for that single source record) can be used for reference generation. (This is useful if your TNG database contains a source that references the database itelf, and you would like to include publication data in page references.)

Custom Event Support

Any custom event associated with a source or citation can be formatted by referring to its GEDCOM tag and creating a format instruction set. For example, Lindell-Herndon Genealogy has a custom Endnote Reference (represented by GEDCOM tag _EREF) attached to every source. This is used at the beginning of each source and citation entry and is formatted in bold with surrounding brackets. The format instruction set looks like this:

   '_EREF' => array(
     'typeface' => 'bold',
     'surround' => 'brackets',
     'separator' => 'space'
   ),
 ... 

Source Specifications

These are elements of a single PHP array that identify source types (such as 'Census') and the format instruction set to be applied. Source type names (e.g., Book) are usually specific to the genealogy program you use and how that program exports sources and citations in GEDCOM. My software, Reunion for Macintosh, uses names like 'Census', 'Will', and 'Compilation'. Yours may do something different.

The following is an example of a source specification for type 'Book':

 $citem_format_spec['Book'] = array(
     'name' => ,
     'comment' => 'Citation Master format for type Book (IEEE style).',
     'context' => 'all',
     'trailer" => 'period',
     'tags' => $book_format_inst
 );

This specifications associates the format instructions contained in $book_format_inst with the source type Book and instructs Citation Master to add a period after all such sources.

Two source specifications, _default and _reference, must exist in each Citation Master configuration file. _default is used for any source types that don't have their own specification. _reference is used for formatting page references. You can modify the instructions sets for these specifications, but do not delete them.

Configuration Files

Format instruction sets and source specifications are placed in a configuration file, and the active configuration file is identified in mod parameters. 5 sample configuration files are supplied with the latest version of Citation Master:

  • citem_config_apa.php - This configuration file provides _default and _reference styles that conform to the American Psychological Association citation standard.
  • citem_config_cmos.php - This is the default configuration file and provides styles that conform to the Chicago Manual of Style.
  • citem_config_ieee.php - This configuration file provides a styles that conform to the IEEE.
  • citem_config_example.php - This is an annotated configuration file containing examples of how to write format instruction sets and source specifications. It contains examples of almost every feature and option supported by Citation Master.
  • citem_config_lhgen.php - This is the author's own configuration file, used for site Lindell-Herndon Genealogy. This file is useful for demonstrating Citation Master's power.

Mod Parameters

Citation Master has 8 mod parameters:

Parameter Version(s) Description
$citem_type_tag v1 - v8 This parameter defines the custom event in TNG's database that holds a source type (e.g., Census). Many genealogy programs export the source type using the GEDCOM tag TYPE. Only change this value if your program uses a different GEDCOM tag. To find out what your software uses, examine one of your sources in TNG and look at the "Other Events". The source type filed will appear as one of these events. (You may also need to examine your custom events to determine the tag name.)
$citem_config_path v1 - v8 The location, relative to the root of your TNG installation, of your active Citation Master configuration file. The default for this parameter is mods/cite_master/config/citem_config_cmos.php.
$citem_use_short v3 - v8 When set to yes, this parameter instructs Citation Master to substitute Short Titles for Titles whenever the latter is empty. The default is no.
$citem_modify_sources v8 When true, Citation Master will modify sources (browsesources.php) according to the current configuration. Otherwise, TNG default formatting is used.
$citem_modify_citations v8 When true, Citation Master will modify citations (getperson.php) according to the current configuration. Otherwise, TNG default formatting is used.
$citem_display_pageref v8 When true, Citation Master will display the generated page reference (getperson.php) and format it according to the current configuration. Otherwise, the page reference is suppressed.
$citem_author v8 Value is used to populate the GEDCOM tag _RAUT for use in generating page references.
$citem_sourceid v8 Identifies source data that can be used during page reference generation. (See the section entitled Standard Source/Citation Fields for additional information on how to use this source.)

Mod Compatibility

  • The Responsive Tables series of mods make an incompatible modification to the header row of the sources table in browsesources.php. Citation Master v10.1.0.3a corrects this by removing it's own modification to that header row, with the downside that the table titles no longer reflect the content of the columns. v10.1.0.3a is recommended for any TNG users having both Citation Master and Responsive Tables installed. Otherwise, for full functionality, Citation Master v10.1.0.3 is recommended. Note that testing has only verified the installation compatibility of Citation Master and Responsive Tables, along with the preservation of Citation Master's functionality. The developer does not have the facilities necessary to test Responsive Tables' functionality.

Notes and Caveats

  • The format instruction sets and source specifications are valid PHP code. So if you make a mistake you'll probably encounter a syntax error when PHP attempts to render your page.
  • No instruction is ever required. There is always a default behavior.
  • Instruction order is important. Do you want your comma inside your quoted title? Then your separator instruction should come before your surround instruction.
  • You must have source specifications named _default. If no other specification matches the source type, this specification is used.
  • You must have a source specification named _reference for page reference generation.
  • Citation Master does not attempt to preserve intra-citation hyperlinks. Making URL's active (i.e., 'clickable') is supported by many browsers.

Frequently Asked Questions

Q: Why GEDCOM tags?

A: It was the only real way to level the playing field between all types of genealogy software while, at the same time, dealing with the fact that TNG stores some information in the sources table (I assign the expected GEDCOM tags to these pieces of data) and some data as custom events. It also helps me deal with the fact that genealogists sometimes define their own tags. For example, I use a custom "EREF" tag that stands for "endnote reference" (a shorthand that I use to refer to sources in notes and for naming source files). I have one of these assigned to every source in my database and wanted them printed on the browsesource.php and individual pages. TNG, of course, has no idea what this source field is because from it's perspective it's just a custom source event.

Q: Can you tell me more about the custom events that identify sources?

A: Most genealogy software, like Reunion (my software), assigns a GEDCOM tag to the type of a source (e.g., "census", "compilation, "vital record", etc...), and that shows up in TNG as a custom event when your source get imported. Citation Master needs to find the field that corresponds to your source type in the database in order to decide which of your format instruction sets to use. So, for my software, there is a custom event in the TNG database with tag "TYPE" and value "Vital Record". Citation Master finds that custom event for a particular citation, then looks up a set of format instructions for sources of type Vital Record.

Q: What happens if one of my source fields, one that I specified format instructions for, is empty or missing?

A: Don't worry about it. Citation Master treats an empty or missing source field as it simply doesn't exist in the output. In other words, data, surrounds and separators are simply omitted.

Q: What if I don't import source information but define it in TNG? In other words, TNG is my primary genealogy database.

A: This is tricky because it means that there may be no custom event to define your source type names, and unless you create such an event...for each source...you won't be able to define different format instructions for different source types. I don't have a good solution for this, but the default type, '_default', will still work for your sources. You'll just have to do your best to make sure it works for all your sources.

Q: Where are the admin interfaces so I don't have to deal with all this PHP configuration stuff?

A: :-) All in good time.

Revision History

Version Release Date Comments
11.1.2.8, 11.1.0.8, 11.0.0.8 Soon Major update that adds page references (a formatted reference that can be copied by other genealogists when they wish to reference a page on your TNG site), the ability to prepend and append text to citation/source fields, the ability to turn the Citation Master formatting engine on/off for citations, sources, references, and internationalization for 12 languages.
11.1.2.7 22 Dec 2017 Minor correction for TNG 11.1.2 compatibility.
11.1.0.7 9 Feb 2017 Compatible with TNG 11.1 and includes all the mod's version 7 functionality. In addition adds support for moving the extensions directory (a TNG 11.0.2 feature). This update is recommended for users of TNG 11.1 but earlier versions may also work.
11.0.0.7, 10.1.0.7, 10.0.2.7 9 Feb 2017 Adds support for three additional citation fields, _CDSC (database field 'description'), _CTXT (field 'citetext') and _CDTE (field 'citedate'). Also adds a new formatting option, 'format' which can be used with date fields stored in the DB or in custom events. (See the documentation and examples.) V7 will be the last update to this mod for TNG 10. This update is optional for TNG 10 and TNG 11.0 users.
11.0.0.6 21 Mar 2016 Now compatible with TNG 11.0.
10.0.2.6, 10.1.0.6 14 Feb 2016 Adds support for TNG's short source titles (see the revised documentation) and a new parameter that instructs Citation Master to substitute short titles for long titles when the latter are empty. Disambiguates some duplicate function code to support compatibility with the Regroup Person Profile series and other similar mods. v10.1.0.6 and v10.0.2.6 are recommended for all Citation Master users.
10.1.0.5 19 Jul 2015 Now compatible with TNG 10.1.2. v10.1.0.5 is backwards compatible patch that is compatible with all TNG releases from 10.1.0 forward, but it is only required for r10.1.2.
10.0.2.4, 10.1.0.4 15 Jul 2015 Adds an administrator interface that supports creation and editing of Citation Master configuration files. A new example config has been added to the distribution, and help is integrated into the admin interface. The source display page now has a profile field that shows how the source is formatted. This update is recommended for all users of TNG versions 10.0.2+ and 10.1.0+. For the moment, users of TNG 9.2.2 should continue to use v9.2.2.3. If you're interested in an update of Citation Master for TNG 9.2.2, please contact me. If there is enough interest, I'll consider a backport. Otherwise, v9.2.2.3 will be the last Citation Master release for TNG 9.2.2.
10.0.2.4, 10.1.0.4 5 Jul 2015 Release updated on 15 July to correct a bug in the cite-master library that would force use of the '_default' configuration regardless of the source type.
10.1.0.3a 15 Jun 2015 A variant of v10.1.0.3 that supports Responsive Tables.
10.1.0.3 8 Feb 2015 Updated for compatibility with TNG 10.1.0. (Thanks to Roger Mitchell for the initial patch set and testing.)
10.0.2.3, 9.2.2.3 6 Dec 2014 Adds support for switching configuration files as a Mod Manager variable. This allows users to keep multiple configuration files for different purposes and makes the process of customizing Citation Master's configuration a bit less cumbersome. (Note that the Mod Manager has no way of moving your custom configuration to the 'extensions' directory or even identifying a custom configuration. Keeping track of the location and name of a custom configuration is up to the user.) Also corrected an issue that caused errors with page header generation in some installations of TNG 10.0.3. This update is recommended for all users of TNG version 10.0.1 and later and is optional for users of TNG 9.2.2.
9.2.2.2 29 Nov 2014 Now supporting functionality from v10.0.2.2.
10.0.2.2 19 Nov 2014 Adds support for PDF reports as well as support for the page, description, and quality citation fields. This updated is recommended for all TNG users of TNG v10.0.2 and above due to improvements in the way that source and citation queries are executed against the TNG database.
10.0.2.1 N/A Version skipped to align version numbers across TNG release.
10.0.2.0 24 Aug 2014 Updated for compatibility with TNG 10.0.2.
9.2.2.1 17 Aug 2014 Now supporting multiple typeface instructions per tag. (See the examples for additional information.) The custom event tag that represents source type can now be set as a Mod parameter.
9.2.2.0 09 Aug 2014 Initial release.

Sites Using Citation Master

If you download and install this mod, please add your TNG site to the table below.

URL User Note Mod-Version TNG-Version Language(s)
Lindell-Herndon Genealogy Bill Herndon Mod developer, public site 11.1.2.8-rc3 11.1.2 DA, DE, EN, ES, FR, SV
Mitchell Families Online Roger Mitchell Great update Bill. Lots of work gone into this! 11.0.0.6 11.0.0
Hooley Family Links Rick Hooley Private site (guest/guest for access) 11.1.2.7 11.1.2
Our Family Histories Bryan Larson Private site (guest/guest for access) 11.1.2.7 11.1.2
Kystslekts Slektsider Roar Dahle Private site 11.1.2.7 (?) 11.1.2
DiFava/Brandt Family Tree Larry DiFava Public site 11.1.2.8-rc2 11.1.2 DE, EN, IT
Farrar’s Island Heritage Randy Farrar Private site (guest/guest for access) 11.0.0.6 11.0.2
Feldman and Related Families Fred Feldman Public site 11.1.0.7 11.1.1
Feldman Family Trees Fred Feldman Public site 11.1.0.7 11.1.1
Thacker Family Forest Fred Feldman Public site 11.1.0.7 11.1.1
Rosemeyer Family Forest Fred Feldman Public site 11.1.0.7 11.1.1
Vest Family Trees Fred Feldman Public site 11.1.0.7 11.1.1
Colvin and Calvin Families Fred Feldman Public site 11.1.0.7 11.1.1
Old Roots, New Branches Margie Bailey Private site 11.0.0.6 11.0.2
Pages From Our Past Allen Prunty Private site 11.1.2.7 11.1.2
Lake Champlain and How We Got Here (McCaffrey) Matt McCaffrey Public site 11.1.2.7 11.1.2
The Story of my Four Branches Beverley Stimpson Private site (guest/guest for access) 11.1.2.7 11.1.2
Gambrill Family tree Bobby Gambrill Public site 11.1.2.7 11.1.2
Our Family History (unknown) Public site 11.1.0.7 11.1.1
Cole / Tanner Family Tree David Cole Private Site 11.1.2.7 11.1.2
Bill & Lynn Desjardin's Genealogy Pages Bill Desjardin Private site (guest/guest for access) 11.1.2.7 11.1.2
Genealogie van de families Visscher en Schuurman Wietze Visscher Public site 11.1.2.7 11.1.2
Our Roy and Boucher Family Ken Roy Public site - very nice source citation using Kate Turabian system learned in college 11.1.2.7 11.1.2
Auf den Spuren meiner Vorfahren Uwe Haase Public site 11.1.2.7 11.1.2
Familienforschung der Familie Klatte Hubertus Klatte Public site 11.1.0.7 11.1.2