Package SrcTargetDesc

The package contains meta information on the latex main file, and, provided reproduction is requested, on the PDF file to be reproduced. All these pieces of information need to be bundled, to make tem available to various functions without polluting the main package.

Latex main files are identified via a regular expression pattern which provides various pieces of information:

Attributes and their Getters

The attributes are all declared with my so for external access getters are required.

%withMagicComments

The attribute "%withMagicComments" is written as side effect of _parseMagicComments() invoked by init(). Note that this does not just contain the magic comments, but it contains the settings determined by base configuration possibly overwritten by magic comments. The keys are as in the configuration given by the pom. Unlike "docMeta", this is always defined after compiling_cmd has been invoked.

TBD: In the long run, all basic settings shall be overwritable by magic comments. Then %withMagicComments contains just all settings. It is initialized with the basic settings and overwritten if an according magic comment is present.

The according getter withMagicComments() invoked without parameter returns a reference on the attribute. If it has a parameter, this is interpreted as a key, and it returns the value corresponding with the key.

$docClass

The attribute "$docClass" is written as side effect of init(). Currently not needed but in the long this may be valuable, e.g. double compilation of beamer and beamer article Getter function is docClass().

%docMeta

The attribute is written as side effect of _parseDocMetadataByNeed() invoked by init may be undef or empty which must be distinguished.

The according getter docMeta returns an undefined value if the attribute is undefined. Else invoked without parameter returns a reference on the attribute and if it has a parameter, this is interpreted as a key and it returns the value corresponding with the key.

$doNeedVerification

Initialized by _parseDocMetadataByNeed() to FALSE and _treatPdfStandards() to TRUE if really verifiation is needed. Indicates whether DocumentMetadata defines at least one pdfstandard which can be verified by the given verification tool.

The according getter is doNeedVerification().

$pdfFileDiff

Undefined in "init()" and defined in _initPdfMetadataHash() if diffing, i.e. reproduction is required (currently for PDF files only) and if a PDF file to be reproduced exists. In this case, $pdfFileDiff is the name of this file.

Used in "run_latex()" to find out whether the PDF to be created newly shall be reproduced and in run_onSuccessWarn() to check whether reproduction succeeded. To reproduce, "run_latex" invokes "getTimestampDiff()" to extract metadata from that PDF file (see "%metaPdfFlat" and "%metaPdfXmp"), and to this end, reads pdfFileDiff also.

The according getter is pdfFileDiff().

%metaPdfFlat

It contains metainfo in the info directory of "$pdfFileDiff" if defined and exists; else undefined in contrast to XMP metadata this is flat It is written as side effect of "init": undef directly, rest in "_initPdfMetadataHash" and it is used in "getTimestampDiff()" only like "%metaPdfXmp". Thus has no getter method.

%metaPdfXmp

It contains xmp metainfo of "$pdfFileDiff" if defined and exists; else undefined It is written as side effect of "init": undef directly, rest in "_initPdfMetadataHash" and it is used in "getTimestampDiff()" only like "%metaPdfFlat". Thus has no getter method.

FUNCTIONS

The functions of this package except getters/

init

# parses the tex file to find out 
# - magic comments which may modify basic settings 
#   The result initializes `withMagicComments`
# - documentmetadata which initializes `docMeta` 


# The pattern is used to read magic comments. 
# Double quotes because the pattern contains single quotes; 
# no interpolation

Used in Main::run_preDecideCompilation which is invoked by the hook Main::$compiling_cmd and initializes "SrcTargetDesc". Accordingly it parses the main tex file to find out magic coments, DocumentMetadata, the documentclass and other pieces of information. If

TBD: in fact, if it is clear that we only create PDF, then we could simplify: $fileName and the rest is by adding the ending. If not then we must add detection of the ending of the target and do only part of the functionality if no PDF file.

Inputs

$fileNameSrc

blabla

$fileNameTarget

blabla

_parseMagicComments()

Initializes "%withMagicComments" based on the basic settings and magic comments given by the parameter list overwriting the basic settings. The function is invoked by init() only, which recognizes the latex main file and in particular identifies the magic comments.

TBD: In the long run, each (general) setting shall be modifiable by a magic comment, so the whole parsing must be shifted into _parseMagicComments(). The attribute shall contain all settings then and the value is given by the magic comment if present, else by the basic setting.

Inputs

$programMagic

blabla

$chkDiffMagic

blabla

$chkDiffMagicVal

blabla

$$targetsMagic

blabla

Outputs

$chkDiff

blabla

_parseDocMetadataByNeed()

Initializes "%docMeta" and "$doNeedVerification" based on the scanned metadata $docMetadata read from DocumentMetadata.

If !defined $docMetadata then !defined "%docMeta" and "$doNeedVerification" = FALSE Else "%docMeta" has at least values for xmp and tagging given implicitly or explicitly. Also key uncompressed is recorded. Note it has no value. Special is the key `pdfstandard` which is treated separately in _treatPdfStandards().

if !defined "%docMeta" or contains no value for `pdfstandards`, "$doNeedVerification" is false but also if the verification tool cannot verify any of the prescribed standards.

May throw a variety of warnings concerning metadata.

Inputs

$docMetadata

Warnings

DMxx: Expected no value for key '$key' but found '$value'.
DMxx: Found key '$key' more than once.
DMxx: Ignoring key '$key' without expected value, compiler behavior is unspecified.
DMxx: Overwritten value '$docMeta{$key}' by '$value' for key '$key'.
DMxx: Found preliminary tagging status 'draft'.

_treatPdfStandards()

Invoked in _parseDocMetadataByNeed only which ensures that $docMeta{pdfstandard} is defined. In this case,

_initPdfMetadataHash()

Presupposes that $pdfFileDiffE is defined and exists initializes "$pdfFileDiff", "%metaPdfFlat" and "%metaPdfXmp" which were undefined before

Inputs

$pdfFileDiffE

blabla

getTimestampDiff()

Used in Main::run_latex to run with the correct timestamp

package main

blablabla

Rules and Functions

run_latex

blablabla

blablabla

blablabla

blablabla

blablabla

Transforming aux to glstex* via run_bib2gls

blablabla

Hooks and Functions

Code latexmk invokes hooks at certain events. Most of these hooks invoke just internal functions.

Hook $main::compiling_cmd and function run_preDecideCompilation

The hook $main::compiling_cmd is defined by the internal function run_preDecideCompilation

Inputs

$sourceBase

The base name of the main TEX file.

$target

The target file to be created with ending.

Hook $main::success_cmd and function run_onSuccess

The hook $main::success_cmd is defined by the internal function run_onSuccess which in turn invokes

Inputs

$source

blabla

$target

blabla

Function run_onSuccessWarn for hooks success_cmd and warning_cmd

The hook success_cmd is defined by the internal function run_onSuccess and the hook warning_cmd is defined by the internal function run_onWarn both of which invoke run_onSuccessWarn.

Inputs

$target

blabla

$main::failure_cmd

In case of a failure, currently no function is invoked, just a failure messgage is echoed.