Style Parsing Methods

General

Styles are defined by a collection of text fields, called "parse strings" or "style strings", which are parsed by Factsmith when exporting. These contain three main things:

  • Plain text, which is exported verbatim. This is for things like commas, connecting words like "by" or "taken from", and spaces and line breaks between parts of the evidence. You can put pretty much any text in, however; it will all be indiscriminately inserted into the file, no matter how strange.
  • Formatting codes, which are functionally much like HTML tags. They tell the export parser to do things like start or end the text being bold. (See Formatting Code Reference for a complete listing of all available codes.)
  • Insert tags, which tell the export parser to insert something from the actual evidence (like the tagline, page number, actual evidence quote, etc.) in place of the tag. Insert tags look like [SOURCE]. (See Insert Tag Reference for a complete listing of all available tags.)

The following is a listing of the different parse strings and when they are inserted:

Evidence: Parsed repeatedly, once for each evidence card
Source: Parsed whenever the [SOURCE] insert tag is used (see Insert Tag Reference and "Source Parsing", below)
Author: Parsed repeatedly, once for each author, whenever the [AUTHORS] insert tag is used (see Insert Tag Reference and "Author Parsing", below)
Text Block: Parsed repeatedly, once for each raw text block
Header: Parsed once for the header of the document (at the top of each page)
Footer: Parsed once for the footer of the document (at the bottom of each page)
Document Start: Parsed once at the beginning of the document
Document End: Parsed once at the end of the document
Section Start: Parsed at the beginning of each section
Section End: Parsed at the end of each section, before the next section starts
Underlining start: Parsed repeatedly, at the start of every underlined portion of a quote or text block
Underlining end: Parsed repeatedly, at the end of every underlined portion of a quote or text block
Plain paragraph: Parsed repeatedly, at the start of every paragraph in a quote or text block that does not have any underlining
Last paragraph: Parsed repeatedly, at the start of the last paragraph of a quote or text block


Source Parsing

Source parsing is comparatively simple: every time the [SOURCE] tag is used, the Source string is parsed (with insert tags pointing to the source for the evidence it was called from) and the output is inserted in the file.

Special feature: Comma stripping, which can be turned on from the Style tab in the Options dialog, will remove a comma followed by a space at the start of an exported source. For example, if the beginning of a source reads ", Murphy Institute, 2009...", it will change it to "Murphy Institute, 2009...". This is a special case to work around deficiencies in null logic. There must be no formatting codes before the comma; you can put formatting codes in the Evidence parse field directly before the [SOURCE] insert tag if you need to.

There is actually nothing preventing the source from being parsed more than once other than that it looks strange.


Author Parsing

Author parsing is the most complicated of any parsing task. Whenever the [AUTHORS] insert tag is used, this parse method is employed to insert a list of the authors. The parse method is as follows:

  1. If there is only a single author, the Author string is parsed (with insert tags pointing to the appropriate author) and the output is inserted in the file. ("Author1")
  2. If there are two authors, the Author string is parsed once for the first author, the word "and" is appended, and it is parsed again for the second author. ("Author1 and Author2")
  3. If there are three or more authors, the Author string is parsed once for each author with commas in between and an "and" before the last author. ("Author1, Author2, and Author3")

Special Styling

Several advanced features are provided to simplify certain formatting tasks.

Underlining: the "Underlining start" and "Underlining end" parse strings can be used to apply special formatting to underlined portions of quotes and text blocks; for example, you might set the quote to 10pt font, but make all underlined text 12pt font by putting <size12> in "Underlining start" and </size12> in "Underlining end".

However, many researchers don't bother to underline anything when the entire paragraph is supposed to be read. To keep the entire paragraph from having 10pt text, you could put <size12> in the "Plain paragraph" parse string to set paragraphs with no underlining to 12pt. (In practice, it's better to use paragraph styles for this, since some exporters may get confused if there is no </size12> tag. I.e., you could define a style called "Quote - Read All" and put <style=Quote - Read All> in "Plain paragraph". See Paragraph Styles for a discussion of why and how to use paragraph styles.)

Last paragraph: It is sometimes convenient to apply different formatting to the final paragraph of multi-paragraph quotes, for example to add extra space between the end of the quote and the next tagline, or to mark the end of a <lock>ed section so the word processor knows where to insert page breaks. This is the purpose of the "Last paragraph" parse string: any formatting in "Last paragraph" will only be applied to the final paragraph of a quote or text block. (If there is only one paragraph, then the entire quote counts as the "last" paragraph.)

Break cleaning: The "Style" tab of the Style Editor allows you to turn on two optional features. "Convert double line breaks to paragraph breaks" is useful for styles (such as CITE-compliant styles) that use paragraph spacing to format quotes and do not want extraneous line breaks between paragraphs. "Clean extra line breaks from end of quotes" is useful for tidiness, but also for compatibility with older briefs. Prior to v1.5, users had to manually add line breaks to the end of raw text blocks to keep them from running into the next paragraph; with the new Text Block parse string, this is no longer necessary, so this option is useful to keep older briefs from being exported with extraneous line breaks that the style does not expect.


Date Parsing

Date parsing is somewhat different than other parsing tasks, but is placed here for consistency. If the "Munch dates for consistent output" checkbox is checked, dates will be scanned to try to determine the contents, and the resulting date - if possible - will be formatted according to the date format listed, or the global date format set from the Options dialog. If the date is not understandable or the checkbox is unchecked, the date will be exported as written without any modification.