Difference between revisions of "Citation Master Basic Mod"

From TNG_Wiki
Jump to navigation Jump to search
(Replaced content with "=== The Citation Master Basic Mod and this page are now obsolete. Please follow the link below for the mod's new page.=== ===Citation Master===")
Line 1: Line 1:
{{TNGmod
+
=== The Citation Master Basic Mod and this page are now obsoletePlease follow the link below for the mod's new page.===
| mod_name        = Citation Master Basic
 
| mod_summary    = Customize the format and content of citations (individual pages) and sources (browsing page).
 
| mod_validation =
 
| download_link  =
 
[http://wherndon.net/genealogy/mods/mod-cite-master-v10.1.0.3.zip v10.1.0.3]&nbsp;{{Tv1010}}<hr/>[http://wherndon.net/genealogy/mods/mod-cite-master-v10.1.0.3a.zip v10.1.0.3a]&nbsp;{{Tv1010}}<hr/>[http://wherndon.net/genealogy/mods/mod-cite-master-v10.0.2.3.zip v10.0.2.3]&nbsp;{{Tv102}}<hr/>[http://wherndon.net/genealogy/mods/mod-cite-master-v9.2.2.3.zip v9.2.2.3]&nbsp;{{Tv922}}
 
| download_stats =
 
| mod_author      = [[User:wrherndon|Bill Herndon]]
 
| mod_url        = [[Citation Master Basic Mod]]
 
| mod_support    = [mailto:bill@wherndon.net Email me.]
 
| mod_contact    =
 
| mod_version    = v10.1.0.3a for TNG 10.1.0 with [[Responsive Tables]]<br/>v10.1.0.3 (includes all features of the 4th release) for TNG 10.1<br />v10.0.2.3 for TNG 10.0.2+<br />v9.2.2.3 for TNG 9.2.2
 
| min_TNG_ver    = 9.2.2
 
| max_TNG_ver    = 10.1.1
 
| TNG_file_list  = browsesources.php<br/>personlib.php<br/>rpt_fam.php<br/>rpt_ind.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.3 is compatible.
 
}}
 
  
{| style="margin-right:0.5 em;" align="right"
+
===[[Citation Master]]===
| __TOC__
 
|}
 
 
 
== 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  Basic can help by allowing you to define the format and
 
content of citations.
 
 
 
== Developer ==
 
[[User:wrherndon|Bill Herndon]]
 
== Requirements ==
 
* A working TNG installation
 
* An installed current version of the [[Mod Manager]] (is already included in TNG v9)
 
* Shell-level access to your TNG host (for editing the configuration file)
 
== Installation ==
 
* Download the .zip file to your mods directory and unpack it.
 
* Inside the the sub-directory, ''egenea_cite_master'', edit the configuration file  ''egenea_cfg_citation.php'' to add format instruction sets for your own source types. 
 
* Install the mod using the TNG Mod Manager
 
== Upgrading ==
 
* Disable the mod through the Mod Manager
 
* Back up your copy of ''mods/egenea_cite_master/egenea_cfg_citation.php''
 
* Install the new version of the mod
 
* Restore your copy of ''''mods/egenea_cite_master/egenea_cfg_citation.php''
 
* Enable the mod through the Mod Manager
 
 
 
== Features ==
 
* Define the fields, order, typeface, surrounding punctuation, and separators that go into a displayed citation or source
 
* Create different format instruction sets for different sources (e.g., Census vs. Will)
 
* Override TNG's formatting behavior for individual citations and source browsing.
 
Citation Master Basic supports changes to the typeface of a source field, the punctuation
 
that surrounds the field, the separator that follows the field, and the punctuation that
 
follows the citation.  (Typeface, surround, and separator are referred to later as ''categories''.)
 
=== Typefaces ===
 
Four typefaces are supported: 'plain', 'bold', 'italic', and 'uline' (i.e., underline).
 
=== Surrounds ===
 
Five types of surrounding punctuation are supported: 'parens' (i.e., parenthesis), 'quotes', 'brackets' (i.e., square brackets), 'braces' (i.e., curly braces), and 'angles' (i.e., angle brackets).
 
=== Separators ===
 
The supported field separators are: 'space', 'comma', 'colon', 'period', 'semi' (i.e., semi-colon), and 'dash'.  With the exception of dashes, that have spaces both before and after, all other punctuation marks have a single appended space.
 
 
 
==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 Basic [http://wherndon.net/genealogy/mods/mod-cite-master-v10.1.0.3a.zip 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 Basic [http://wherndon.net/genealogy/mods/mod-cite-master-v10.1.0.3.zip 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 instructions 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. 
 
* Multiple typeface instructions are supported per source tag.  (See the 'Examples' for the syntax of such an instruction.) 
 
* 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 a source specification named "_default".  If no other specification matches the source type, this specification is used.
 
* The '_default' specification supplied in the example configuration file corresponds to the requirements of the Chicago Manual of Style, book format.
 
* For TNG v10.0.2 Citation Master Basic does not attempt to preserve intra-citation hyperlinks (a new feature).
 
=== Formatting Instructions ===
 
This is a PHP array that associates GEDCOM tags with formatting instructions. So, for example, the TITL (title) tag might be associated with the typeface 'bold'and be followed by a 'comma' (a 'separator' instruction).
 
=== Source Specifications ===
 
These are PHP arrays that define source types (such as 'Census') and identify the format instruction sets that get applied.  Source type names are usually specific to the genealogy program you use for your data and how that program exports that data to GEDCOM.  My software, Reunion for Macintosh uses names like 'Census', 'Will', and 'Compilation'.  Yours will almost certainly do something different.
 
The '_default' specification must exist in the configuration file to handle any source types that don't have their own specifications.  Don't delete it.
 
 
 
== Examples ==
 
=== Screenshots ===
 
The following is an example from the source browsing page on [http://wherndon.net/genealogy/browsesources.php Lindell-Herndon Genealogy]:<br/>(The format approximates the IEEE citation style):
 
 
 
[[File:example-sources.png]]
 
 
 
 
 
The next image depicts [http://wherndon.net/genealogy/getperson.php?personID=I32#sources citations on a individual's page]:
 
 
 
[[File:example-citations.png]]
 
 
 
=== Format Instructions and Source Specifications ===
 
Format instructions associate things like typefaces with the GEDCOM tags that represent particular source fields.  For example:
 
<code>
 
    ...
 
    "TITL" => array(
 
      "typeface" => "italics",
 
      "separator" => "comma",
 
      "surround" => "quotes"
 
    ),
 
    "PUBL" => array(
 
      "typeface" => array("bold", "italics"),
 
      "surround" => "parens",
 
      "separator" => "space"
 
    ),
 
    ... 
 
</code>
 
...instructs Citation Master to display a source's title field (GEDCOM tag TITL) in italics, append a comma, and then surround the whole thing in quotes.  A PUBL (publisher) field should be displayed in bold-italics, surrounded by parenthesis, and followed by a space.
 
 
 
Source specifications define what set of format instructions go with what source, and whether that source should have any leading or trailing punctuation.  For example:
 
<code>
 
  $egenea_source_fmt['Census'] = array(
 
    "name" => "",
 
    "comment" => "Citation Master format for type 'Census' (IEEE style).",
 
    "context" => "all",
 
    "trailer" => "period",
 
    "tags" => $census_fmt_ins
 
  );
 
</code>
 
...associates the format instructions contained in ''$census_fmt_ins'' with the source type ''Census'' and instructs Citation Master to add a period after all such sources.
 
 
 
== 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''':  '''''What's the variable $egenea_srctype_tag mean and how should I set it?'''''
 
 
 
'''A''':  Most genealogy software, like Reunion (my software), assigns a GEDCOM style tag to the type of source (e.g., "census", "compilation, "vital record", etc...), and that shows up in TNG as a custom event when your source get imported.  I need to find the field that corresponds to your source type in the database in order to decide which of your defined formats to use.  So, for my software, there is a custom event in the TNG database with tag "TYPE" and value "Vital Record", and I know to look for an entry in the $egenea_source_fmt variable called "Vital Record" containing all the formatting instructions for vital records.
 
 
 
'''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 ==
 
{| border="0" cellspacing="1" cellpadding="2" class="wikitable"
 
|-
 
! Version
 
! Release&nbsp;Date
 
! Comments
 
|- valign="top"
 
| 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.)
 
|- valign="top"
 
| 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.
 
|- valign="top"
 
| 9.2.2.2
 
| 29 Nov 2014
 
| Now supporting functionality from v10.0.2.2.
 
|- valign="top"
 
| 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.
 
|- valign="top"
 
| 10.0.2.1
 
| N/A
 
| Version skipped to align version numbers across TNG release.
 
|- valign="top"
 
| 10.0.2.0
 
| 24 Aug 2014
 
| Updated for compatibility with TNG 10.0.2.
 
|- valign="top"
 
| 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.
 
|- valign="top"
 
| 9.2.2.0
 
| 09 Aug 2014
 
| Initial release.
 
|-
 
|}
 
 
 
== Sites Using Citation Master Basic ==
 
If you download and install this mod, please add your TNG site to the table below.
 
{| border="0" cellspacing="1" cellpadding="3" class="wikitable"
 
|-
 
! URL
 
! User
 
! Note
 
! Mod-Version
 
! TNG-Version
 
|-
 
| [http://wherndon.net/genealogy Lindell-Herndon Genealogy]
 
| [[User:wrherndon|Bill Herndon]]
 
| Mod developer
 
| 10.1.0.3
 
| 10.1.0
 
|-
 
| [http://mfo.me.uk Mitchell Families Online]
 
| [[User:HiTowerUK|Roger Mitchell]]
 
| Great update Bill. Lots of work gone into this!
 
| 10.0.2.3
 
| 10.0.3
 
|-
 
| [http://genealogy.oceanwharf.com Hooley Family Links]
 
| [[User:lastejas|Rick Hooley]]
 
| Public Site
 
| 10.1.0.3
 
| 10.1.1
 
|}
 

Revision as of 21:18, 6 July 2015

The Citation Master Basic Mod and this page are now obsolete. Please follow the link below for the mod's new page.

Citation Master