Name
Data::Edit::Xml::Xref - Cross reference Dita XML.
Synopsis
Check the references in a set of Dita XML documents held in folder inputFolder:
use Data::Edit::Xml::Xref;
my $x = xref(inputFolder=>q(in));
ok nws($x->statusLine) eq nws(<<END);
Xref:
10 bad first lines,
10 bad second lines,
9 bad conrefs,
9 bad xrefs,
8 duplicate ids,
8 missing image files,
8 missing image references,
3 bad topicrefs,
2 duplicate topic ids,
1 bad book map,
1 file failed to parse,
1 file not referenced
ENDThe counts listed in the statusLine are the counts of the files that have the described problems not a count of all the instances of the problem in all the files which would be larger.
More detailed reports are produced in the reports folder:
$x->reportsDescription
Cross reference Dita XML.
Version 20181216.
The following sections describe the methods in each functional area of this module. For an alphabetic listing of all methods by name see Index.
Cross reference
Check the cross references in a set of Dita files and report the results.
lll(@)
Write a message
Parameter Description
1 @m Message textxref(%)
Check the cross references in a set of Dita files held in inputFolder and report the results in the reports folder. The possible attributes are defined in Data::Edit::Xml::Xref
Parameter Description
1 %attributes AttributesExample:
my $N = 8;countLevels($$)
Count has elements to the specified number of levels
Parameter Description
1 $l Levels
2 $h HashwindowsFile($$)
Format file name for easy use on windows
Parameter Description
1 $xref Xref
2 $file FileunixFile($$)
Format file name for easy use on unix
Parameter Description
1 $xref Xref
2 $file FileformatFileNames($$$)
Format file names for easy use on unix and windows
Parameter Description
1 $xref Xref
2 $array Array of arrays containing file names in unix format
3 $column Column containing file namesHash Definitions
Data::Edit::Xml::Xref Definition
Attributes used by the Xref cross referencer.
attributeCount - {file}{attribute} == count of the different xml attributes found in the xml files.
author - {file} = author of file
badBookMaps - Bad book maps
badConRefs - [file, href] Invalid conref attributes.
badGuidHrefs - [file, href, location] Invalid guid hrefs
badImageRefs - Consolidated images missing.
badTopicRefs - [file, href] Invalid href attributes found on topicref tags.
badXRefs - [file, href] Invalid href attributes found on xref tags.
badXml1 - [Files] with a bad xml encoding header on the first line.
badXml2 - [Files] with a bad xml doc type on the second line.
conRefs - {file}{href} Count of conref definitions in each file.
docType - {file} == docType: the docType for each xml file.
duplicateIds - [file, id] Duplicate id definitions within each file.
duplicateTopicIds - [topicId, [files]] Files with duplicate topic ids - the id on the outermost tag.
fileExtensions - Default file extensions to load
fixBadRefs - Try to fix bad references in these files where possible.
fixRefs - Files that have a missing conref or href which can be ameliorated by renaming the failing attribute to "xtrf".
goodBookMaps - Good book maps
goodConRefs - Good con refs
goodGuidHrefs - {file}{href}{location}++ where a href that starts with GUID- has been correctly resolved
goodImageRefs - Consolidated images found.
goodTopicRefs - Good topic refs
goodXRefs - Good xrefs
guidHrefs - {file}{href} = location where href starts with GUID- and is thus probably a guid
ids - {file}{id} Id definitions across all files.
images - {file}{href} Count of image references in each file.
improvements - Improvements needed
inputFiles - Input files from inputFolder.
inputFolder - A folder containing the dita and ditamap files to be cross referenced.
inputFolderImages - {filename} = full file anme which works well for images because the md5 sun in their name is probably unique
maximumNumberOfProcesses - Maximum number of processes to run in parallel at any one time.
missingImageFiles - [file, href] == Missing images in each file.
missingTopicIds - Missing topic ids
noHref - Tags that should have an href but do not have one
notReferenced - Files in input area that are not referenced by a conref, image, topicref or xref tag and are not a bookmap.
parseFailed - [file] files that failed to parse
reports - Reports folder: the cross referencer will write reports to files in this folder.
results - Summary of results table
sourceFile - The source file from which this structure was generated
statusLine - Status line summarizing the cross reference. The counts listed in the status line are the counts of the files that have the described problems not a count of all the instances of all the problems in all the files.
summary - Print the summary line.
tagCount - {file}{tags} == count of the different tag names found in the xml files.
title - {file} = title of file
topicIds - {file} = topic id - the id on the outermost tag.
topicRefs - {file}{href}++ References from bookmaps to topics via appendix, chapter, topicref.
unixPath - Path to be used to name files on unix in reports
validationErrors - True means that Lint detected errors in the xml contained in the file
windowsPath - Path to be used to name files on windows in reports
xRefs - {file}{href}++ Xrefs references.
xrefBadFormat - External xrefs with no format=html
xrefBadScope - External xrefs with no scope=external
Attributes
The following is a list of all the attributes in this package. A method coded with the same name in your package will over ride the method of the same name in this package and thus provide your value for the attribute in place of the default value supplied for this attribute by this package.
Replaceable Attribute List
improvementLength
improvementLength
Improvement length
Private Methods
loadInputFiles($)
Load the names of the files to be processed
Parameter Description
1 $xref Cross referenceranalyzeOneFile($)
Analyze one input file
Parameter Description
1 $iFile File to analyzefixOneFile($$)
Fix one file by moving unresolved references to the xtrf attribute
Parameter Description
1 $xref Xref results
2 $file File to fixfixFiles($)
Fix files by moving unresolved references to the xtrf attribute
Parameter Description
1 $xref Xref resultsanalyze($)
Analyze the input files
Parameter Description
1 $xref Cross referencerreportDuplicateIds($)
Report duplicate ids
Parameter Description
1 $xref Cross referencerreportDuplicateTopicIds($)
Report duplicate topic ids
Parameter Description
1 $xref Cross referencerreportNoHrefs($)
Report locations where an href was expected but not found
Parameter Description
1 $xref Cross referencerreportRefs($$)
Report bad references found in xrefs or conrefs as they have the same structure
Parameter Description
1 $xref Cross referencer
2 $type Type of reference to be processedreportGuidHrefs($)
Report on guid hrefs
Parameter Description
1 $xref Cross referencerreportXrefs($)
Report bad xrefs
Parameter Description
1 $xref Cross referencerreportTopicRefs($)
Report bad topic refs
Parameter Description
1 $xref Cross referencerreportConrefs($)
Report bad conrefs refs
Parameter Description
1 $xref Cross referencerreportImages($)
Reports on images and references to images
Parameter Description
1 $xref Cross referencerreportParseFailed($)
Report failed parses
Parameter Description
1 $xref Cross referencerreportXml1($)
Report bad xml on line 1
Parameter Description
1 $xref Cross referencerreportXml2($)
Report bad xml on line 2
Parameter Description
1 $xref Cross referencerreportDocTypeCount($)
Report doc type count
Parameter Description
1 $xref Cross referencerreportTagCount($)
Report tag counts
Parameter Description
1 $xref Cross referencerreportAttributeCount($)
Report attribute counts
Parameter Description
1 $xref Cross referencerreportValidationErrors($)
Report the files known to have validation errors
Parameter Description
1 $xref Cross referencercheckBookMap($$)
Check whether a bookmap is valid or not
Parameter Description
1 $xref Cross referencer
2 $bookMap BookmapreportBookMaps($)
Report on whether each bookmap is good or bad
Parameter Description
1 $xref Cross referencerreportFileExtensionCount($)
Report file extension counts
Parameter Description
1 $xref Cross referencerreportFileTypes($)
Report file type counts - takes too long in series
Parameter Description
1 $xref Cross referencerreportNotReferenced($)
Report files not referenced by any of conref, image, topicref, xref and are not bookmaps.
Parameter Description
1 $xref Cross referencerreportExternalXrefs($)
Report external xrefs missing other attributes
Parameter Description
1 $xref Cross referencerreportPossibleImprovements($)
Report improvements possible
Parameter Description
1 $xref Cross referencerreportTopicDetails($)
Things that occur once in each file
Parameter Description
1 $xref Cross referencercreateSampleInputFiles($)
Create sample input files for testing. The attribute inputFolder supplies the name of the folder in which to create the sample files.
Parameter Description
1 $N Number of sample filesIndex
1 analyze - Analyze the input files
2 analyzeOneFile - Analyze one input file
3 checkBookMap - Check whether a bookmap is valid or not
4 countLevels - Count has elements to the specified number of levels
5 createSampleInputFiles - Create sample input files for testing.
6 fixFiles - Fix files by moving unresolved references to the xtrf attribute
7 fixOneFile - Fix one file by moving unresolved references to the xtrf attribute
8 formatFileNames - Format file names for easy use on unix and windows
9 lll - Write a message
10 loadInputFiles - Load the names of the files to be processed
11 reportAttributeCount - Report attribute counts
12 reportBookMaps - Report on whether each bookmap is good or bad
13 reportConrefs - Report bad conrefs refs
14 reportDocTypeCount - Report doc type count
15 reportDuplicateIds - Report duplicate ids
16 reportDuplicateTopicIds - Report duplicate topic ids
17 reportExternalXrefs - Report external xrefs missing other attributes
18 reportFileExtensionCount - Report file extension counts
19 reportFileTypes - Report file type counts - takes too long in series
20 reportGuidHrefs - Report on guid hrefs
21 reportImages - Reports on images and references to images
22 reportNoHrefs - Report locations where an href was expected but not found
23 reportNotReferenced - Report files not referenced by any of conref, image, topicref, xref and are not bookmaps.
24 reportParseFailed - Report failed parses
25 reportPossibleImprovements - Report improvements possible
26 reportRefs - Report bad references found in xrefs or conrefs as they have the same structure
27 reportTagCount - Report tag counts
28 reportTopicDetails - Things that occur once in each file
29 reportTopicRefs - Report bad topic refs
30 reportValidationErrors - Report the files known to have validation errors
31 reportXml1 - Report bad xml on line 1
32 reportXml2 - Report bad xml on line 2
33 reportXrefs - Report bad xrefs
34 unixFile - Format file name for easy use on unix
35 windowsFile - Format file name for easy use on windows
36 xref - Check the cross references in a set of Dita files held in inputFolder and report the results in the reports folder.
Installation
This module is written in 100% Pure Perl and, thus, it is easy to read, comprehend, use, modify and install via cpan:
sudo cpan install Data::Edit::Xml::XrefAuthor
Copyright
Copyright (c) 2016-2018 Philip R Brenan.
This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.