Automated Analysis no-LT
Antenna House Formatter V7.4 is able to automatically detect a range of typographic problems in the formatted Area Tree. Solving these problems usually requires editorial or stylistic changes, and sometimes both.
Specify -analyze on the Antenna House Formatter V7.4 Command-line Interface to enable analysis. Any problems detected are reported in the error information output. An XSLT stylesheet for annotating the Area Tree XML with visual indications of the analysis problems is available on GitHub at https://github.com/AntennaHouse/analysis-utility You are free to modify the XSLT stylesheet you obtained, but it is outside the scope of our support.
Every language, including English, has stylistic conventions for formatted text. The origins of the conventions may be for readability, for aesthetics, for commercial reasons, or for a mix of these. Some are now just considered to be good design without reference to the underlying reason. Books on typography or book design will usually cover a subset of possible problems, but even the reference books differ in what they consider to be a problem, the threshold for a condition becoming a problem, and even the terminology for describing a problem.
| CAUTION: | Automated Analysis is not available with Antenna House Formatter V7.4 Lite. |
|---|
Analyzers
The checks, which can be individually enabled or disabled in the Option Setting File, are:
- End Blank Pages
- Hyphens on Consecutive Lines
- Repeated First or Last Word
- Number of Lines Before or After Current Block
- Page Widow
- Paragraph Widow
- River
- Unbalanced Spread
- White-space
End Blank Pages
This analyzer reports when the number of blank pages exceeds the end-blank-pages-limit option setting.
The printing and binding method used for a book may require that the book is a multiple of 8, 16, 32, or even more pages. Extensions to the force-page-count property make this possible with Antenna House Formatter V7.4. However, the forced page count may create empty pages at the end of the document just to fulfil the requirement. Empty pages are a cost to the publisher with little or no obvious benefit.
Hyphens on Consecutive Lines
This analyzer reports when the number of consecutive lines that end with a hyphen exceeds the hyphen-limit option setting.
Too many consecutive lines that end with a hyphen increase the likelihood that a reader will either skip reading a line or read the same line twice. Both the Chicago Manual of Style (17th edition) and Elements of Typographic style recommend a maximum of three consecutive lines that end with a hyphen.
Antenna House Formatter V7.4 implements the XSL 1.1 hyphenation-ladder-count property for automatically limiting the number of successive lines that end with a hyphen. For CSS, it implements the similar hyphenate-lines from an early draft of GCPM. However, the appropriate property may not have been set, or it may be preferable to review the lines before letting Antenna House Formatter V7.4 automatically adjust the lines.
| CAUTION: | This analyzer ignores blocks with a right-to-left writing mode. |
|---|
Repeated First or Last Word
This analyzer reports when the number of consecutive lines that start with the same word exceeds the line-start-repeat-limit option setting or the number of consecutive lines that end with the same word exceeds the line-end-repeat-limit option setting.
This is similar to the problem with multiple consecutive lines that end on a hyphen. Multiple consecutive lines that start with the same word or lines that end with the same word can result in a reader either skipping a line of text or rereading a line. The Chicago Manual of Style (17th edition) recommends a maximum of three lines that either start or end with the same word. Book Typography warns against multiple lines that end with the same word but does not provide a limit and does not mention lines that start with the same word.
Lines Before or After Current Block
When a chapter does not start on a new page, there can be a requirement for a minimum number of lines either before or after the chapter heading. Book Typography recommends at least three lines above and below the chapter heading. This can usually be enforced using the widows and orphans properties, but not when, for example, the previous chapter ends with short lines of dialogue.
A section break is a space the height of one or two blank lines, possibly containing an asterisk or other symbol or symbols. It indicates a change of scene or subject. There can be a requirement for a minimum number of lines above and below a section break. Book Typography recommends at least two lines above and below a section break.
This analyzer reports when the number of lines before the current block is more than zero but less than the axf:analyze-lines-before property or the number of lines after the current block is more than zero but less than the axf:analyze-lines-after property. The effect of the properties can be disabled using the lines-before and lines-after option settings.
| CAUTION: | If there is a requirement for at least one line before or after the current block area, use keep-with-previous or keep-with-next, as appropriate. |
|---|
| CAUTION: | Content of <fo:list-item-label> is not counted as lines. |
|---|
| CAUTION: | This analyzer only counts lines in the same reference area. |
|---|
Page Widow
This analyzer reports when a short last line of a block of text is formatted as the first line on a page or column. The line is too short when it is shorter than either the page-widow-limit-em or page-widow-limit-percent option setting.
widows is name of the XSL and CSS property that controls the number of line of a paragraph that must be left at the top of a page.
Paragraph Widow
This analyzer reports when a block of text has a short last line. The line is too short when it is shorter than either the paragraph-widow-limit-em or paragraph-widow-limit-percent option setting.
widows is name of the XSL and CSS property that controls the number of line of a paragraph that must be left at the top of a page.
River
A river occurs where spaces on consecutive lines overlap, or nearly overlap. Rivers are more likely to occur in justified text than in text that is aligned to one side or is centered. A large or long river of white-space may interfere with comprehension of the text. People differ in their sensitivity to rivers, but it is often noted as a problem for people with certain cognitive disabilities, including dyslexsia.
This analyzer reports when the cumulative width of overlapping white-space on consecutive lines exceeds the river option setting. The option setting may be overridden using the axf:analyze-river property.
Non-overlapping spaces on consecutive lines that are within the river-zone option setting length are considered a part of the same river. The option setting may be overridden using the axf:analyze-river property.
| CAUTION: | This analyzer applies only to blocks with a left-to-right writing mode. |
|---|
Unbalanced Spread
This analyzer reports when the difference in the formatted length of the text in corresponding body regions on the left-hand and right-hand pages of a two-page spread exceeds the unbalanced-spread-limit option setting. The option setting may be overridden using the axf:analyze-unbalanced-spread property.
A spread is not checked if either the left or right page of the spread is the last page of its page sequence.
White-space
This analyzer reports when the white-space between words in a line is stretched and exceeds the white-space option setting. The option setting may be overridden using the axf:analyze-white-space property.
| CAUTION: | This analyzer applies only to blocks with a left-to-right writing mode. |
|---|
Extended Properties
axf:analyze no-LT
Specifies whether to perform analyzer checks on the current FO and its descendants.
| Value: | true | false | auto |
| Initial: | auto |
| Applies to: | all elements |
| Inherited: | no |
| Percentages: | N/A |
Values have the following meanings:
- true
Perform analyzer checks on this FO and its descendants.
- false
Do not perform analyzer checks on either this FO or its descendants
- auto
Dependent on the system setting. This is the value specified by analyze in the Option Setting File.
This property is not available with Antenna House Formatter V7.4 Lite.
axf:analyze-end-blank-page no-LT
Specifies whether to perform end-blank-page analyzer checks on the current FO and its descendants.
| Value: | auto | none | <integer> |
| Initial: | auto |
| Applies to: | fo:page-sequence |
| Inherited: | yes |
| Percentages: | N/A |
Values have the following meanings:
- auto
Dependent on the system setting. This is the value specified by end-blank-pages-limit in the Option Setting File.
- none
Do not perform end-blank-page analyzer checks on this FO or its descendants.
- <integer>
Allowed number of blank pages at the end of document. Blank pages in excess of this causes an analyzer error.
This property is not available with Antenna House Formatter V7.4 Lite.
axf:analyze-hyphen no-LT
Specifies whether to perform hyphen analyzer checks on the current FO and its descendants.
| Value: | auto | none | <integer> |
| Initial: | auto |
| Applies to: | block elements |
| Inherited: | yes |
| Percentages: | N/A |
Values have the following meanings:
- auto
Dependent on the system setting. This is the value specified by hyphen-limit in the Option Setting File.
- none
Do not perform hyphen analyzer checks on this FO or its descendants.
- <integer>
Allowed number of consecutive lines that end with a hyphen. Consecutive lines in excess of this causes an analyzer error.
This property is not available with Antenna House Formatter V7.4 Lite.
axf:analyze-line-end-repeat no-LT
Specifies whether to perform line-end-repeat analyzer checks on the current FO and its descendants.
| Value: | auto | none | [<integer> <integer>?] |
| Initial: | auto |
| Applies to: | block elements |
| Inherited: | yes |
| Percentages: | N/A |
Values have the following meanings:
- auto
Dependent on the system setting. This is the value specified by line-end-repeat-limit in the Option Setting File.
- none
Do not perform line-end-repeat analyzer checks on this FO or its descendants.
- <integer>
Allowed number of consecutive lines that end with the same word. Lines in excess of this causes an analyzer error.
A second integer specifies the maximum number of characters at the end of the line to compare. This overrides the value specified by line-end-limit in the Option Setting File.
This property is not available with Antenna House Formatter V7.4 Lite.
axf:analyze-line-start-repeat no-LT
Specifies whether to perform line-start-repeat analyzer checks on the current FO and its descendants.
| Value: | auto | none | [<integer> <integer>?] |
| Initial: | auto |
| Applies to: | block elements |
| Inherited: | yes |
| Percentages: | N/A |
Values have the following meanings:
- auto
Dependent on the system setting. This is the value specified by line-start-repeat-limit in the Option Setting File.
- none
Do not perform line-start-repeat analyzer checks on this FO or its descendants.
- <integer>
Allowed number of consecutive lines that start with the same word. Lines in excess of this causes an analyzer error.
A second integer specifies the maximum number of characters at the start of the line to compare. This overrides the value specified by line-start-limit in the Option Setting File.
This property is not available with Antenna House Formatter V7.4 Lite.
axf:analyze-lines-after no-LT
Specifies whether to analyze the number of lines after the last area generated by this FO.
| Value: | none | <integer> |
| Initial: | none |
| Applies to: | block elements |
| Inherited: | no |
| Percentages: | N/A |
Values have the following meanings:
- none
Do not perform lines-after analyzer checks on this FO.
- <integer>
Minimum number of consecutive lines in the current column after the last area generated from this FO. A non-zero number of following lines less than this causes an analyzer error.
This property is not available with Antenna House Formatter V7.4 Lite.
axf:analyze-lines-before no-LT
Specifies whether to analyze the number of lines before the first area generated by this FO.
| Value: | none | <integer> |
| Initial: | none |
| Applies to: | block elements |
| Inherited: | no |
| Percentages: | N/A |
Values have the following meanings:
- none
Do not perform lines-before analyzer checks on this FO.
- <integer>
Minimum number of consecutive lines in the current column before the first area generated from this FO. A non-zero number of previous lines less than this causes an analyzer error.
This property is not available with Antenna House Formatter V7.4 Lite.
axf:analyze-page-widow no-LT
Specifies whether to perform page widow analyzer checks on the current FO and its descendants.
| Value: | auto | none | <length> | <percentage> |
| Initial: | auto |
| Applies to: | all elements |
| Inherited: | yes |
| Percentages: | refer to the width of line |
Values have the following meanings:
- auto
Dependent on the system setting. This is the value specified by page-widow in the Option Setting File.
- none
Do not perform page widow analyzer checks on this FO or its descendants.
- <length>
- <percentage>
Minimum length of a page widow. A page widow that is less than this length causes an analyzer error.
This property is not available with Antenna House Formatter V7.4 Lite.
axf:analyze-paragraph-widow no-LT
Specifies whether to perform paragraph widow analyzer checks on the current FO and its descendants.
| Value: | auto | none | <length> | <percentage> |
| Initial: | auto |
| Applies to: | all elements |
| Inherited: | yes |
| Percentages: | refer to the width of line |
Values have the following meanings:
- auto
Dependent on the system setting. This is the value specified by paragraph-widow in the Option Setting File.
- none
Do not perform paragraph widow analyzer checks on this FO or its descendants.
- <length>
- <percentage>
Minimum length of a paragraph widow. A paragraph widow that is less than this length causes an analyzer error.
This property is not available with Antenna House Formatter V7.4 Lite.
axf:analyze-river no-LT
Specifies whether to perform river analyzer checks on the current FO and its descendants.
| Value: | auto | none | [<length> <length>?] |
| Initial: | auto |
| Applies to: | block elements |
| Inherited: | yes |
| Percentages: | N/A |
Values have the following meanings:
- auto
Dependent on the system setting. This is the value specified by river in the Option Setting File.
- none
Do not perform river analyzer checks on this FO or its descendants.
- <length>
Maximum cumulative length of a white-space river. A cumulative width that is greater than this length causes an analyzer error.
A second length specifies the “river zone” in which two spaces on consecutive lines that do not overlap are considered part of the same river. This overrides the value specified by river-zone in the Option Setting File.
This property is not available with Antenna House Formatter V7.4 Lite.
axf:analyze-unbalanced-spread no-LT
Specifies whether to perform unbalanced-spread analyzer checks on the current FO and its descendants.
| Value: | auto | none | <length> |
| Initial: | auto |
| Applies to: | fo:region-body |
| Inherited: | yes |
| Percentages: | N/A |
Values have the following meanings:
- auto
Dependent on the system setting. This is the value specified by unbalanced-spread-limit in the Option Setting File.
- none
Do not perform unbalanced-spread analyzer checks on this FO or its descendants.
- <length>
Maximum vertical imbalance of the last areas of two body regions with the same region name on facing pages of one spread. An imbalance that is greater than this length causes an analyzer error.
This property is not available with Antenna House Formatter V7.4 Lite.
axf:analyze-white-space no-LT
Specifies whether to perform white-space analyzer checks on the current FO and its descendants.
| Value: | auto | none | <length> | <percentage> |
| Initial: | auto |
| Applies to: | block elements |
| Inherited: | yes |
| Percentages: | refer to the width of line |
Values have the following meanings:
- auto
Dependent on the system setting. This is the value specified by white-space in the Option Setting File.
- none
Do not perform white-space analyzer checks on this FO or its descendants.
- <length>
- <percentage>
Maximum length of white-space between words on a line. A width that is greater than this length causes an analyzer error.
This property is not available with Antenna House Formatter V7.4 Lite.
Error Message Format
Error messages from analyzing the Area Tree may include one or both of a message about the error and an indication of the location of the error. The general format of an analyzer error in XML format is:
<error level="1" code="45959">
Message
location:: page: 3; ax: 18; ay: 242; bx: 191.764; by: 270;
</error>where:
- Message
Error message text. This may be omitted. For example, when the number of blank pages at the end of the document exceeds the limit by more than one page, an error message is generated for each page, but only the last page has the error message text showing the number of excess pages.
- location::
Literal text that is included in every location indication.
- page: 3
Absolute page number of the page containing the error.
- ax: 18
Absolute position, in pt, of the right edge of the error indication area.
- ay: 242
Absolute position, in pt, of the top edge of the error indication area.
- bx: 191.764
Absolute position, in pt, of the left edge of the error indication area.
- by: 270
Absolute position, in pt, of the bottom edge of the error indication area.
Note that the error indication area does not always correspond to a single area in the Area Tree.
References
- Bringhurst, R. (2001). The Elements of Typographic Style (2.4 ed.). Vancouver, BC, Canada: Hartley & Marks.
- Mitchell, M., & Wrightman, S. (2005). Book Typography: A Designer's Manual. Marlborough, Wiltshire: Libanus Press.
- The University of Chicago Press. (2017). The Chicago Manual of Style (17th ed.). Chicago and London: The University of Chicago Press.
- W3C. (2014, September 30). Requirements for Latin Text Layout and Pagination. (D. Cramer, Ed.) Retrieved from: https://www.w3.org/TR/dpub-latinreq/