/*
    * The akquinet maven-latex-plugin project
    *
    * Copyright (c) 2011 by akquinet tech@spree GmbH
    *
    * Licensed under the Apache License, Version 2.0 (the "License");
    * you may not use this file except in compliance with the License.
    * You may obtain a copy of the License at
    *
   * http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  package eu.simuline.m2latex.core;
  
  import java.io.File;
  import java.io.FileFilter;
  import java.io.IOException;
  import java.io.InputStream;
  import java.io.PrintStream;
  import java.time.Instant;
  import java.time.ZonedDateTime;
  import java.util.ArrayList;
  import java.util.Collection;
  import java.util.List;
  import java.util.Map;
  import java.util.TreeMap;
  import java.util.Optional;
  import java.util.Set;
  import java.util.SortedSet;
  import java.util.TreeSet;
  
  import com.florianingerl.util.regex.Matcher;
  import com.florianingerl.util.regex.Pattern;
  
  //import java.util.regex.Pattern;
  //import java.util.regex.Matcher;
  
  import eu.simuline.m2latex.core.CommandExecutor.CmdResult;
  // TBD: all this must be eliminated.
  // import eu.simuline.m2latex.antTask.LatexCfgTask;
  // import eu.simuline.m2latex.antTask.LatexClrTask;
  import eu.simuline.m2latex.mojo.CfgLatexMojo;
  // import eu.simuline.m2latex.mojo.ChkMojo;
  // import eu.simuline.m2latex.mojo.ClearMojo;
  // import eu.simuline.m2latex.mojo.GraphicsMojo;
  
  // idea: use latex2rtf and unoconv
  // idea: targets for latex2html, latex2man, latex2png and many more.
  
  // TBD: rework
  /**
   * The latex processor creates various output from latex sources
   * including also preprocessing of graphic files in several formats.
   * This is the core class of this piece of software.
   * The main method is {@link #create(SortedSet<Target>)} which is executed by
   * the ant task
   * and by the maven plugin given by { @link CfgLatexMojo}.
   * Also important are {@link #clearAll()} which is executed by
   * the maven plugin given by { @link ClearMojo}.
   * also {@link #processGraphics()} which is executed by
   * the maven plugin given by { @link GraphicsMojo}
   * which is helpful for information development.
   * <p>
   * This class delegates preprocessing of the graphic files,
   * selection of the latex main files and deleting their targets
   * to {@link LatexPreProcessor}.
   * Processing of the latex main files is done in
   * {@link #create(SortedSet<Target>)}
   * according to the target(s) given by the parameters.
   * The elements of the enumeration {@link Target} use methods
   * {@link #processLatex2rtf(LatexMainDesc)},
   * {@link #processLatex2dvi(LatexMainDesc)},
   * {@link #processLatex2pdf(LatexMainDesc)},
   * {@link #processLatex2html(LatexMainDesc)},
   * {@link #processLatex2odt(LatexMainDesc)},
   * {@link #processLatex2docx(LatexMainDesc)}
   * and {@link #processLatex2txt(LatexMainDesc)}.
   */
  public class LatexProcessor extends AbstractLatexProcessor {
  
  
  
  
    // Note that two \\ represent a single \ in the string.
    // Thus \\\\ represents '\\' in the pattern,
    // which in turn represents a single \.
    static final String PATTERN_OUFULL_HVBOX = "^(Ov|Und)erfull \\\\[hv]box \\(";
  
    // LaTeX (notably, .tex is not needed )
    final static String SUFFIX_TOC = ".toc";
    final static String SUFFIX_LOF = ".lof";
    final static String SUFFIX_LOT = ".lot";
    final static String SUFFIX_LOL = ".lol";
 
   final static String SUFFIX_AUX = ".aux";
   final static String SUFFIX_DVI = ".dvi";
   final static String SUFFIX_XDV = ".xdv";
 
   // bibtex
   final static String SUFFIX_BLG = ".blg";
   final static String SUFFIX_BBL = ".bbl";
 
   // makeindex for index
   // unsorted and not unified index created by latex
   final static String SUFFIX_IDX = TexFileUtils.SUFFIX_IDX;
   // sorted and unified index created by makeindex
   final static String SUFFIX_IND = TexFileUtils.SUFFIX_IND;
   // log file created by makeindex
   final static String SUFFIX_ILG = TexFileUtils.SUFFIX_ILG;
 
   // sorted and unified glossary created by makeindex
   final static String SUFFIX_GLS = ".gls";
   // logging file for makeindex used with glossaries
   final static String SUFFIX_GLG = ".glg";
 
 
   // logging file for pythontex written by pythontexW
   final static String SUFFIX_PLG = ".plg";
 
 
   // file in PREFIX_PYTEX_OUT_FOLDER 
   // created by auxiliary program pythontex
   private final static String SUFFIX_PYTXMCR = ".pytxmcr";
 
   // latex2rtf
   private final static String SUFFIX_RTF = ".rtf";
 
   // odt2doc
   private final static String SUFFIX_ODT = ".odt";
 
   // tex4ht
   // FIXME: works for unix only
   final static String SUFFIX_HTML = ".html";
 
   // pdftotext
   private final static String SUFFIX_TXT = ".txt";
 
   // ChkTeX: log file
   private final static String SUFFIX_CLG = ".clg";
 
   /**
    * The implicit default identifier of an index
    * hardcoded into the package <code>splitidx</code>
    * and into the program <code>splitindex</code>.
    */
   private final static String IMPL_IDENT_IDX = "idx";
 
   /**
    * Separator <code>-</code> of the index identifier
    * used in files <code>xxx-yy.idx</code>, <code>xxx-yy.ind</code>
    * and <code>xxx-yy.ilg</code>.
    * This is hardcoded by the package <code>splitidx</code>
    * when reading <code>xxx-yy.ind</code> files
    * but is configurable as an option in the program <code>splitindex</code>.
    */
   private final static String SEP_IDENT_IDX = "-";
 
   private final ParameterAdapter paramAdapt;
 
   /**
    * The graphics preprocessor used by this processor.
    */
   private final LatexPreProcessor preProc;
 
   /**
    * The meta info provider used by this processor.
    */
   private final MetaInfo metaInfo;
 
   /**
    * An <code>Optional</code> which contains the name of a latex2pdf converter 
    * while processing a latex file specifying such a converter 
    * in a magic comment. 
    * Else this <code>Optional</code> is empty. 
    */
   private Optional<String> latex2PdfCmdMagic = Optional.empty();
 
   /**
    * Index of the group in {@link Settings#patternMultiIndex}
    * containing the string <code>\indexentry</code>. 
    * The default is 3 and this may hardly change. 
    */
   final static int GRP_IDX_KEYPAGE = 3;
 
   /**
    * Index of the group in {@link Settings#patternMultiIndex}
    * containing the identifier of the index. 
    * The default is 2 and this may hardly change. 
    */
   final static int GRP_IDX_IDENT = 2;
 
   /**
    * Index of the group in {@link Settings#patternMultiIndex}
    * containing the string <code>\indexentry</code>. 
    * The default is 1 and this may hardly change. 
    */
   final static int GRP_IDX_IDXENTRY = 1;
 
 
   // also for tests
   LatexProcessor(Settings settings, CommandExecutor executor, LogWrapper log,
       TexFileUtils fileUtils, ParameterAdapter paramAdapt) {
     super(settings, executor, log, fileUtils);
     this.paramAdapt = paramAdapt;
     this.preProc = new LatexPreProcessor(this.settings, this.executor, this.log,
         this.fileUtils);
     this.metaInfo = new MetaInfo(this.executor, this.log);
     this.latex2PdfCmdMagic = Optional.empty();
   }
 
   /**
    * Creates a LatexProcessor with parameters given by <code>settings</code>
    * which logs onto <code>log</code> and used by <code>paramAdapt</code>.
    *
    * @param settings
    *    the settings controlling latex processing
    * @param log
    *    the logger to write on events while processing
    * @param paramAdapt
    *    the parameter adapter, refers to maven-plugin or ant-task.
    */
   public LatexProcessor(Settings settings, LogWrapper log,
       ParameterAdapter paramAdapt) {
     this(settings, new CommandExecutor(log), log, new TexFileUtils(log),
         paramAdapt);
   }
 
   /**
    * Returns the set of targets to be built. 
    * If <code>desc</code> indicates 
    * that the TEX file specifies targets via a magic comment, 
    * then this is the build target to be returned. 
    * <p>
    * Else, the target set from the configuration, <code>targetSet/code> 
    * is the base. 
    * If <code>docClasses2Targets</code> excludes targets 
    * for the document class specified by <code>desc</code>, 
    * this must be taken into account also. 
    * @param desc
    *    the description of the main file to be built. 
    *    In this context, the document class is relevant 
    *    and optionally the targets. 
    * @param docClasses2Targets
    *    reflects the according setting. 
    * @param targetSet
    *    reflects the setting 'targets' for goal <code>cfg</code> 
    *    or the one element target set given by the goal directly. 
    * @return 
    *    the set of targets to be built. 
    * @throws BuildFailureException
    */
   Set<Target> getTargetsForBuild(LatexMainDesc desc,
                                   Map<String, Set<Target>> docClasses2Targets,
                                   SortedSet<Target> targetSet)
       throws BuildFailureException {
 
     Optional<String> targetsMagic =
         desc.groupMatch(LatexMainParameterNames.targetsMagic);
     if (targetsMagic.isPresent()) {
       this.log.info("Magic comment 'targets=" + targetsMagic.get() + "' overrides settings. ");
       return Settings.getTargets(targetsMagic.get(),
           TargetsContext.targetsMagic);
     }
     // Here, the targets are not given by a magic comment 
     // Thus they come from the setting targets 
     // combined with the targets giben by docClasses2Targets and docClass 
 
     //String docClassOpt = desc.getDocClass();
     // if (docClassOpt.isEmpty()) {
     //   this.log.warn("WLPXX: For file '" + desc.texFile
     //       + "' targets are not restricted by unknown document class. ");
     //   reachableTargets = targetSet;
     // } else {
 
     String docClass = desc.getDocClass();
     Set<Target> possibleTargets = docClasses2Targets.get(docClass);
     if (possibleTargets == null) {
       // Here, to docClass no restriction is attached 
       this.log.warn("WLP09: For file '" + desc.texFile
           + "' targets are neither specified by magic comment nor restricted by document class '" + docClass
           + "'. ");
       return targetSet;
     }
     // Here, targetSet must be intersected with the targets possible for the docClass 
     Set<Target> unreachableTargets = new TreeSet<Target>(targetSet);
     unreachableTargets.removeAll(possibleTargets);
     if (!unreachableTargets.isEmpty()) {
       this.log.info("Skipping targets " + unreachableTargets + ". ");
     }
     Set<Target> reachableTargets = new TreeSet<Target>(targetSet);
     reachableTargets.retainAll(possibleTargets);
     return reachableTargets;
 
     //}
   }
 
   // TBD: rework 
   /**
    * Defines creational ant-task defined in { @link LatexCfgTask} 
    * and the according goals in { @link CfgLatexMojo} 
    * and subclasses of the maven plugin. 
    * <p>
    * This consists in reading the parameters 
    * via {@link ParameterAdapter#initialize()} 
    * processing graphic-files 
    * via {@link LatexPreProcessor#processGraphicsSelectMain(File, DirNode, boolean)} 
    * and processing the tex main files 
    * via {@link Target#processSource(LatexProcessor, LatexMainDesc)}. 
    * If a diff-tool for the target format is available
    * and if check by diff is specified, 
    * the resulting file is checked to be equal to a specified file. 
    * A {@link BuildFailureException} is thrown 
    * if the files are not equal according to the diff tool. 
    * The resulting files are identified by its suffixes 
    * via  {@link Target#getPatternOutputFiles(Settings)}. 
    * If no exception occurs before, they are copied to the target folder. 
    * Finally, by default a cleanup is performed 
    * invoking {@link TexFileUtils#cleanUp(DirNode, File, String)}. 
    * <p>
    * Logging: 
    * <ul>
    * <li> WFU01: Cannot read directory... 
    * <li> WFU03: cannot close file 
    * <li> EFU05: Cannot delete file 
    * <li> EFU07, EFU08, EFU09: if filtering a file fails. 
    * <li> WPP02: tex file may be latex main file 
    * <li> WPP03: Skipped processing of files with suffixes ... 
    * <li> EEX01, EEX02, EEX03, WEX04, WEX05: 
    *      applications for preprocessing graphic files 
    *      or processing a latex main file fails. 
    * </ul>
    *
    * FIXME: exceptions not really clear. 
    * 
    * @param targetSet
    *    the set of targets to be created. 
    *    The target 'chk' does not create artifacts except the log file clg. 
    *    The target set may have a single entry coming from the goal 
    *    or, for goal {@link CfgLatexMojo} 
    *    may be given by {@link Settings#getTargets()}. 
    * @throws BuildFailureException 
    *    <ul>
    *    <li> TSS01 if 
    *    the tex source directory does either not exist 
    *    or is not a directory. 
    *    <li> TSS02 if 
    *    the tex source processing directory does either not exist 
    *    or is not a directory. 
    *    <li> TSS03 if 
    *    the output directory exists and is no directory. 
    *    <li> TSS04 if
    *    the target set is not a subset of the set given by {@link Target}.
    *    <li> TEX01 if 
    *    invocation of applications for preprocessing graphic files 
    *    or processing a latex main file fails 
    *    <li> TFU01 if 
    *    the target directory that would be returned 
    *    exists already as a regular file. 
    *    <li> TFU03, TFU04, TFU05, TFU06 if 
    *    copy of output files to target folder fails. 
    *    For details see 
    *    {@link TexFileUtils#copyOutputToTargetFolder(File, FileFilter, File)}
    *    <li>TLP01 if difference check is specified in settings and if 
    *    the artifact could not be reproduced (currently for pdf only). 
    *    <li>WPP05: Included tex files which are no latex main files 
    *    <li>WPP06: Included tex files which are no latex main files 
    *    <li>WPP07: inluded/excluded files not identified by their names.
    *    <li>TBD: complete. 
    *    </ul>
    */
   public void create(SortedSet<Target> targetSet) throws BuildFailureException {
 
     // TBD: clarify whether this is superfluous 
     this.paramAdapt.initialize();
     this.log.info("-----------create-------------");
     this.log.debug("Settings: " + this.settings.toString());
 
     // may emit WSS01, WSS02 TBD: correct 
     // may throw BuildFailureException TSS04, TSS11, TBD: complete. 
     Map<String, Set<Target>> docClasses2Targets =
         this.settings.getDocClassesToTargets();
 
     // may throw BuildFailureException TSS01
     File texDir = this.settings.getTexSrcDirectoryFile();
     assert texDir.exists()
         && texDir.isDirectory() : "Expected existing tex folder " + texDir;
 
     // may throw BuildFailureException TSS02
     File texProcDir = this.settings.getTexSrcProcDirectoryFile();
     assert texProcDir.exists() && texProcDir
         .isDirectory() : "Expected existing tex processing folder " + texDir;
 
     // constructor DirNode may log warning WFU01 Cannot read directory
     DirNode node = new DirNode(texProcDir, this.fileUtils);
     try {
       // does two things at the same time 
       // - determine latexMainFiles 
       // - process graphics if preProcessInternally()
       // may throw BuildFailureException TEX01,
       // log warning WFU03, WPP02, WPP03,
       // EEX01, EEX02, EEX03, WEX04, WEX05, EFU07, EFU08, 
       //    EFU09: if filtering a file fails.
       Collection<LatexMainDesc> latexMainDescs =
           this.preProc.processGraphicsSelectMain(texProcDir, node, 
           this.settings.getLatexmkUsage().preProcessInternally());
 
       for (LatexMainDesc desc : latexMainDescs) {
         File texFile = desc.texFile;
         this.log.info("Processing LaTeX file '" + desc.texFile + "'. ");
 
         // throws BuildFailureException TFU01
         // if targetDir would be an existing non-directory
         File targetDir = this.fileUtils.getTargetDirectory(texFile, texDir,
             // throws BuildFailureException TSS03
             // if exists and is no dir
             this.settings.getOutputDirectoryFile());
         assert !targetDir.exists()
             || targetDir.isDirectory() : "Expected target folder " + targetDir
                 + " folder if exists. ";
 
         Set<Target> targetsForBuild =
           getTargetsForBuild(desc, docClasses2Targets, targetSet);
         // currently, this is the only magic comment applying to all targets 
         // even that is not really true: htlatex vs xhtlatex 
         // and targets like txt 
         // but chkDiff and latexmk are specific for target pdf 
         // and targets is more globally and a special case. 
         this.latex2PdfCmdMagic = desc
           .groupMatch(LatexMainParameterNames.programMagic);
         if (this.latex2PdfCmdMagic.isPresent()) {
           // TBD: this comes before message converting to pdf: file. 
           // Better: 
           // - processing file.. 
           // - then targets 
           if (!this.latex2PdfCmdMagic.get().equals(this.settings.getCommand(ConverterCategory.LaTeX))) {
             this.log.info("Magic comment 'program=" + this.latex2PdfCmdMagic.get() + "' overrides settings.");
           }
         }
 
         // may throw BuildFailureException TSS04
         for (Target target : targetsForBuild) {
           Optional<File> pdfFileCmpOpt = Optional.empty();
           // Do it really, if an original artifact exists
 
           // Pattern patStd = Pattern.compile("^.*pdfstandard.*$");
           // boolean claimsStd = patStd.matcher(docMetadataString).matches();
           MetaData docMeta = docMetadata(desc);
           if (!docMeta.isSpecMetadata()) {
             this.log.debug("No DocumentMetadata.");
           }
           Optional<String> stdX = docMeta.claimedStandard(StdType.x);
           if (stdX.isPresent()) {
             this.log.warn("Specified standard " + stdX.get() + " which cannot be verified. ");// TBD: identifier 
           }
           Optional<String> stdA = docMeta.claimedStandard(StdType.a);
           if (stdA.isPresent()) {
             this.log.info("Specified standard " + stdA.get() + " to be verified later. ");
           }
           Optional<String> stdU = docMeta.claimedStandard(StdType.ua);
           if (stdU.isPresent()) {
             if (docMeta.tagging == TaggingState.on) {
               this.log.info("Specified standard " + stdU.get() + " to be verified later. ");
             } else {
               this.log.warn("Specified standard " + stdU.get() + " without tagging; verification will fail. ");// TBD: identifier 
             }
           }
 
           //boolean claimsStd = docMeta.claimsSomeStandard();
           // if (claimsStd) {
           //   this.log.info("DocumenMetadata specifies standard.");
           // } else {
           //   this.log.info("DocumenMetadata does not specify standard.");
           // }
 
           if ((stdX.isPresent() || stdA.isPresent() || stdU.isPresent()) && !docMeta.withXMP) {
             this.log.warn("Specified standard without XMP. ");
           }
 
 
 
 
           boolean doTryVeri = target.hasVerificationTool() && (stdA.isPresent() || stdU.isPresent());
           boolean doTryDiff = target.hasDiffTool() && isChkDiff(desc);
           if (doTryDiff) {
             File pdfFileCmp = TexFileUtils.getPdfFileDiff(desc.pdfFile,
                 this.settings.getTexSrcDirectoryFile(),
                 this.settings.getDiffDirectoryFile().getAbsoluteFile());
             this.log.debug(String.format("cmp file %s", pdfFileCmp));
             pdfFileCmpOpt = Optional.of(pdfFileCmp);
 
             // assert pdfFileCmp.exists();
             if (pdfFileCmp.exists()) {
               //runPdfInfo(desc.pdfFile);
               long timestampSec = runPdfInfo(pdfFileCmp);
 
               this.log.info("Process with timestamp "
                     + Instant.ofEpochSecond(timestampSec)
                     + " (" + timestampSec + "sec)");
 
               assert pdfFileCmpOpt.isPresent();
               this.executor.envSetTimestampAndTZutc(timestampSec);
             } else {
               // just a placeholder to signify that a reproducible artifact must be created 
               // but there is no original 
               this.executor.envUtc();
               this.log.info("Process with time zone UTC. ");
             }
           } else {
             this.executor.envReset();
             // process with empty environment: neither timestamp nor timezone 
           }
           // Here, metaDataDescOpt is either 
           // - empty meaning no diff requested 
           // - not empty but without timestamp 
           //   meaning shall be reproducible, i.e. env=TZ
           // - not empty with timestamp 
           //   meaning reproducible with timestamp 
           //   i.e. env=TZ, SOURCE_DATE_EPOCH, FORCE_SOURCE_DATE 
           //   Strictly speaking, FORCE_SOURCE_DATE not needed for DVI2PDF 
 
           // may throw BuildFailureException TEX01,
           // log warning EEX01, EEX02, EEX03, WEX04, WEX05
           //target.processSource(this, desc, timestampOpt);
 
           // perform the proper processing 
           target.processSource(this, desc);
 
           // copy the resulting artifacts to the target folder 
           FileFilter fileFilter = TexFileUtils.getFileFilter(texFile,
               target.getPatternOutputFiles(this.settings), false);
           // may throw BuildFailureException
           // TFU03, TFU04, TFU05, TFU06
           // may log warning WFU01 Cannot read directory
           Set<File> targetFiles = this.fileUtils
               .copyOutputToTargetFolder(texFile, fileFilter, targetDir);
 
           // Here, we assume that targets viable for verification and comparison
           // have a single file as an artifact
           if (targetFiles.size() != 1) {
             continue;
           }
 
           File pdfFileAct = targetFiles.iterator().next();
           this.log.debug(String.format("act file %s", pdfFileAct));
           if (!pdfFileAct.exists()) {
             // Here, the logging is done already above
             continue;
           }
 
           // // but this shall be clear also above before trying to copy to target folder
           // boolean coincideChecked = runDiffPdf(pdfFileCmpOpt.get(), pdfFileAct);
           // null: not checked, else the result of the check as a boolean. 
           Boolean coincideChecked = diffByNeedAndReturnEqual(doTryDiff, pdfFileAct, pdfFileCmpOpt);
 
           // Of course, verification can be done only if supported by the target. 
           // If so, for !this.settings.getVerifyByCmp(), validation must be run. 
           // else, it must only be done if no check, i.e. coincideChecked==null:
           // or comparison did not yiels confirmation that the files coincide 
           if (doTryVeri 
             && (!this.settings.getVerifyByCmp() || coincideChecked == null || !coincideChecked)) {
             runValidatePdf(desc);
           }
 
           // for coincideChecked == null diffByNeedAndReturnEqual emitted an according warnind already
           if (coincideChecked != null && !coincideChecked) {
             throw new BuildFailureException(
                 "TLP01: Artifact '" + pdfFileAct.getName() +
                     "' from '" + texFile + "' could not be savely reproduced. ");
           }
         } // target
       } // texFile
     } finally {
       if (this.settings.isCleanUp()) {
         // may log warning WFU01, EFU05
         this.fileUtils.cleanUp(node, texProcDir, this.settings.getPrefixPytexOutFolder());
       }
       this.log.debug(this.settings.isCleanUp() ? ("cleanup: " + texProcDir)
           : "No cleanup");
       this.latex2PdfCmdMagic = Optional.empty();// superfluous
     }
   }
 
   /**
    * Runs {@link #runDiffPdf(File, File)} by need 
    * and returns whether the comparison was not executed, passed for failed. 
    * Note that currently, a diff is performed for PDF files only. 
    * 
    * @param doTryDiff
    *    whether a diff check was resquested, i.e. possible by target (PDF only) 
    *    and requested globally or particularly for the actual document. 
    * @param pdfFileAct
    *    The actual PDF file 
    * @param pdfFileCmpOpt
    *    An Optional carrying another PDF file for comparison, if available. 
    * @return 
    *    <code>null</code> if it was not tried to compare. 
    *    This is if <code>doTryDiff</code> is false 
    *    or if <code>pdfFileCmpOpt</code> contains not original PDF file for comparison. 
    *    Else it returns whether the trial succeeded and showed equality. 
    * @throws BuildFailureException
    *      TEX01 if invocation of the diff command failed. 
    */
   private Boolean diffByNeedAndReturnEqual(boolean doTryDiff,
       File pdfFileAct,
       Optional<File> pdfFileCmpOpt)
       throws BuildFailureException {
     if (!doTryDiff) {
       this.log.debug("No artifact diff specified.");
       return null;
     }
 
     File pdfFileCmp = pdfFileCmpOpt.get();
     if (!pdfFileCmp.exists()) {
       // TBD: adapt identifier of warning
       // THis shall occur only if a newly created or changed file shall be
       // reproducible
       // in the message: 'Modification of reproducible file?' - add artifact as
       // original file '
       // TBD: pdfFileCmp is absolute but shall be relative to project base directory
       this.log.warn("TLP02: Add file '" + pdfFileCmp
           + "' to compare with artifact '" + pdfFileAct + "'! ");
       return null;
     }
     this.log.debug("Prepare verification by diffing: ");
 
     // but this shall be clear also above before trying to copy to target folder
     // may throw BuildFailureException 
     boolean coincideChecked = runDiffPdf(pdfFileCmpOpt.get(), pdfFileAct);
     if (coincideChecked) {
       this.log.info("Checked result: coincides with expected artifact. ");
     }
     return coincideChecked;
   }
 
   // TBD: rework documentation 
   /**
    * Returns whether the pdf file under construction 
    * is going to be checked whether an original is reproduced. 
    * If the magic comment <code>% !LMP chkDiff...</code> is set, 
    * it takes precedence over {@link Settings#isChkDiff()} 
    * which determines whether checks are performed 
    * only if there is no magic comment. 
    * The magic comment has two variants: 
    * besides the one with boolean values, 
    * also one without value which defaults to boolean true value. 
    * <p>
    * This applies to all kinds of compilation, 
    * except for latexmk 
    * 
    * @param desc
    *   description of a TEX file. 
    * @return
    *   whether the PDF file under construction  
    *   is checked to reproduced the original  
    *   This is determined via magic comment or, 
    *   if not present, via settings. 
   * @see #buildLatexmkArguments(Settings, LatexMainDesc)
    */
   private boolean isChkDiff(LatexMainDesc desc) {
     boolean chkDiffSetting = this.settings.isChkDiff();
     if (!desc.groupMatches(LatexMainParameterNames.chkDiffMagic)) {
       // Here, result is according to setting 
       return chkDiffSetting;
     }
     // Here, the magic comment overrides the settings 
     Optional<String> chkDiffValue = 
     desc.groupMatch(LatexMainParameterNames.chkDiffMagicVal);
     boolean chkDiff = chkDiffValue.isEmpty() 
     ? true 
     : Boolean.parseBoolean(chkDiffValue.get());
     if (chkDiff != chkDiffSetting) {
       this.log.info("Magic comment 'chkDiff=" + chkDiff + "' overrides setting.");
     }
     return chkDiff;
   }
 
   /**
    * Represents the values of tagging in DocumentMetadata. 
    */
   static enum TaggingState {
     /**
      * Tagging is active. 
      */
     on,
     /**
      * Tagging is not active. 
      */
     off,
     /**
      * Tagging commands are active emitting warnings by need, 
      * but finally the tagging structure is not written to the final output. 
      */
     draft;
   } // enum TaggingState 
 
   static enum StdType {
     ua, a, x;
   } // enum StdType 
 
   /**
    * Represents the settings in DocumentMetadata. 
    * This means that all data is a request not reality. 
    * For example, standards are only claimed, not validated. 
    * Some aspects, as compression should be quite reliable, 
    * whereas for example the pdfversion can be manipulated. 
    */
   static class MetaData {
 
     // TBD: value must admit also nested braces
     private static final Pattern PATTERN_METADATA = Pattern
         .compile("(\\s*,\\s*)?(?<key>[-a-z]+)(?:\\s*=\\s*(?<value>[^{}, ]+|\\{[^{}]*\\}))?");
 
     private static final String KEY_PDFVERSION = "pdfversion";
     private static final String KEY_UNCOMP = "uncompress";
     private static final String KEY_STD = "pdfstandard";
     private static final String KEY_XMP = "xmp";
     private static final String KEY_TAGGING = "tagging";
 
 
     final static MetaData NO_METADATA = new MetaData(KEY_XMP + "=" +false);
     /**
      * The version as an optional which is empty if the version is not given explicitly. 
      */
     final Optional<String> pdfversion;
 
     final boolean isCompressed;
 
     //EnumSet<PdfStandard> standards;
 
     final boolean withXMP;
     final TaggingState tagging;
 
 
 
     private final Map<String, String> key2value;
 
     private static String unwrap(String str) {
       str = str.trim();
       return  (str.startsWith("{") && str.endsWith("}"))
         ? str.substring(1,str.length()-1)
         : str;
     }
 
     MetaData(String docMetadataString) {
       this.key2value = new TreeMap<String, String>();
       Matcher matcher = PATTERN_METADATA.matcher(docMetadataString);
       String key, value;
       while (matcher.find()) {
         key = matcher.group("key");
         value = matcher.group("value");
         System.out.println("key: |" + key + "| value: |" + value + "|");
         switch (key) {
           case KEY_STD:
             String org = this.key2value.get(KEY_STD);
             value = unwrap(value).toLowerCase();
             if (org == null) {
               this.key2value.put(KEY_STD, value);
 
             } else {
               this.key2value.put(KEY_STD, org + "," + value);
             }
             continue;
           case KEY_UNCOMP:
             assert value == null;
             // continue; fallthrough
           default:
             this.key2value.put(key, value);
         } // switch
       } // while 
 
       // no action for 'backend'
       // pdfversion may be given explicitly or not 
       this.pdfversion = this.key2value.containsKey(KEY_PDFVERSION)
       ? Optional.of(this.key2value.get(KEY_PDFVERSION))
       : Optional.empty();
       // uncompression TBD: there is a second way to reach this. 
       this.isCompressed = !this.key2value.containsKey(KEY_UNCOMP);
 
 
       // xmp 
       this.withXMP = this.key2value.containsKey(KEY_XMP)
           ? Boolean.parseBoolean(this.key2value.get(KEY_XMP))
           : true; // the default value.
 
       // tagging 
       this.tagging = this.key2value.containsKey(KEY_TAGGING)
         ? TaggingState.valueOf(this.key2value.get(KEY_TAGGING))
         : TaggingState.off;
  
       // value may be well null but only for uncompress,
       // currently, this is not checked.
       // for pdfstandard, the key may repeat.
       // currently this is just overwritten.
 
     } // MetaData 
 
     // Set<String> getClaimedStandard(String xaua) {
 
     // }
 
     // boolean claimsSomeStandard() {
     //   return this.key2value.containsKey(KEY_STD);
     // }
 
     boolean isSpecMetadata() {
       return this != NO_METADATA;
     }
 
     Optional<String> claimedStandard(StdType stdType) {
       String stdsStr = this.key2value.get(KEY_STD);
       //System.out.println("stdsStr: "+stdsStr);
       if (stdsStr == null) {
         return Optional.empty();
       }
       Matcher matcher = Pattern
         .compile(String.format("^(.*,)?(?<std>%s-\\d+[a-z]*)", stdType.toString()))
         .matcher(stdsStr);
       return matcher.find()
         ? Optional.of(matcher.group("std"))
         : Optional.empty();
       //boolean found = matcher.find();
       // if (found) {
       //   return Optional.of(matcher.group("std"));
       // } else {
       //   return Optional.empty();
       // }
     }
 
   } // class MetaData 
 
 
 
   private MetaData docMetadata(LatexMainDesc desc) {
     //boolean chkDiffSetting = this.settings.isChkDiff();
     if (!desc.groupMatches(LatexMainParameterNames.docMetadata)) {
       // Here, no metadata at all, so no claim 
       //this.log.info("No DocumentMetadata.");
       return MetaData.NO_METADATA;
     }
     // Here, metadata are given 
     // TBD: make this more precise later. 
     Optional<String> docMetadataValue = 
     desc.groupMatch(LatexMainParameterNames.docMetadata);
     String docMetadataString = docMetadataValue.get();
 
 System.out.println("docMetadata: |"+docMetadataString+"|");
      return new MetaData(docMetadataString);
   }
 
   /**
    * Returns whether the tex file under consideration 
    * is going to be compiled using {@link Converter#Latexmk}. 
    * If the magic comment <code>% !LMP latexmk..</code> is set, 
    * it takes precedence over {@link Settings#getLatexmkUsage()} 
    * which determines among other whether latexmk is used. 
    * The magic comment has two variants: 
    * besides the one with boolean values, 
    * also one without value which defaults to boolean true value. 
    * <p>
    * This applies to all kinds of compilation, 
    * except for latexmk 
    * 
    * @param desc
    *   description of a TEX file. 
    * @return
    *   whether the tex file under consideration 
    *   is going to be compiled using {@link Converter#Latexmk}. 
    *   This is determined via magic comment or, 
    *   if not present, via settings. 
    * @see #processLatex2pdf(LatexMainDesc)
    */
   // TBD: generalize together with isChkDiff
   private boolean isCompileWithLatexmk(LatexMainDesc desc) {
     boolean runLatexmkSetting = this.settings.getLatexmkUsage().runLatexmk();
     if (!desc.groupMatches(LatexMainParameterNames.latexmkMagic)) {
       return runLatexmkSetting;
     }
     // Here, the magic comment overrides the settings 
     Optional<String> runLatexmkValue = 
     desc.groupMatch(LatexMainParameterNames.latexmkMagicVal);
     boolean runLatexmk = (runLatexmkValue.isEmpty())
     ? true
     : Boolean.parseBoolean(runLatexmkValue.get());
     if (runLatexmk != runLatexmkSetting) {
       this.log.info("Magic comment 'latexmk="+runLatexmk+"' overrides settings. ");
     }
     return runLatexmk;
   }
 
   // TBD: rework 
   /*
    * Defines check goal of the maven plugin in { @link ChkMojo}.
    * This includes also creation of graphic files.
    * <p>
    * TBD: logging
    * <ul>
    *    <li>WPP05: Included tex files which are no latex main files 
    *    <li>WPP06: Included tex files which are no latex main files 
    *    <li>WPP07: inluded/excluded files not identified by their names.
    * </ul>
    * 
    * @throws BuildFailureException
    *    <ul>
    *    <li>
    *    TSS02 if the tex source processing directory
    *    does either not existor is not a directory.
    *    <li>
    *    TEX01 invoking FIXME
    *    </ul>
    */
   // used in ChkMojo.execute() only
   // FIXME: maybe sufficient not to create graphics, if no \input.
   // Also, maybe good not to remove log file
   // maybe good to make suffix configurable rather than hardcoded.
   // public void checkAll() throws BuildFailureException {
 
   //     this.paramAdapt.initialize();
   //     this.log.debug("Settings: " + this.settings.toString());
 
   //     // may throw BuildFailureException TSS02
   //     File texProcDir = this.settings.getTexSrcProcDirectoryFile();
   //     assert texProcDir.exists() && texProcDir.isDirectory()
   //             : "Expected existing tex processing folder " + texProcDir;
 
   //     // constructor DirNode may log warning WFU01 Cannot read directory
   //     DirNode node = new DirNode(texProcDir, this.fileUtils);
 
   //     try {
   //         // TBD: eliminate processing graphics. 
   //         // may throw BuildFailureException TEX01,
   //         // log warning WFU03, WPP02, WPP03,
   //         // EEX01, EEX02, EEX03, WEX04, WEX05, EFU07, EFU08, EFU09
   //         Collection<File> latexMainFiles = this.preProc
   //                 .processGraphicsSelectMain(texProcDir, node);
 
   //         for (File latexMain : latexMainFiles) {
   //             processCheck(getLatexMainDesc(latexMain));
   //         }
   //     } finally {
   //         // FIXME: also removes the clg-files
   //         if (this.settings.isCleanUp()) {
   //             // may log warning WFU01, EFU05
   //             this.fileUtils.cleanUp(node, texProcDir);
   //         }
   //     }
   // }
 
   // TBD: rework 
   /**
    * Defines graphics goal of the maven plugin in { @link GraphicsMojo}.
    * <p>
    * Logging:
    * <ul>
    * <li>WFU01: Cannot read directory
    * <li>WFU03: cannot close file
    * <li>EFU07, EFU08, EFU09: if filtering a file fails.
    * <li>WPP02: tex file may be latex main file
    * <li>WPP03: Skipped processing of files with suffixes ...
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * if running graphic processors failed.
    * <li>WPP05: Included tex files which are no latex main files 
      * <li>WPP06: Included tex files which are no latex main files 
      * <li>WPP07: inluded/excluded files not identified by their names.
    * </ul>
    *
    * @throws BuildFailureException
    *    <ul>
    *    <li>
    *    TSS02 if the tex source processing directory
    *    does either not exist or is not a directory.
    *    <li>
    *    TEX01 invoking FIXME
    *    </ul>
    */
   // used in GraphicsMojo.execute() only
   public void processGraphics() throws BuildFailureException {
     // may throw BuildFailureException TSS02
     File texProcDir = this.settings.getTexSrcProcDirectoryFile();
     assert texProcDir.exists()
         && texProcDir.isDirectory() : "Expected existing tex processing folder "
             + texProcDir;
 
     // constructor DirNode may log warning WFU01 Cannot read directory
     DirNode node = new DirNode(texProcDir, this.fileUtils);
     // TBD: eliminate here selecting the main files. 
     // may throw BuildFailureException TEX01,
     // log warning WFU03, WPP02, WPP03,
     // EEX01, EEX02, EEX03, WEX04, WEX05, EFU07, EFU08, EFU09
     this.preProc.processGraphicsSelectMain(texProcDir, node, true);
   }
 
   // TBD: rework 
   /**
    * Defines clearing ant-task defined in { @link LatexClrTask}
    * and the according goal in { @link ClearMojo} of the maven plugin.
    * Consists in clearing created graphic files
    * and created files derived from latex main file.
    * <p>
    * The parameters this method depends on are (currently):
    * <ul>
    * <li>
    * {@link Settings#getTexSrcProcDirectoryFile()}
    * <li>
    * {@link Settings#getPatternLatexMainFile()}
    * <li>
    * {@link Settings#getPatternCreatedFromLatexMain()}
    * </ul>
    * <p>
    * Logging:
    * <ul>
    * <li>WPP02: tex file may be latex main file
    * <li>WFU01: Cannot read directory...
    * <li>WFU03: cannot close tex file
    * <li>EFU05: Failed to delete file
    * <li> WFU10, WFU11: if a config file is not written by this software 
    * or it is not clear or the reader cannot close. 
    * </ul>
    *
    * @throws BuildFailureException
    *   <ul>
    *   <li> TSS02 if the tex source processing directory
    *    does either not exist or is not a directory.</li>
    *   <li> TLP04 if a config file cannot be decided whether to be cleared 
    *    or could not be cleared. </li>
    *   </ul>
    *   TBD: synchronize: Really a throwable? 
    */
   public void clearAll() throws BuildFailureException {
     this.paramAdapt.initialize();
     this.log.debug("Settings: " + this.settings.toString());
 
     // may throw BuildFailureException TSS02
     File texProcDir = this.settings.getTexSrcProcDirectoryFile();
     assert texProcDir.exists()
         && texProcDir.isDirectory() : "Expected existing tex processing folder "
             + texProcDir;
 
     // constructor DirNode may log warning WFU01 Cannot read directory
     // clearCreated may log warnings WPP02, WFU01, WFU03, EFU05
     this.preProc.clearCreated(texProcDir);
     // may log WFU10, WFU11, EFU05 
     clearInjFiles();
   }
 
   // FIXME: use the -recorder option to resolve dependencies.
   // With that option, a file xxx.fls is generated with form
   // PWD
   // /home/ernst/OpenSource/maven-latex-plugin/maven-latex-plugin.git/trunk/maven-latex-plugin/src/site/tex
   // INPUT /usr/local/texlive/2014/texmf.cnf
   // INPUT /usr/local/texlive/2014/texmf-dist/web2c/texmf.cnf
   // INPUT /usr/local/texlive/2014/texmf-var/web2c/pdftex/pdflatex.fmt
   // INPUT manualLatexMavenPlugin.tex
   // OUTPUT manualLatexMavenPlugin.log
   // INPUT /usr/local/texlive/2014/texmf-dist/tex/latex/base/article.cls
   // INPUT /usr/local/texlive/2014/texmf-dist/tex/latex/base/article.cls
   // INPUT /usr/local/texlive/2014/texmf-dist/tex/latex/base/size12.clo
   //
   // The first line starts has the form 'PWD <working directory>'
   // The other lines have the form '(INPUT|OUTPUT) <file>'
   // We distinguishe those in the installation,
   // here '/usr/local/texlive/2014/...' which do not change ever
   // and others.
   // In this example, the others are (unified and sorted):
 
   // INPUT manualLatexMavenPlugin.tex
 
   // OUTPUT manualLatexMavenPlugin.log
   // INPUT manualLatexMavenPlugin.aux
   // OUTPUT manualLatexMavenPlugin.aux
   // INPUT manualLatexMavenPlugin.out
   // OUTPUT manualLatexMavenPlugin.out
   // INPUT manualLatexMavenPlugin.toc
   // OUTPUT manualLatexMavenPlugin.toc
   // INPUT manualLatexMavenPlugin.lof
   // OUTPUT manualLatexMavenPlugin.lof
   // INPUT manualLatexMavenPlugin.lot
   // OUTPUT manualLatexMavenPlugin.lot
 
   // OUTPUT manualLatexMavenPlugin.idx
   // INPUT manualLatexMavenPlugin.ind
 
   // OUTPUT manualLatexMavenPlugin.pdf
 
   // INPUT 1fig2dev.ptx
   // INPUT 1fig2dev.pdf
   // INPUT 2plt2pdf.ptx
   // INPUT 2plt2pdf.pdf
   // INPUT 4tex2pdf.ptx
   // INPUT 5aux2bbl.ptx
   // INPUT 5aux2bbl.pdf
   // INPUT 6idx2ind.ptx
   // INPUT 6idx2ind.pdf
   // INPUT 7tex2xml.ptx
   // INPUT 7tex2xml.pdf
   // what is missing is all to do with bibliography, i.e. the bib-file.
 
   // FIXME: determine whether to use latexmk makes sense
 
 
   public String getLatex2pdfCommand() throws BuildFailureException {
     return this.latex2PdfCmdMagic
       .orElse(this.settings.getCommand(ConverterCategory.LaTeX));
   }
 
   private String getDvi2pdfCommand() throws BuildFailureException {
     return this.settings.getCommand(ConverterCategory.Dvi2Pdf);
   }
 
   /**
    * Runs LaTeX on on the latex main file <code>texFile</code>
    * described by <code>desc</code> once,
    * runs BibTeX, MakeIndex and MakeGlossaries by need
    * and returns whether a second LaTeX run is required.
    * The latter also holds, if a table of contents, a list of figures
    * or a list of tables is specified.
    * The output format of the LaTeX run is given by <code>dev</code>,
    * to be more precise by {@link LatexDev#getLatexOutputFormat()}.
    * <p>
    * A warning is logged if the LaTeX, a BibTeX run a MakeIndex
    * or a MakeGlossaries run fails
    * or if a BibTeX run or a MakeIndex or a MakeGlossary run issues a warning
    * in the according methods
    * {@link #runLatex2dev(LatexMainDesc, LatexDev)} and 
    * {@link Auxiliary#process(LatexMainDesc, LatexProcessor)}. 
    * <p>
    * Logging:
    * <ul>
    * <li>EAP01: Running <code>command</code> failed. For details...
    * <li>EAP02: Running <code>command</code> failed. No log file
    * <li>WAP04: if <code>logFile</code> is not readable.
    * <li>WLP04: Cannot read idx file; skip creation of index
    * <li>WLP05: Use package 'splitidx' without option 'split'
    * <li>WLP02: Cannot read blg file: BibTeX run required?
    * <li>WFU03: cannot close log file
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * if one of the commands mentioned in the throws-tag fails
    * </ul>
    *
    * @param desc
    *    the description of a latex main file <code>texFile</code>
    *    to be processed.
    * @param dev
    *    the device describing the output format which is either pdf or
    *    dvi.
    *    See {@link LatexDev#getLatexOutputFormat()}.
    * @return
    *    the number of LaTeX runs required after invocation of this method 
    *    because bibtex, makeindex or makeglossaries had been run
    *    or to update a table of contents or a list figures or tables.
    *    <ul>
    *    <li>
    *    If neither of these are present, no rerun is required.
    *    <li>
    *    If a bibliography, an index and a glossary is included
    *    and a table of contents,
    *    we assume that these are in the table of contents.
    *    Thus two reruns are required:
    *    one to include the bibliography or that like
    *    and the second one to make it appear in the table of contents.
    *    <li>
    *    In all other cases, a single rerun suffices
    *    </ul>
    * @throws BuildFailureException
    *    TEX01 if invocation one of the following commands fails: the
    *    <ul>
    *    <li>latex2pdf command from
    *    {@link #getLatex2pdfCommand()}
    *    <li>BibTeX command from
    *    {@link Settings#getBibtexCommand()}
    *    <li>makeindex command from
    *    {@link Settings#getMakeIndexCommand()}
    *    <li>makeglossaries command
    *    from {@link Settings#getMakeGlossariesCommand()}
    *    </ul>
    * @see #processLatex2devCore(LatexMainDesc, LatexDev)
    * @see #processLatex2html(LatexMainDesc)
    * @see #processLatex2odt(LatexMainDesc)
    * @see #processLatex2docx(LatexMainDesc)
    */
   private int preProcessLatex2dev(LatexMainDesc desc, LatexDev dev)
       throws BuildFailureException {
 
     // initial latex run
     // may throw BuildFailureException TEX01
     // may log warnings EEX01, EEX02, EEX03, WEX04, WEX05,
     // EAP01, EAP02, WAP04, WFU03
     runLatex2dev(desc, dev);
     //File texFile = desc.texFile;
 
     // need not be a file with ending aux, but is source for an auxiliary process 
     File auxFile;
     boolean posterioryEntryInToc = false;
     int minNumRunsAfter = 0;
     for (Auxiliary aux : Auxiliary.values()) {
       auxFile = desc.withSuffix(aux.extension());
       assert !auxFile.isDirectory();
       if (!aux.doesFitAuxiliary(auxFile)) {
         continue;
       }
       // TBC: can additional keys occur later? 
       desc.aux2fileId.put(aux, getIdent(aux, auxFile));
 
       posterioryEntryInToc = aux.mayBeEntryInToc();
       this.log.debug("Running auxiliary " + aux + ". ");
       aux.process(desc, this);
       minNumRunsAfter = Math.max(minNumRunsAfter,aux.numRunsAfter());
     } // for 
     assert minNumRunsAfter >= 0 && minNumRunsAfter <= 2;
 
     // // create bibliography, index and glossary by need
     // // may throw BuildFailureException TEX01
     // // may log warnings EEX01, EEX02, EEX03, WEX04, WEX05,
     // // EAP01, EAP02, WAP03, WAP04, WLP02, WFU03
     // boolean hasBib = runBibtex(desc);
     // // may both throw BuildFailureException, both TEX01
     // // may both log warnings EEX01, EEX02, EEX03, WEX04, WEX05,
     // // EAP01, EAP02, WLP04, WLP05, WAP03, WAP04, WFU03
     // boolean hasIdxGls = makeIndex(desc) | runMakeGlossary(desc);
     // boolean hasPyCode = runPythontex(desc);
 
 
     boolean hasToc = desc.withSuffix(SUFFIX_TOC).exists();
     if (hasToc && posterioryEntryInToc) {
       minNumRunsAfter = Math.max(minNumRunsAfter,2);
     }
 
     if (hasToc
     || desc.withSuffix(SUFFIX_LOF).exists()
     || desc.withSuffix(SUFFIX_LOT).exists()
     || desc.withSuffix(SUFFIX_LOL).exists()) {
       minNumRunsAfter = Math.max(minNumRunsAfter,1);
     }
 
     return minNumRunsAfter;
   }
 
   private static final FileId EMPTY_FILE_ID = new FileId().finalizFileId();
 
   /**
    * Wraps {@link Auxiliary#getIdent(File)} 
    * catching the IOException 
    * and transforming it into WLP10 
    * indicating that rerun check is degraded. 
    * 
    * @param aux
    *    the auxiliary which determines the aspects of 
    * @param file
    *    the file for which an identifier is requested. 
    * @return
    *    the identifier for the file <code>file</code> 
    *    tied to the auxiliary <code>aux</code> 
    *    according to {@link Auxiliary#getIdent(File)}, 
    *    except if the latter throws an exception. 
    *    In that case, {@link #EMPTY_FILE_ID} is returned. 
    */
   private FileId getIdent(Auxiliary aux, File file) {
     try {
       return aux.getIdent(file).finalizFileId();
     } catch(IOException ioe) {
       this.log.warn("WLP10: Degraded identifier for '" +file + 
       "'; augmented risk not to rerun although necessary. ");
       return EMPTY_FILE_ID;
     }
   }
 
   /**
    * Runs LaTeX on the latex main file <code>texFile</code>
    * described by <code>desc</code> once,
    * runs BibTeX, MakeIndex and MakeGlossaries by need
    * according to {@link #preProcessLatex2dev(LatexMainDesc,LatexDev)}
    * and reruns MakeIndex, MakeGlossaries and LaTeX
    * as often as needed to get all links satisfied
    * or as threshold {@link Settings#maxNumReRunsLatex} specifies.
    * <p>
    * Note that still no logging of warnings from a latex run is done.
    * This is done
    * in {@link #processLatex2dev(LatexMainDesc, LatexDev)}.
    * The exclusion of logging of warnings is indicated by the name part
    * 'Core'.
    * Processing without logging of warnings
    * is required by {@link #processLatex2txt(LatexMainDesc)}.
    * <p>
    * The output format of the LaTeX run is given by <code>dev</code>,
    * to be more precise by {@link LatexDev#getLatexOutputFormat()}.
    * <p>
    * Logging:
    * WLP01: if another rerun is required but the maximum number of runs
    * {@link Settings#getMaxNumReRunsLatex()} is reached.
    * Further logging is inherited by invoked methods:
    * <ul>
    * <li>WLP04: Cannot read idx file; skip creation of index
    * <li>WLP05: Use package 'splitidx' without option 'split'
    * <li>EAP01: Running <code>command</code> failed. For details...
    * <li>EAP02: Running <code>command</code> failed. No log file
    * <li>WAP04: if <code>logFile</code> is not readable.
    * <li>WLP02: Cannot read log file: run BibTeX/
    * (re)run MakeIndex/LaTeX required?
    * <li>WFU03: cannot close
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05: as for
    * {@link #preProcessLatex2dev(LatexMainDesc, LatexDev)}
    * maybe caused by subsequent runs.
    * </ul>
    *
    * @param desc
    *    the description of a latex main file <code>texFile</code>
    *    to be processed.
    * @param dev
    *    the device describing the output format 
    *    which is either pdf or dvi.
    *    See {@link LatexDev#getLatexOutputFormat()}.
    * @throws BuildFailureException
    *    TEX01 as for
    *    {@link #preProcessLatex2dev(LatexMainDesc, LatexDev)}
    *    maybe caused by subsequent runs.
    * @see #processLatex2dvi(LatexMainDesc)
    * @see #processLatex2txt(LatexMainDesc)
    */
   private void processLatex2devCore(LatexMainDesc desc, LatexDev dev)
       throws BuildFailureException {
 
     // may throw BuildFailureException TEX01,
     // log warning WLP04, WLP05, EAP01, EAP02, WAP04, WLP02, WFU03, 
     // EEX01, EEX02, EEX03, WEX04, WEX05
     int numLatexReRuns = preProcessLatex2dev(desc, dev);
 
     String latexCmd = getLatex2pdfCommand();
 
     assert numLatexReRuns == 0 || numLatexReRuns == 1 || numLatexReRuns == 2;
     if (numLatexReRuns > 0) {
       // rerun LaTeX without makeindex and makeglossaries
       this.log.debug("Rerun " + latexCmd + " to update table of contents, ... "
           + "bibliography, index, or that like. ");
       // may throw BuildFailureException TEX01
       // may log warnings EEX01, EEX02, EEX03, WEX04, WEX05,
       // EAP01, EAP02, WAP04, WFU03
       runLatex2dev(desc, dev);
       numLatexReRuns--;
     }
     assert numLatexReRuns == 0 || numLatexReRuns == 1;
 
     boolean needLatexReRun = (numLatexReRuns == 1) 
     || needRun(true, latexCmd,
         desc.logFile, this.settings.getPatternReRunLatex());
 
     int maxNumReruns = this.settings.getMaxNumReRunsLatex();
     for (int num = 0; maxNumReruns == -1 || num < maxNumReruns; num++) {
       FileId fileId;
       for (Auxiliary aux : desc.aux2fileId.keySet()) {
         fileId = getIdent(aux, desc.withSuffix(aux.extension()));
 
         if (desc.aux2fileId.get(aux).equals(fileId)) {
           continue;
         }
         this.log.debug("Rerunning auxiliary " + aux + ". ");
         desc.aux2fileId.put(aux, fileId);
         aux.process(desc, this);
         needLatexReRun = true;
       }
 
       if (!needLatexReRun) {
         return;
       }
       this.log.debug("Latex must be rerun. ");
 
 
       // may throw BuildFailureException TEX01
       // may log warnings EEX01, EEX02, EEX03, WEX04, WEX05,
       // EAP01, EAP02, WAP04, WFU03
       runLatex2dev(desc, dev);
       needLatexReRun = needRun(true, latexCmd, desc.logFile,
           this.settings.getPatternReRunLatex());
     } // for 
     this.log.warn("WLP01: LaTeX requires rerun but maximum number "
         + maxNumReruns + " reached. ");
   }
 
   /**
    * Returns whether a(n other) run (see <code>another</code>)
    * of the application <code>application</code> is necessary
    * based on a pattern <code>pattern</code>
    * matching in the log file <code>logFile</code>.
    * Note that only <code>logFile</code> and <code>pattern</code>
    * are required unless a warning needs to be issued.
    * <p>
    * Logging:
    * <ul>
    * <li>WLP02: Cannot read log file: (re)run required?
    * <li>WFU03: cannot close log file
    * </ul>
    *
    * @param another
    *    whether it is requested whether another run 
    *    (a 'rerun') is required.
    *    If false, just a run is required
    * @param cmdStr
    *    Determines the command string of the application to be rerun.
    *    This may be of category {@link ConverterCategory#LaTeX},
    *    {@link ConverterCategory#MakeIndex}
    *    but also {@link ConverterCategory#BibTeX}.
    * @param logAuxFile
    *    the log file or aux file which determines
    *    whether to rerun <code>cmdStr</code>.
    * @param pattern
    *    the pattern in the <code>logFile</code>
    *    which determines whether to rerun <code>cmdStr</code>.
    * @return
    *    whether <code>cmdStr</code> needs to be rerun
    *    based on a pattern <code>pattern</code>
    *    matching in the log file <code>logFile</code>.
    * @see TexFileUtils#matchInFile(File, String)
    */
   // used in processLatex2devCore only
   // TBD: eliminate Converter again and replace by ConverterCategory
   // including also the rerun pattern.
   boolean needRun(boolean another, String cmdStr, File logAuxFile,
       String pattern) {
     // may log warning WFU03: cannot close
     FileMatch fileMatch = this.fileUtils.getMatchInFile(logAuxFile, pattern);
     if (fileMatch.isFileReadable()) {
       return fileMatch.doesExprMatch();
     }
     this.log
         .warn("WLP02: Cannot read " 
             + TexFileUtils.getSuffix(logAuxFile, false)
             + " file '" + logAuxFile.getName() + "'; " + cmdStr
             + " may require " + (another ? "re" : "") + "run. ");
     return false;
   }
 
   /**
    * Runs LaTeX, BibTeX, MakeIndex and MakeGlossaries
    * on the latex main file <code>texFile</code>
    * described by <code>desc</code>
    * repeatedly as described for
    * {@link #processLatex2devCore(LatexMainDesc,LatexDev)}
    * and issue a warning if the last LaTeX run issued a warning.
    * </ul>
    * <p>
    * Logging:
    * <ul>
    * <li>WFU03: cannot close
    * <li>WAP04: if <code>logFile</code> is not readable.
    * <li>WLP01: if another rerun is required
    * but the maximum number of runs is reached.
    * <li>WLP03: <code>command</code> created bad boxes
    * <li>WLP04: <code>command</code> emitted warnings
    * <li>WLP04: Cannot read idx file; skip creation of index
    * <li>WLP05: Use package 'splitidx' without option 'split'
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * {@link #processLatex2devCore(LatexMainDesc, LatexDev)}
    * if running an exernal command fails.
    * </ul>
    *
    * @param desc
    *    the description of a latex main file <code>texFile</code>
    *    to be processed.
    * @param dev
    *    the device describing the output format which is either pdf or dvi.
    *    See {@link LatexDev#getLatexOutputFormat()}.
    * @throws BuildFailureException
    *    TEX01 as for
    *    {@link #processLatex2devCore(LatexMainDesc, LatexDev)}.
    * @see #needRun(boolean, String, File, String)
    * @see Target#pdf
    */
   private void processLatex2dev(LatexMainDesc desc, LatexDev dev)
       throws BuildFailureException {
 
     // invocation of latexmk here is suitable if used not only for pdf but also for dvi in future 
     // // TBD: improve this in several respect. 
     // if (dev == LatexDev.pdf && this.settings.getLatexmkUsage() != LatexmkUsage.NotAtAll) {
     //   this.log.info("Running latexmk bypassing direct compilation. ");
     //   runLatexmk(desc);
     //   return;
     // }
     // this.log.info("No latexmk because target=" + dev + " and usage=" + this.settings.getLatexmkUsage());
 
     // may throw BuildFailureException TEX01,
     // log warning EAP01, EAP02, WAP04, WLP02, WFU03, WLP04, WLP05,
     // EEX01, EEX02, EEX03, WEX04, WEX05
     processLatex2devCore(desc, dev);
 
     // emit warnings (errors are emitted by runLatex2dev and that like.)
     // may log warnings WFU03, WAP04, WLP03, WLP04
     logWarns(desc.logFile, getLatex2pdfCommand());
   }
 
   void processLatex2dvi(LatexMainDesc desc)
       throws BuildFailureException {
     this.log.info("Converting into dvi/xdv format. ");
     // may throw BuildFailureException TEX01,
     // log warning EEX01, EEX02, EEX03, WEX04, WEX05
     // WFU03, WAP04, WLP03, WLP04
     processLatex2dev(desc, LatexDev.dvips);
   }
 
   void processLatex2pdf(LatexMainDesc desc)
       throws BuildFailureException {
     this.log.info("Converting into pdf format. ");
 
     // TBD: improve this in several respect. 
     if (isCompileWithLatexmk(desc)) {
       // CAUTION: timestamp is not used directly 
       runLatexmk(desc);
       return;
     }
 
     LatexDev dev = this.settings.getPdfViaDvi();
 
     // may throw BuildFailureException TEX01,
     // log warning EEX01, EEX02, EEX03, WEX04, WEX05, WLP04, WLP05
     processLatex2dev(desc, dev);
     // FIXME: certain figures are invisible in the intermediate dvi file,
     // but converstion to pdf shows that the figures are present.
 
     if (dev.isViaDvi()) {
       // may throw BuildFailureException TEX01,
       // may log warning EEX01, EEX02, EEX03, WEX04, WEX05
       runDvi2pdf(desc);
     }
   }
 
   /**
    * Logs errors detected in the according log file:
    * The log file is by replacing the ending of <code>texFile</code>
    * by <code>log</code>.
    * If the log file exists, a <em>warning</em> is logged
    * if the error pattern given by {@link Settings#getPatternErrLatex()}
    * occurs in the log file.
    * If the log file does not exist, an <em>error</em> is logged.
    * In both cases, the message logged refers to the <code>command</code>
    * which failed.
    * <p>
    * Logging:
    * <ul>
    * <li>EAP01: Running <code>command</code> failed. For details...
    * <li>EAP02: Running <code>command</code> failed. No log file
    * <li>WAP04: if <code>logFile</code> is not readable.
    * <li>WFU03: cannot close
    * </ul>
    */
   private void logErrs(File logFile, String command) {
     // may log warnings WFU03, EAP01, EAP02, WAP04
     logErrs(logFile, command, this.settings.getPatternErrLatex());
   }
 
   /**
    * Logs warnings detected in the according log-file <code>logFile</code>:
    * Before logging warnings,
    * errors are logged via {@link #logErrs(File, String)}.
    * So, if the log-file does not exist,
    * an error was already shown and so nothing is to be done here.
    * If the log-file exists, a <em>warning</em> is logged if
    * <ul>
    * <li>
    * another LaTeX rerun is required
    * beyond {@link Settings#maxNumReRunsLatex},
    * <li>
    * bad boxes occurred and shall be logged
    * according to {@link Settings#getDebugBadBoxes()}.
    * <li>
    * warnings occurred and shall be logged
    * according to {@link Settings#getDebugWarnings()}.
    * </ul>
    * Both criteria are based on pattern recognized in the log file:
    * {@link #PATTERN_OUFULL_HVBOX} for bad boxes is fixed,
    * whereas {@link Settings#getPatternWarnLatex()} is configurable.
    * The message logged refers to the <code>command</code> which failed.
    * <p>
    * Logging:
    * <ul>
    * <li>WFU03: cannot close
    * <li>WAP04: if <code>logFile</code> is not readable.
    * <li>WLP03: <code>command</code> created bad boxes
    * <li>WLP04: <code>command</code> emitted warnings
    * </ul>
    *
    * @param logFile
    *    the log-file to detect warnings in.
    * @param command
    *    the command which created <code>logFile</code>
    *    and which maybe created warnings.
    */
   private void logWarns(File logFile, String command) {
     if (!logFile.exists()) {
       return;
     }
     // hasErrsWarns may log warnings WFU03 cannot close, WAP04 not readable
     if (this.settings.getDebugBadBoxes()
         && hasErrsWarns(logFile, PATTERN_OUFULL_HVBOX)) {
       this.log.warn("WLP03: Running " + command
           + " created bad boxes logged in '" + logFile.getName() + "'. ");
     }
 
     if (this.settings.getDebugWarnings()
         && hasErrsWarns(logFile, this.settings.getPatternWarnLatex())) {
       // logs warning WAP03: emitted warnings
       logWarn(logFile, command);
     }
   }
 
   /**
    * Runs conversion of <code>texFile</code> to html or xhtml
    * after processing latex to set up the references,
    * bibliography, index and that like.
    * <p>
    * Logging: FIXME: incomplete
    * <ul>
    * <li>EAP01: Running <code>command</code> failed. For details...
    * <li>EAP02: Running <code>command</code> failed. No log file
    * <li>WAP04: if <code>logFile</code> is not readable.
    * <li>WLP02: Cannot read blg file: BibTeX run required?
    * <li>WFU03: cannot close log file
    * <li>WLP04: Cannot read idx file; skip creation of index
    * <li>WLP05: Use package 'splitidx' without option 'split'
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * if running an exernal command fails.
    * </ul>
    *
    * @param desc
    *    the tex file to be processed.
    * @throws BuildFailureException
    *    TEX01 as for
    *    {@link #preProcessLatex2dev(LatexMainDesc, LatexDev)}
    *    but also as for
    *    {@link #runLatex2html(LatexProcessor.LatexMainDesc)}.
    * @see #preProcessLatex2dev(LatexMainDesc, LatexDev)
    * @see #runLatex2html(LatexMainDesc)
    * @see Target#html
    */
   // TBD: check: is it really sensible to do preprocessing? 
   // TBD: also inconsistency: preprocessing with lualatex, xelatex, pdflatex
   // whereas processing is done with htlatex and with xtlatex... no lualatex involved. 
   void processLatex2html(LatexMainDesc desc)
       throws BuildFailureException {
     this.log.info("Converting into html format. ");
     // may throw BuildFailureException TEX01,
     // log warning EAP01, EAP02, WLP04, WLP05, WAP04, WLP02, WFU03, 
     // EEX01, EEX02, EEX03, WEX04, WEX05
     preProcessLatex2dev(desc, LatexDev.devViaDvi(true));
     // may throw BuildFailureException TEX01,
     // log warning EEX01, EEX02, EEX03, WEX04, WEX05
     runLatex2html(desc);
   }
 
   /**
    * Runs conversion of <code>texFile</code>
    * to odt or other open office formats
    * after processing latex to set up the references,
    * bibliography, index and that like.
    * <p>
    * Logging: FIXME: incomplete 
    * <ul>
    * <li>EAP01: Running <code>command</code> failed. For details...
    * <li>EAP02: Running <code>command</code> failed. No log file
    * <li>WAP04: if <code>logFile</code> is not readable.
    * <li>WLP02: Cannot read blg file: BibTeX run required?
    * <li>WFU03: cannot close log file
    * <li>WLP04: Cannot read idx file; skip creation of index
    * <li>WLP05: Use package 'splitidx' without option 'split'
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * if running an exernal command fails.
    * </ul>
    *
    * @param desc
    *    the tex file to be processed.
    * @throws BuildFailureException
    *    TEX01 as for
    *    {@link #preProcessLatex2dev(LatexMainDesc, LatexDev)}
    *    but also as for
    *    {@link #runLatex2odt(LatexProcessor.LatexMainDesc)}.
    * @see #preProcessLatex2dev(LatexMainDesc, LatexDev)
    * @see #runLatex2odt(LatexMainDesc)
    * @see Target#odt
    */
   void processLatex2odt(LatexMainDesc desc)
       throws BuildFailureException {
     this.log.info("Converting into odt format. ");
     // may throw BuildFailureException TEX01,
     // log warning EAP01, EAP02, WAP04, WLP02, WFU03, WLP04, WLP05
     // EEX01, EEX02, EEX03, WEX04, WEX05
     preProcessLatex2dev(desc, this.settings.getPdfViaDvi());
     // may throw BuildFailureException TEX01,
     // log warning EEX01, EEX02, EEX03, WEX04, WEX05
     runLatex2odt(desc);
   }
 
   /**
    * Runs conversion of <code>texFile</code>
    * to docx or other MS word formats
    * after processing latex to set up the references,
    * bibliography, index and that like.
    * <p>
    * Logging: FIXME: incomplete
    * <ul>
    * <li>EAP01: Running <code>command</code> failed. For details...
    * <li>EAP02: Running <code>command</code> failed. No log file
    * <li>WAP04: if <code>logFile</code> is not readable.
    * <li>WLP02: Cannot read blg file: BibTeX run required?
    * <li>WFU03: cannot close log file
    * <li>WLP04: Cannot read idx file; skip creation of index
    * <li>WLP05: Use package 'splitidx' without option 'split'
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * if running an exernal command fails.
    * </ul>
    *
    * @param desc
    *    the latex main file to be processed.
    * @throws BuildFailureException
    *    TEX01 as for
    *    {@link #preProcessLatex2dev(LatexMainDesc, LatexDev)}
    *    but also as for
    *    {@link #runLatex2odt(LatexProcessor.LatexMainDesc)}
    *    and for {@link #runOdt2doc(LatexMainDesc)}.
    * @see #preProcessLatex2dev(LatexMainDesc, LatexDev)
    * @see #runLatex2odt(LatexMainDesc)
    * @see #runOdt2doc(LatexMainDesc)
    * @see Target#docx
    */
   void processLatex2docx(LatexMainDesc desc)
       throws BuildFailureException {
     this.log.info("Converting into doc(x) format. ");
     // may throw BuildFailureException TEX0,
     // log warning EAP01, EAP02, WAP04, WLP02, WFU03, WLP04, WLP05
     // EEX01, EEX02, EEX03, WEX04, WEX05
     preProcessLatex2dev(desc, this.settings.getPdfViaDvi());
     // may throw BuildFailureException TEX0,
     // log warning EEX01, EEX02, EEX03, WEX04, WEX05
     runLatex2odt(desc);
     // may throw BuildFailureException TEX01,
     // log warning EEX01, EEX02, EEX03, WEX04, WEX05
     runOdt2doc(desc);
   }
 
   /**
    * Runs direct conversion of <code>texFile</code> to rtf format.
    * <p>
    * FIXME: Maybe prior invocation of LaTeX MakeIndex and BibTeX
    * after set up the references, bibliography, index and that like
    * would be better.
    * <p>
    * Logging: FIXME: incomplete
    * <ul>
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * if running an exernal command fails.
    * </ul>
    *
    * @param desc
    *    the tex file to be processed.
    * @throws BuildFailureException
    *    TEX01 if running the latex2rtf command
    *    returned by
    *    {@link Settings#getLatex2rtfCommand()} failed.
    * @see #runLatex2rtf(File)
    * @see Target#rtf
    */
   void processLatex2rtf(LatexMainDesc desc) throws BuildFailureException {
     this.log.info("Converting into rtf format. ");
     // may throw BuildFailureException TEX01,
     // log warning EEX01, EEX02, EEX03, WEX04, WEX05
     runLatex2rtf(desc.texFile);//, timestamp
   }
 
   /**
    * Runs conversion of <code>texFile</code> to txt format via pdf.
    * <p>
    * Logging: FIXME: incomplete
    * <ul>
    * <li>WLP04: Cannot read idx file; skip creation of index
    * <li>WLP05: Use package 'splitidx' without option 'split'
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * if running an exernal command fails.
    * </ul>
    *
    * @param desc
    *    the tex file to be processed.
    * @throws BuildFailureException
    *    TEX01 as for
    *    {@link #processLatex2devCore(LatexMainDesc, LatexDev)}
    *    and for {@link #runPdf2txt(LatexMainDesc)}.
    * @see #processLatex2devCore(LatexMainDesc, LatexDev)
    * @see #runPdf2txt(LatexMainDesc)
    * @see Target#txt
    */
   void processLatex2txt(LatexMainDesc desc)
       throws BuildFailureException {
     this.log.info("Converting into txt format. ");
     LatexDev dev = this.settings.getPdfViaDvi();
 
     // may throw BuildFailureException TEX01,
     // log warning EAP01, EAP02, WAP04, WLP02, WFU03, WLP04, WLP05,
     // EEX01, EEX02, EEX03, WEX04, WEX05
     processLatex2devCore(desc, dev);
     if (dev.isViaDvi()) {
       // may throw BuildFailureException TEX01,
       // may log warning EEX01, EEX02, EEX03, WEX04, WEX05
       runDvi2pdf(desc);
     }
 
     // warnings emitted by LaTex are ignored
     // (errors are emitted by runLatex2dev and that like.)
     // may throw BuildFailureException TEX01,
     // log warning EEX01, EEX02, EEX03, WEX04, WEX05
     runPdf2txt(desc);
   }
 
   /**
    * Prints meta information, mainly version information
    * on this software and on the converters used.
    * <p>
    * WMI01: If the version string of a converter cannot be read.
    * WMI02: If the version of a converter is not as expected.
    *
    * @param includeVersionInfo
    *     whether to include plain version info; else warnings only.
    * @return
    *    whether a warning has been issued.
    * @throws BuildFailureException
    *    <ul>
    *    <li>TMI01: if the stream to either the manifest file
    *    or to a property file, either 
    *    {@LINK #VERSION_PROPS_FILE} or
    *    {@link MetaInfo.GitProperties#GIT_PROPS_FILE}
    *    could not be created.</li>
    *    <li>TMI02: if the properties could not be read
    *    from one of the two property files mentioned above.</li>
    *    <li>TSS05: if converters are excluded in the
    *    pom which are not known.</li>
    *    </ul>
    */
   public boolean printMetaInfo(boolean includeVersionInfo)
       throws BuildFailureException {
     // may throw BuildFailureException TSS05
     SortedSet<Converter> convertersExcluded =
         this.settings.getConvertersExcluded();
     return this.metaInfo.printMetaInfo(includeVersionInfo, convertersExcluded);
   }
 
   boolean runBibtex(LatexMainDesc desc) throws BuildFailureException {
     String command = this.settings.getCommand(ConverterCategory.BibTeX);
     this.log.debug("Running " + command + " on '" + desc.xxxFile.getName() + "'. ");
     String[] args = buildArguments(this.settings.getBibtexOptions(), desc.xxxFile);
     // may throw BuildFailureException TEX01,
     // may log warning EEX01, EEX02, EEX03, WEX04, WEX05
     this.executor.executeEnvR0(desc.parentDir, // workingDir
         this.settings.getTexPath(), command, args, desc.withSuffix(SUFFIX_BBL));
 
     File logFile = desc.withSuffix(SUFFIX_BLG);
     // may log EAP01, EAP02, WAP04, WFU03
     logErrs(logFile, command, this.settings.getPatternErrBibtex());
     // may log warnings WFU03, WAP03, WAP04
     logWarns(logFile, command, this.settings.getPatternWarnBibtex());
     return true;
   }
 
   /**
    * Runs the MakeIndex command
    * given by {@link Settings#getMakeIndexCommand()}
    * on the idx-file corresponding with <code>texFile</code> which is assumed to exist.
    * <p>
    * Note that {@link Settings#getMakeIndexCommand()}
    * is invoked either directly, or, in case of a multiple index,
    * via {@link Settings#getSplitIndexCommand()}. 
    * To decide whether splitting is required, 
    * the idx-file must be read. 
    * If this is not possible, warning WLP04 is emitted 
    * indicating that the index is not created. 
    * This is the only case where the return value is <code>false</code>. 
    * <p>
    * Logging:
    * <ul>
    * <li>WLP04: Cannot read idx file; skip creation of index
    * <li>WLP05: Use package 'splitidx' without option 'split'
    * <li>EAP01: Running <code>makeindex</code> failed. For details...
    * <li>EAP02: Running <code>makeindex</code> failed. No log file
    * <li>WAP03: Running <code>makeindex</code> emitted warnings.
    * <li>WAP04: .ilg-file is not readable.
    * <li>WFU03: cannot close .ilg-file
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * if running the makeindex command failed.
    * </ul>
    *
    * @param desc
    *     the description of a latex main file <code>dviFile</code>
    *     including the idx-file MakeIndex is to be run on.
    * @return
    *     whether MakeIndex had been run, possibly via splitindex. 
    *     This is done, except if the idx-file is not readable 
    *     and so it cannot be decided whether to invoke makeindex or splitindex. 
    *     In this case the warning WLP04 is emitted. 
    * @throws BuildFailureException
    *      TEX01 if invocation of the makeindex command
    *      returned by
    *      {@link Settings#getMakeIndexCommand()} failed.
    */
   boolean runMakeSplitIndex(LatexMainDesc desc)
     throws BuildFailureException {
 
     // determine the explicit given identifiers of indices
     final Set<String> explIdxIdent =
         this.fileUtils.collectMatchesForIdx(desc.idxFile,
             Pattern.compile(this.settings.getPatternMultiIndex()),
             GRP_IDX_IDENT);
     if (explIdxIdent == null) {
       this.log.warn("WLP04: Cannot read idx file '" + desc.idxFile.getName()
           + "'; skip creation of index. ");
       return false;
     }
     assert explIdxIdent != null;
 
     // Here, explIdxIdent contains the explicit identifiers of all indices
     // The identifier idx may be missing or not.
 
     // package splitidx is used with option split
     // is in general not allowed. The criteria are:
     // - if \jobname-xxx.idx exists for some xxx whereas \jobname.idx does not:
     //   This occurs only for option split
     //   and does not allow applying splitindex
     //   as it is intended in this software.
     //   This would require applying makeindex separately
     //   to all \jobname-xxx.idx
     // - if \jobname-xxx.idx exists for some xxx
     //   and also \jobname.idx exists but has no entry
     //   \indexentry[xxx]{...}{..}:
     //   This occurs only for option split
     //   and applying splitindex yields the wrong result.
     //   This would require applying makeindex separately
     //   to all \jobname-xxx.idx and to \jobname.idx
     // - if \jobname-xxx.idx does not exist for any xxx
     //   then all is ok, whether \jobname.idx exists or not.
     //   If it exists, even splitidx with option split is ok.
 
     // so algorithm:
     // determine list of these xxx for which \jobname-xxx.idx exists
     // if (\jobname-xxx.idx exists for some xxx) {
     //   if (!(\jobname.idx exists &&
     //         \jobname.idx matches some \indexentry[xxx]{...}{.. )) {
     //      log.error(cannot handle splitidx with option split)
     //      return false;
     // }
     // // For second condition,
     // // determine list of all yyy matching \indexentry[yyy]{...}{..}
     // // and make sure that it is non-empty.
     // }
 
     // filter for extended raw idx-files: \jobname-xxx.idx
     FileFilter filter =
         this.fileUtils.getFileFilterReplace(desc.idxFile, SEP_IDENT_IDX + ".+");
     // may cause WFU01: Cannot read directory
     File[] idxFilesExtInDir =
         this.fileUtils.listFilesOrWarn(desc.idxFile.getParentFile(), filter);
 
     // If the directory compising idxFile is not readable,
     // idxFilesExtInDir == null
     // Then the check for option split cannot be done.
 
     if (idxFilesExtInDir != null && idxFilesExtInDir.length > 0) {
       // Here, idxFilesExtInDir contains the idx-files \jobname-xxx.idx
       if (explIdxIdent.isEmpty()) {
         // Here, either \jobname.idx does not exist at all
         // or does not contain an entry \indexentry[yyy]{...}{..}
 
         this.log.warn("WLP05: Use package 'splitidx' "
             + "without option 'split' in '" + desc.texFile.getName() + "'. ");
         // this.log.warn("WLP05: Found extended idx-file " +
         // " without (according entry in) '" +
         // desc.idxFile.getName() +
         // "': use package 'splitidx' " +
         // "without option 'split'. ");
       }
     }
 
     // TBD: the following is misleading 
     // if \sindex[idx]{...} is used with a single index name idx 
     // This counts as a multi-index but is only one. 
     // But then we need splitindex anyway. 
 
     // check whether more than one index has to be created
     if (explIdxIdent.isEmpty()) {
       // may throw BuildFailureException TEX01
       // may log warnings EEX01, EEX02, EEX03, WEX04, WEX05,
       // EAP01, EAP02, WAP03, WAP04, WFU03
       runMakeIndex(desc);
     } else {
       // may throw BuildFailureException TEX01
       // may log warnings EEX01, EEX02, EEX03, WEX04, WEX05,
       // EAP01, EAP02, WAP03, WAP04, WFU03
       runSplitIndex(desc, explIdxIdent);
     }
 
     return true;
   }
 
   /**
    * Runs the MakeIndex command
    * given by {@link Settings#getMakeIndexCommand()}. 
    * Note that xindy is not supported in this context. 
    * <p>
    * Logging:
    * <ul>
    * <li>EAP01: Running <code>makeindex</code> failed. For details...
    * <li>EAP02: Running <code>makeindex</code> failed. No log file
    * <li>WAP03: Running <code>makeindex</code> emitted warnings.
    * <li>WAP04 .ilg-file is not readable.
    * <li>WFU03: cannot close .ilg-file
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * if running the makeindex command failed.
    * </ul>
    *
    * @param desc
    *     the description of a latex main file <code>texFile</code>
    *     including the idx-file MakeIndex is to be run on.
    * @throws BuildFailureException
    *     TEX01 if invocation of the MakeIndex command
    *     returned by
    *     {@link Settings#getMakeIndexCommand()} failed.
    */
   private void runMakeIndex(LatexMainDesc desc) throws BuildFailureException {
 
     String command = this.settings.getCommand(ConverterCategory.MakeIndex);
     // File idxFile = desc.idxFile;
     // this.log.debug("Running " + command + " on '" + idxFile.getName() + "'. ");
     // String[] args =
     //     buildArguments(this.settings.getMakeIndexOptions(), idxFile);
     File xxxFile = desc.xxxFile;
     this.log.debug("Running " + command + " on '" + xxxFile.getName() + "'. ");
     String[] args =
         buildArguments(this.settings.getMakeIndexOptions(), xxxFile); // may throw BuildFailureException TEX01,
     // may log warning EEX01, EEX02, EEX03, WEX04, WEX05
     this.executor.executeEnvR0(desc.parentDir, // workingDir
         this.settings.getTexPath(), command, args, desc.indFile);
 
     // detect errors and warnings makeindex wrote into xxx.ilg
     // may log EAP01, EAP02, WAP04, WFU03
     logErrs(desc.ilgFile, command, this.settings.getPatternErrMakeIndex());
     // may log warnings WFU03, WAP03, WAP04
     logWarns(desc.ilgFile, command, this.settings.getPatternWarnMakeIndex());
   }
 
   /**
    * Combines an array of files from a file prefix <code>filePrefix</code>,
    * a collection of intermediate strings <code>variant</code>
    * and of the suffix <code>suffix</code>.
    *
    * @param filePrefix
    *     prefix of file name; in practice of index file without suffix
    * @param variant
    *     collection of strings; in practice set of identifiers of indices
    * @param suffix
    *     the suffix of a file; in practice {@link #SUFFIX_IDX}.
    * @return
    *     an array of file names of the form
    *     <code>&lt;filePrefix&gt;&lt;ident&gt;&lt;suffix&gt;</code>,
    *     where <code>ident</code> runs in <code>variant</code>.
    */
   private File[] files(String filePrefix, Collection<String> variant,
       String suffix) {
     File[] res = new File[variant.size()];
     int idx = 0;
     StringBuilder strb;
     for (String idxIdent : variant) {
       strb = new StringBuilder();
       strb.append(filePrefix);
       strb.append(idxIdent);
       strb.append(suffix);
 
       res[idx++] = new File(strb.toString());
     }
     return res;
   }
 
   /**
    * Runs the SplitIndex command
    * given by {@link Settings#getSplitIndexCommand()}.
    * <p>
    * Logging:
    * Note that <code>splitindex</code> neither writes a log file
    * nor may it fail in itself but invoking <code>makeindex</code>
    * or whatever program it uses.
    * <ul>
    * <li>EAP01: Running <code>splitindex</code> failed. For details...
    * <li>EAP02: Running <code>splitindex</code> failed. No log file
    * <li>WAP03: Running <code>splitindex</code> emitted warnings.
    * <li>WAP04 .ilg-file is not readable.
    * <li>WFU03: cannot close .ilg-file
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * if running the splitindex command failed.
    * </ul>
    *
    * @param desc
    *     the description of a latex main file <code>texFile</code>
    *     including the idx-file SplitIndex is to be run on.
    * @param explIdxIdent
    *     the set of identifiers of indices,
    *     whether explicitly given or not in the idx file.
    * @throws BuildFailureException
    *     TEX01 if invocation of the SplitIndex command returned by
    *     {@link Settings#getSplitIndexCommand()} failed.
    */
   private void runSplitIndex(LatexMainDesc desc, Collection<String> explIdxIdent)
       throws BuildFailureException {
 
     String splitInxCmd = this.settings.getCommand(ConverterCategory.SplitIndex);
     // File idxFile = desc.idxFile;
     // this.log
     //     .debug("Running " + splitInxCmd + " on '" + idxFile.getName() + "'. ");
     // // buildArguments(this.settings.getMakeIndexOptions(), idxFile);
     //File idxFile = desc.idxFile;
     this.log
         .debug("Running " + splitInxCmd + " on '" + desc.xxxFile.getName() + "'. ");
     // buildArguments(this.settings.getMakeIndexOptions(), idxFile);
     // NOTE: named groups are not compatible with the lua version of splitindex 
 
     // set the options of splitindex set internally and not passed to makeindex or that like 
     String groupIdent = Settings.GRP_IDENT;
     String[] argsSplitIndexDefault = new String[] {
         "-m " + this.settings.getCommand(ConverterCategory.MakeIndex),
         // **** no splitindex.tlu
         // TBD: take over in .latexmkrc also: else latexmk cannot be used with splitindex.tlu. 
         // This is hardcoded by splitidx when writing xxx.ind
         "-i " + this.settings.getPatternMultiIndex(),
         // This is hardcoded by makeindex when writing xxx.ind
         "-r "+groupIdent+GRP_IDX_IDXENTRY+groupIdent+GRP_IDX_KEYPAGE, // groups in IDX_EXPL: \indexentry{...}
         // -s -$2 is hardcoded by splitidx when reading in the -xxx.ind-files
         "-s " + SEP_IDENT_IDX + groupIdent + GRP_IDX_IDENT
     };
 
     // add the single allowed option for splitindex given by the user 
     String argSplitindexOption = this.settings.getSplitIndexOptions();
     assert(argSplitindexOption.indexOf(' ')) == -1;// contains no blank, is single option or empty 
     // Arguments are default arguments, possibly option given explicitly and file name 
     // This is true only if getMakeIndexOptions() is not empty 
 
     // arguments: default options, user defined option filename 
     String[] args = new String[argsSplitIndexDefault.length + (argSplitindexOption.isEmpty() ? 0 : 1) + 1];
     System.arraycopy(argsSplitIndexDefault, 0, args, 0, argsSplitIndexDefault.length);
     if (!argSplitindexOption.isEmpty()) {
       args[args.length - 2] = argSplitindexOption;
     }
     args[args.length - 1] = desc.xxxFile.getName();
 
     // Add the options to be passed to makeindex or that like 
     String optionsMakeIndex = this.settings.getMakeIndexOptions();
     if (!optionsMakeIndex.isEmpty()) {
       // Here 'args' must be replaced by 'args -- optionsMakeIndex' 
       String[] optionsMake_IndexArr = optionsMakeIndex.split(" ");
       String[] optionsSplitIndexArr = args;
       args = new String[optionsMake_IndexArr.length + 1
           + optionsSplitIndexArr.length];
       System.arraycopy(optionsSplitIndexArr, 0, args, 0,
           optionsSplitIndexArr.length);
       args[optionsSplitIndexArr.length] = "--";
       System.arraycopy(optionsMake_IndexArr, 0, args,
           optionsSplitIndexArr.length + 1, optionsMake_IndexArr.length);
     }
 
     // determine the resulting ind-files
     //explIdxIdent.add(IMPL_IDENT_IDX);
     String filePrefix = desc.xxxFile.toString() + SEP_IDENT_IDX;
     File[] indFiles = files(filePrefix, explIdxIdent, SUFFIX_IND);
 
     // may throw BuildFailureException TEX01,
     // may log warning EEX01, EEX02, EEX03, WEX04, WEX05
     this.executor.executeEnvR0(desc.parentDir, // workingDir
         this.settings.getTexPath(), splitInxCmd, args, indFiles);
 
     // detect errors and warnings splitindex,
     // aka makeindex wrote into xxx.ilg
     File[] ilgFiles = files(filePrefix, explIdxIdent, SUFFIX_ILG);
     splitInxCmd = this.settings.getCommand(ConverterCategory.MakeIndex);
     for (int idx = 0; idx < explIdxIdent.size(); idx++) {
       // may log EAP01, EAP02, WAP04, WFU03
       logErrs(ilgFiles[idx], splitInxCmd,
           this.settings.getPatternErrMakeIndex());
       // may log warnings WFU03, WAP03, WAP04
       logWarns(ilgFiles[idx], splitInxCmd,
           this.settings.getPatternWarnMakeIndex());
     }
   }
 
   // return whether the processor has been invoked. 
   // TBD: clarify whether success plays a role
   // parece que nao usa executeEnvR0 return value. 
   // a valuable source of information is https://www.dickimaw-books.com/latex/auxglossaries/
   boolean runMakeGlossary(LatexMainDesc desc)
       throws BuildFailureException {
         // message emitted by makeglossaries: makeglossaries diagnostic messages
         // not used by makeglossaries-light
     // file name without ending: parameter for makeglossaries
     File xxxFile = desc.xxxFile;
     String command = this.settings.getCommand(ConverterCategory.MakeGlossaries);
     this.log.debug("Running " + command + " on '" + xxxFile.getName() + "'. ");
     String[] args =
       buildArguments(this.settings.getMakeGlossariesOptions(), xxxFile);
     // may throw BuildFailureException TEX01,
     // may log warning EEX01, EEX02, EEX03, WEX04, WEX05
     this.executor.executeEnvR0(desc.parentDir, // workingDir
         this.settings.getTexPath(), command, args, desc.glsFile);
     // TBD: check whether more than one gls file is possible.
 
     Boolean isMakeIndexOrLike = this.fileUtils.withMakindexLike(desc.auxFile);
     // assert isMakeIndexOrLike;
     String patternErr, patternWarn;
     if (isMakeIndexOrLike != null && isMakeIndexOrLike.booleanValue()) {
       patternErr = this.settings.getPatternErrMakeIndex();
       patternWarn = this.settings.getPatternWarnMakeIndex();
     } else {
       patternErr = this.settings.getPatternErrXindy();
       patternWarn = this.settings.getPatternWarnXindy();
     }
     Set<String> extLogFiles = this.fileUtils.collectLogsForGloss(desc.auxFile);
     if (isMakeIndexOrLike == null || extLogFiles == null) {
       this.log.warn("WLPXX: Cannot read AUX file; skipping evaluating log files for glossaries. ");
       return true;
     }
     for (String ext : extLogFiles) {
       // detect errors and warnings makeglossaries wrote into xxx.glg
       File logFile = desc.withSuffix("."+ext);
       // may log EAP01, EAP02, WAP04, WFU03
       logErrs(logFile, command, patternErr);
       // may log warnings WFU03, WAP03, WAP04
       logWarns(logFile, command, patternWarn);
     }
 
     return true;
   } // runMakeGlossary
 
   boolean runPythontex(LatexMainDesc desc)
       throws BuildFailureException {
     File xxxFile = desc.xxxFile;
     String command = this.settings.getCommand(ConverterCategory.Pythontex);
     this.log.debug("Running " + command + " on '" + xxxFile.getName() + "'. ");
     String[] args =
         buildArguments(this.settings.getPythontexOptions(), desc.xxxFile);
 
     File outFolder = TexFileUtils
         .replacePrefix(this.settings.getPrefixPytexOutFolder(), desc.xxxFile);
     String repOutFileName = desc.xxxFile.getName() + SUFFIX_PYTXMCR;
     File repOutFile = new File(outFolder, repOutFileName);
     if (repOutFile.exists()) {
       // In the long run: eliminate options rerun and runall 
       // from xxx.pytxcode; then rerun is controlled by command line options. 
       boolean isDel = repOutFile.delete();
       if (!isDel) {
         this.log.warn("Preliminary warning: Could not delete '" + repOutFile
             + "'; this may cause further warnings/errors. ");
       }
     }
     // TBD: repOutFile is not the only result file. 
     // one has to add pytxpyg, pkl and the stdout files. 
     // The precise names of the latter must be read from the pytxcode file. 
 
     // may throw BuildFailureException TEX01,
     // may log warning EEX01, EEX02, EEX03, WEX04, WEX05
     //CommandExecutor.CmdResult res = 
     this.executor.executeEnvR0(desc.parentDir, // workingDir
         this.settings.getTexPath(), command,
         //true, 
         // This may change later, when rerun=never is taken into account. 
         args, repOutFile);
 
     File logFile = desc.withSuffix(SUFFIX_PLG);
     // may log EAP01, EAP02, WAP04, WFU03
     logErrs(logFile, command, this.settings.getPatternErrPyTex());
     // may log warnings WFU03, WAP03, WAP04
     logWarns(logFile, command, this.settings.getPatternWarnPyTex());
     return true;
   } // runPythontex
 
   /**
    * Runs the latexmk command given by {@link Settings#getLatexmkCommand()}
    * on the latex main file <code>texFile</code>
    * described by <code>desc</code>
    * in the directory containing <code>texFile</code> with arguments
    * <!--given by 
    * {@link #buildLatexArguments(Settings, LatexDev, File, boolean)}-->.
    * The output format of the LaTeX run is given by <code>PDF</code> currently.
    * <p>
    * Logs a warning or an error if running latexmk failed.
    * <p>
    * Logging:
    * <ul>
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * if running the latexmk command failed.
    * </ul>
    *
    * @param desc
    *     the description of a latex main file <code>texFile</code>
    *     to be processed.
    * @throws BuildFailureException
    *     TEX01 if invocation of the latexmk command returned by
    *     {@link Settings#getLatexmkCommand()} failed.
    */
   private void runLatexmk(LatexMainDesc desc) 
     throws BuildFailureException {
 
     File texFile = desc.texFile;
     // FIXME: wrong name; better is latex2dev
 
     String command = this.settings.getLatexmkCommand();
 
     String[] args = buildLatexmkArguments(settings, desc);
     this.log.debug("Running " + command + " on '" + texFile.getName() + "'. ");
     // may throw BuildFailureException TEX01,
     // may log warning EEX01, EEX02, WEX05
     // special: PDF file must exist after but need not be updated 
     this.executor.executeBuild(desc.parentDir, // workingDir
         this.settings.getTexPath(), command, args, desc.pdfFile);//
     // TBD: desc.withSuffix(SUFFIX_HTML): maybe depending on Target
   }
 
   // also for tests
   // TBD: eliminate magic comments: occur in Settings and also in .latexmkrc 
   protected static String[] buildLatexmkArguments(Settings settings,
       LatexMainDesc desc) throws BuildFailureException {
 
     // running specific compiler given in magic comment 
     // Optional<String> programMagic =
     //     desc.groupMatch(LatexMainParameterNames.programMagic);
     List<String> addArgs = new ArrayList<String>();
     // if (programMagic.isPresent()) {
     //   addArgs.add("-e");
     //   addArgs.add("$programMagic=q/" + programMagic.get() + "/");
     // }
 
     // running with specific time stamp if required in magic comment 
     // Optional<String> chkDiffMagic =
     //     desc.groupMatch(LatexMainParameterNames.chkDiffMagic);
     // if (chkDiffMagic.isPresent()) {
     //   addArgs.add("-e");
     //   // isChkDiff implements the same except for latexmk 
     //   Optional<String> chkDiffMagicValue =
     //   desc.groupMatch(LatexMainParameterNames.chkDiffMagicVal);
     //   String chkDiffMagicValueStr = chkDiffMagicValue.isPresent()
     //   ? chkDiffMagic.get() 
     //   : Boolean.TRUE.toString();// default=true if value not present 
     //   addArgs.add("$chkDiffMagic=q/" + chkDiffMagicValueStr + "/");
     // }
 
     // create arguments, both from settings and 
     // the optional ones from magic comments 
     return buildArguments(settings.getLatexmkOptions(), desc.texFile,
         addArgs.toArray(new String[addArgs.size()])
     );
   }
 
   /**
    * Runs the LaTeX command given by {@link #getLatex2pdfCommand()}
    * on the latex main file <code>texFile</code>
    * described by <code>desc</code>
    * in the directory containing <code>texFile</code> with arguments 
    * given by {@link #buildLatexArguments(Settings, LatexDev, File, boolean)}.
    * The output format of the LaTeX run is given by <code>dev</code>,
    * to be more precise by {@link LatexDev#getLatexOutputFormat()}.
    * <p>
    * Logs a warning or an error if the latex run failed
    * invoking {@link #logErrs(File, String)}
    * but not if bad boxes occurred or if warnings occurred.
    * This is done in
    * {@link #processLatex2dev(LatexMainDesc, LatexDev)}
    * after the last LaTeX run only.
    * <p>
    * Logging:
    * <ul>
    * <li>EAP01: Running <code>latex2pdf</code> failed. For details...
    * <li>EAP02: Running <code>latex2pdf</code> failed. No log file
    * <li>WAP04: .log-file is not readable.
    * <li>WFU03: cannot close .log-file
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * if running the latex2pdf command failed.
    * </ul>
    *
    * @param desc
    *     the description of a latex main file <code>texFile</code>
    *     to be processed.
    * @param dev
    *     the device describing the output format 
    *     which is either pdf or dvi.
    *     See {@link LatexDev#getLatexOutputFormat()}.
    * @throws BuildFailureException
    *     TEX01 if invocation of the latex2pdf command returned by
    *     {@link #getLatex2pdfCommand()} failed.
    */
   private void runLatex2dev(LatexMainDesc desc,
                             LatexDev dev)
       throws BuildFailureException {
 
     File texFile = desc.texFile;
     // FIXME: wrong name; better is latex2dev
     String command = getLatex2pdfCommand();
     this.log.debug("Running " + command + " on '" + texFile.getName() + "'. ");
     // TBD: this is not completely correct. 
     // A wrapper of xelatex would not be recognized. 
     // boolean isTypeXelatex =
     //     Converter.XeLatex.getCommand().equals(settings.getLatex2pdfCommand());
     boolean isTypeXelatex =
         Converter.XeLatex.getCommand().equals(command);
     String[] args =
         buildLatexArguments(this.settings, dev, texFile, isTypeXelatex);
     File latexTargetFile = dev.latexTargetFile(desc, isTypeXelatex);
     // may throw BuildFailureException TEX01,
     // may log warning EEX01, EEX02, EEX03, WEX04, WEX05
     // CAUTION: an error also occurs if running xelatex in conjunction with dvi mode 
     // because this engine creates xdv instead of dvi 
     this.executor.executeEnvR0(desc.parentDir, // workingDir
         this.settings.getTexPath(), command, args,
         latexTargetFile);
 
     // logging errors (warnings are done in processLatex2pdf)
     // may log EAP01, EAP02, WAP04, WFU03
     logErrs(desc.logFile, command);
 
     // FIXME: documentation that in the dvi file,
     // png, jpg and svg are not visible, but present. 
   }
 
   // also for tests
   protected static String[] buildLatexArguments(Settings settings, LatexDev dev,
       File texFile, boolean isTypeXelatex) throws BuildFailureException {
     // FIXME: here it should be taken xelatex into account, using different settings: 
     // added is dev==pdf, then nothing, else dev==dvi it is "-no-pdf". 
     String options = settings.getLatex2pdfOptions();
     if (dev.isDefault()) {
       return buildArguments(options, texFile);
     }
       // Here we shall create dvi or xdv file 
       // FIXME: this shall be based on analysis of the options of the converter, 
       // not on its name 
     return buildArguments(options, texFile, 
       isTypeXelatex ? "-no-pdf"
                     : "-output-format=" + dev.getLatexOutputFormat());
   }
 
   /**
    * Runs conversion from dvi or xdv to pdf-file
    * executing {@link #getDvi2pdfCommand()}
    * on a dvi/xdv-file covered by <code>desc</code> with arguments
    * given by {@link #buildLatexArguments(Settings, LatexDev, File, boolean)}. 
    * Note that this works only because all converter of the according category 
    * can convert both dvi and xdv 
    * and apply also on the filename without extension. 
    * If both files are present, the xdv file is processed. 
    * <p>
    * Logging:
    * <ul>
    * WLP07: if both dvi and xdv files are present.
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * if running the dvi2pdf command failed.
    * </ul>
    *
    * @param desc
    *     the description of a latex main file 
    *     <code>dviFile</code> or <code>xdvFile</code>
    *     including the dvi-file dvi2pdf is to be run on.
    * @throws BuildFailureException
    *     TEX01 if invocation of the dvi2pdf command returned by
    *     {@link #getDvi2pdfCommand()} failed.
    */
   // used in processLatex2pdf(File) and processLatex2txt(File) only
   private void runDvi2pdf(LatexMainDesc desc)
       throws BuildFailureException {
     assert this.settings.getPdfViaDvi().isViaDvi();
 
     String command = getDvi2pdfCommand();
     // use desc.xxxFile rather than desc.dviFile, 
     // because we have to treat both, dvi and xdv
     // TBD: warning if both are present; then xdv is preferred. 
     if (desc.dviFile.exists() && desc.xdvFile.exists()) {
       this.log.warn("WLP07: Found both '" + desc.dviFile + "' and '"
           + desc.xdvFile + "'; convert the latter. ");
     }
     this.log
         .debug("Running " + command + " on '" + desc.xxxFile.getName() + "'. ");
     String[] args =
         buildArguments(this.settings.getDvi2pdfOptions(), desc.xxxFile);
     // may throw BuildFailureException TEX01,
     // may log warning EEX01, EEX02, EEX03, WEX04, WEX05
     this.executor.executeEnvR0(desc.parentDir, // workingDir
         this.settings.getTexPath(), command, args, desc.pdfFile);
     // FIXME: what about error logging?
     // Seems not to create a log-file. 
   }
 
   /**
    * Runs the tex4ht command given by {@link Settings#getTex4htCommand()}
    * on <code>texFile</code> described by <code>desc</code>
    * in the directory containing <code>texFile</code>
    * with arguments given by {@link #buildHtlatexArguments(Settings, File)}.
    * <p>
    * Logging:
    * <ul>
    * <li>EAP01: Running <code>htlatex</code> failed. For details...
    * <li>EAP02: Running <code>htlatex</code> failed. No log file
    * <li>WLP03: <code>htlatex</code> created bad boxes
    * <li>WLP04: <code>htlatex</code> emitted warnings
    * <li>WAP04: log file is not readable.
    * <li>WFU03: cannot close log file
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * if running the tex4ht command failed.
    * </ul>
    *
    * @param desc
    *     the description of a latex main file <code>texFile</code>
    *     to be processed.
    * @throws BuildFailureException
    *     TEX01 if invocation of the tex4ht command
    *      returned by {@link Settings#getTex4htCommand()} failed.
    */
   private void runLatex2html(LatexMainDesc desc) throws BuildFailureException {
 
     File texFile = desc.texFile;
     String command = this.settings.getTex4htCommand();
     this.log.debug("Running " + command + " on '" + texFile.getName() + "'. ");
     String[] args = buildHtlatexArguments(this.settings, texFile);
     // may throw BuildFailureException TEX01,
     // may log warning EEX01, EEX02, EEX03, WEX04, WEX05
     this.executor.executeEnvR0(desc.parentDir, // workingDir
         this.settings.getTexPath(), command, args,
         desc.withSuffix(SUFFIX_HTML));
 
     // logging errors and warnings
     // may log EAP01, EAP02, WAP04, WFU03
     logErrs(desc.logFile, command);
     // may log warnings WFU03, WAP04, WLP03, WLP04
     logWarns(desc.logFile, command);
   }
 
   protected static String[] buildHtlatexArguments(Settings settings,
       File texFile) {
     return new String[] {texFile.getName(), 
       settings.getTex4htStyOptions(),
       settings.getTex4htOptions(), 
       settings.getT4htOptions(),
       settings.getLatex2pdfOptions()};
   }
 
   /**
    * Runs the latex2rtf command
    * given by {@link Settings#getLatex2rtfCommand()}
    * on <code>texFile</code>
    * in the directory containing <code>texFile</code>
    * with arguments given by {@link #buildArguments(String, File, String...)}.
    * <p>
    * Logging:
    * <ul>
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * if running the latex2rtf command failed.
    * </ul>
    *
    * @param texFile
    *     the latex file to be processed.
    * @throws BuildFailureException
    *     TEX01 if invocation of the latex2rtf command
    *     returned by
    *     {@link Settings#getLatex2rtfCommand()} failed.
    */
   private void runLatex2rtf(File texFile) throws BuildFailureException {
     String command = this.settings.getCommand(ConverterCategory.LaTeX2Rtf);
     this.log.debug("Running " + command + " on '" + texFile.getName() + "'. ");
     String[] args =
         buildArguments(this.settings.getLatex2rtfOptions(), texFile);
     // may throw BuildFailureException TEX01,
     // may log warning EEX01, EEX02, EEX03, WEX04, WEX05
     this.executor.executeEnvR0(texFile.getParentFile(), // workingDir
         this.settings.getTexPath(), command, args,
         TexFileUtils.replaceSuffix(texFile, SUFFIX_RTF));
 
     // FIXME: no check: just warning that no output has been created.
     // Warnings and error messages are output to stderr
     // and by default listed in the console window.
     // aThey can be redirected to a file “latex2rtf.log” by
     // appending 2>latex2rtf.log to the command line.
   }
 
   /**
    * Runs conversion from latex to odt
    * executing {@link Settings#getTex4htCommand()}
    * on <code>texFile</code>
    * in the directory containing <code>texFile</code> with arguments
    * given by {@link #buildLatexArguments(Settings, LatexDev, File, boolean)}.
    * <p>
    * Logs a warning or an error if the latex run failed
    * invoking {@link #logErrs(File, String)}
    * but not if bad boxes ocurred or if warnings occurred.
    * This is done in
    * {@link #processLatex2dev(LatexMainDesc, LatexDev)}
    * after the last LaTeX run only.
    * <p>
    * Logging:
    * <ul>
    * <li>EAP01: Running <code>htlatex</code> failed. For details...
    * <li>EAP02: Running <code>htlatex</code> failed. No log file
    * <li>WLP03: <code>htlatex</code> created bad boxes
    * <li>WLP04: <code>htlatex</code> emitted warnings
    * <li>WAP04: log file is not readable.
    * <li>WFU03: cannot close log file
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * if running the tex4ht command failed.
    * </ul>
    *
    * @param desc
    *     the descriptor of the latex main file to be processed.
    * @throws BuildFailureException
    *     TEX01 if invocation of the tex4ht command
    *     returned by {@link Settings#getTex4htCommand()} failed.
    */
   private void runLatex2odt(LatexMainDesc desc) throws BuildFailureException {
     File texFile = desc.texFile;
     String command = this.settings.getTex4htCommand();
     this.log.debug("Running " + command + " on '" + texFile.getName() + "'. ");
     String[] args = new String[] {texFile.getName(), "xhtml,ooffice", // there is no choice here
         "ooffice/! -cmozhtf", // ooffice/! represents a font direcory
         "-coo -cvalidate"// -coo is mandatory, -cvalidate is not
     };
     // may throw BuildFailureException TEX01,
     // may log warning EEX01, EEX02, EEX03, WEX04, WEX05
     this.executor.executeEnvR0(desc.parentDir, this.settings.getTexPath(), command,
         args, desc.withSuffix(SUFFIX_ODT));
 
     // FIXME: logging refers to latex only, not to tex4ht or t4ht script
     // may log EAP01, EAP02, WAP04, WFU03
     logErrs(desc.logFile, command);
     // may log warnings WFU03, WAP04, WLP03, WLP04
     logWarns(desc.logFile, command);
   }
 
   // FIXME: missing options.
   // above all (input) doctype: -ddoc, -ddocx
   // and (output) doctype: -fdoc, -fdocx,
   // available: odt2doc --show.
   // among those also: latex and rtf !!!!!!
   // This is important to define the copy filter accordingly
   /**
    * Runs conversion from odt to doc or docx-file
    * executing {@link Settings#getOdt2docCommand()}
    * on an odt-file created from <code>texFile</code>
    * in the directory containing <code>texFile</code> with arguments
    * given by {@link #buildLatexArguments(Settings, LatexDev, File, boolean)}.
    * <p>
    * Logging:
    * <ul>
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * if running the odt2doc command failed.
    * </ul>
    *
    * @param desc
    *     the description of a latex main file <code>texFile</code>
    *     to be processed.
    * @throws BuildFailureException
    *     TEX01 if invocation of the odt2doc command returned by
    *     {@link Settings#getOdt2docCommand()} failed.
    */
   private void runOdt2doc(LatexMainDesc desc) throws BuildFailureException {
     File odtFile = desc.withSuffix(SUFFIX_ODT);
     String command = this.settings.getCommand(ConverterCategory.Odt2Doc);
     this.log.debug("Running " + command + " on '" + odtFile.getName() + "'. ");
     String[] args = buildArguments(this.settings.getOdt2docOptions(), odtFile);
     String suffix = null;
     for (int idx = 0; idx < args.length - 1; idx++) {
       // FIXME: -f is hardcoded
       if (args[idx].startsWith("-f")) {
         assert suffix == null;// -f comes once only
         // without leading '-f'
         suffix = args[idx].substring(2, args[idx].length());
       }
     }
     // FIXME: no validity check on suffix 
     assert suffix != null;
     // may throw BuildFailureException TEX01,
     // may log warning EEX01, EEX02, EEX03, WEX04, WEX05
     this.executor.executeEnvR0(desc.parentDir, this.settings.getTexPath(), command,
         args, desc.withSuffix(suffix));
     // FIXME: what about error logging?
     // Seems not to create a log-file.
   }
 
   /**
    * Runs conversion from pdf to txt-file
    * executing {@link Settings#getPdf2txtCommand()}
    * on a pdf-file created from <code>texFile</code>
    * in the directory containing <code>texFile</code> with arguments
    * given by {@link #buildLatexArguments(Settings, LatexDev, File, boolean)}.
    * <p>
    * Logging:
    * <ul>
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * if running the pdf2txt command failed.
    * </ul>
    *
    * @param desc
    *     the description of a latex main file <code>texFile</code>
    *     to be processed.
    * @throws BuildFailureException
    *     TEX01 if invocation of the pdf2txt command returned by
    *     {@link Settings#getPdf2txtCommand()} failed.
    */
   private void runPdf2txt(LatexMainDesc desc) throws BuildFailureException {
     File pdfFile = desc.withSuffix(SUFFIX_PDF);
     String command = this.settings.getCommand(ConverterCategory.Pdf2Txt);
     this.log.debug("Running " + command + " on '" + pdfFile.getName() + "'. ");
     String[] args = buildArguments(this.settings.getPdf2txtOptions(), pdfFile);
     // may throw BuildFailureException TEX01,
     // may log warning EEX01, EEX02, EEX03, WEX04, WEX05
     this.executor.executeEnvR0(desc.parentDir, this.settings.getTexPath(), command,
         args, desc.withSuffix(SUFFIX_TXT));
     // FIXME: what about error logging?
     // Seems not to create a log-file.
   }
 
   void processCheck(LatexMainDesc desc) throws BuildFailureException {
     this.log.info("Checking source. ");
     runChktex(desc);
   }
 
   /**
    * Runs the check command given by {@link Settings#getChkTexCommand()}
    * on the latex main file <code>texFile</code>
    * in the directory containing <code>texFile</code>
    * creating a log file with ending {@link #SUFFIX_CLG}
    * in that directory.
    * <p>
    * Logging:
    * <ul>
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * if running the ChkTeX command failed.
    * </ul>
    *
    * @param desc
    *    the description of a latex main file <code>texFile</code>
    *    to be processed.
    * @throws BuildFailureException
    *     TEX01 if invocation of the check command
    *     returned by {@link Settings#getChkTexCommand()} failed.
    */
   private void runChktex(LatexMainDesc desc) throws BuildFailureException {
     File texFile = desc.texFile;
     File clgFile = desc.withSuffix(SUFFIX_CLG);
     String command = this.settings.getCommand(ConverterCategory.LatexChk);
     this.log.debug("Running " + command + " on '" + texFile.getName() + "'. ");
     String[] args = buildChkTexArguments(this.settings.getChkTexOptions(),
         texFile, clgFile);
     // may throw BuildFailureException TEX01,
     // may log warning EEX01, EEX02, EEX03, WEX04, WEX05
     CommandExecutor.CmdResult res = this.executor.executeEmptyEnv(
         texFile.getParentFile(), this.settings.getTexPath(), command,
         CommandExecutor.ReturnCodeChecker.IsOne, args, clgFile);
     switch (res.returnCode) {
       case 0: // all ok 
         if (clgFile.exists() && clgFile.length() != 0) {
           this.log.info("Checker '" + command + "' logged a message in '"
               + clgFile.getName() + "'. ");
         }
         break;
       case 1: // execution error already treated in executor; 
         // nothing to be done. 
         // see CommandExecutor.ReturnCodeChecker.isOne.hasFailed
         break;
       case 3: // no execution error but check found error 
         this.log.error("ELP02: Checker '" + command + "' logged an error in '"
             + clgFile.getName() + "'. ");
         break;
       case 2: // no execution error and no error but warning. 
         this.log.warn("WLP08: Checker '" + command + "' logged a warning in '"
             + clgFile.getName() + "'. ");
         break;
       default:
         logErrUnexpectedReturnCode(command, res);
     }
     // Possibly, if not using the -q option 
     // the status messages delivers even more pieces of information. 
     // Maintain this, to indicate why WLP06 does not occur any more. 
     // if (!clgFile.exists()) {
     //     // Here, chktex could not perform the check
     //     // but the failure is already logged.
     //     return;
     // }
     // // assert !clgFile.isDirectory();
     // if (clgFile.length() != 0) {
     //     this.log.warn("WLP06: Running " + command +
     //             " found issues logged in '" +
     //             texFile.getName() + "'. ");
     // }
   }
 
   /**
    * Logs an error on command <code>command</code> if the result <code>command</code> 
    * returned an unexpected return value. 
    * This method shall be used for checker commands only. 
    * The background is, that an error like that comes from a change in the application 
    * which needs adaption of this software. 
    * The error is the trigger for further development. 
    * 
    * @param command
    *    the ckecker command which returned an unexpected return value. 
    * @param res
    *    the result with unexpected return value. 
    */
   private void logErrUnexpectedReturnCode(String command, CommandExecutor.CmdResult res) {
         this.log.error("ELP01: For command '" + command
             + "' found unexpected return code " + res.returnCode + ". ");
   }
 
   /**
    * Runs the validation command for PDF format given by {@link Settings#getcommand
    * @param desc
    * @throws BuildFailureException
    */
   private void runValidatePdf(LatexMainDesc desc) throws BuildFailureException {
     File pdfFile = desc.pdfFile;
     String command = this.settings.getCommand(ConverterCategory.StandardValidator);
     this.log.debug("Running " + command + " on '" + pdfFile.getName() + "'. ");
     String[] args = buildArguments(this.settings.getChkTexOptions(), pdfFile);
     // may throw BuildFailureException TEX01,
     // may log warning EEX01, EEX02, EEX03, WEX04, WEX05
     CommandExecutor.CmdResult res = this.executor.executeEmptyEnv(
         pdfFile.getParentFile(), this.settings.getTexPath(), command,
         CommandExecutor.ReturnCodeChecker.IsNotZeroOrOne, args);
         // TBD: display the standards. 
         // TBD: clarify how to use verapdf output 
         switch (res.returnCode) {
           case 0: // check executed and passed
             this.log.info("Validation of '" + pdfFile.getName() + "' passed. ");
             break;
           case 1: // check executed and failed
             this.log.warn("XXX: Validation of '" + pdfFile.getName() + "' failed. ");
             break;
           case 2:
           case 3:
           case 4:
             // case 5 is missing 
           case 6:
           case 7:
           case 8:
           case 9:
           case 10:
           case 11:
           case 12: // execution error already treated in executor;
             // nothing to be done.
             // see CommandExecutor.ReturnCodeChecker.IsNotZeroOrOne.hasFailed
             break;
           default:
             logErrUnexpectedReturnCode(command, res);
         }
       }
 
 
 
   /**
    * Returns an array of strings,
    * each entry with a single option given by <code>options</code>
    * except the last three which represent <code>-o clgFile texFile</code>.
    *
    * @param options
    *     the options string. The individual options
    *     are expected to be separated by a single blank.
    * @param texFile
    *     the latex main file to be checked.
    * @param clgFile
    *     the log-file with the result of the check of
    *     <code>texFile</code>.
    * @return
    *     An array of strings:
    *     If <code>options</code> is not empty,
    *     the first entries are the options in <code>options</code>.
    *     The last three entries are
    *     <code>-o</code>, <code>clgFile</code> and <code>texFile</code>.
    */
   protected static String[] buildChkTexArguments(String options, File texFile,
       File clgFile) {
     return buildArguments(options, texFile, "-o", clgFile.getName());
   }
 
   /**
    * Returns whether the given pdf files coincide
    * running the diff tool specified
    * by {@link Settings#getCommand(ConverterCategory)}
    * with {@link ConverterCategory#DiffPdf}. 
    * For a checker method the return value is quite unusual: 
    * It causes a break of the process. 
    *
    * Logging:
    * <ul>
    * <li>EEX01, EEX02, EEX03, WEX04, WEX05:
    * if running the ChkTeX command failed.
    * </ul>
    * 
    * 
    * @param pdfFileCmp
    *     the pdf file for comparison
    * @param pdfFileAct
    *     the pdf file actually created.
    * @return
    *     whether <code>pdfFileAct</code> could be checked to be coincideswith
    *     <code>pdfFileCmp</code>. 
    *     This is false whether the check failed or the check could not be performed. 
    * @throws BuildFailureException
    *      TEX01 if invocation of the diff command failed. 
    * @see #runChktex(LatexMainDesc)
    */
   private boolean runDiffPdf(File pdfFileCmp, File pdfFileAct)
       throws BuildFailureException {
     //
     // File clgFile = TexFileUtils.replaceSuffix(texFile, SUFFIX_CLG);
     String command = this.settings.getCommand(ConverterCategory.DiffPdf);
     this.log.debug("Running " + command + " diffing '" + pdfFileCmp.getName()
         + "' and '" + pdfFileAct.getName() + "'. ");
     // String[] args = buildChkTexArguments(this.settings.getChkTexOptions(),
     // texFile,
     // clgFile);
     String[] args = new String[] {pdfFileCmp.toString(), pdfFileAct.toString()};
 
     // may throw BuildFailureException TEX01,
     // may log warning EEX01, EEX02, EEX03, WEX04, WEX05
     CmdResult res = this.executor.executeEmptyEnv(null, // texFile.getParentFile(),
         this.settings.getTexPath(), command,
         CommandExecutor.ReturnCodeChecker.IsNotZeroOrOne, args);
     // other value 2 caused an exception before 
     //assert returnCode == 0 || returnCode == 1 : "diff unexpected return value "+returnCode;
     // 0 means that the files 'coincide', 
     // where as 2 means that there is a significant difference 
     int returnCode = res.returnCode;
     switch (returnCode) {
       case 0:
         // Here, files could be diffed and coincide. 
         // treated outside via return value 
        break;
       case 1:
         // Here, files could be diffed but do not coincide 
         // treated outside via return value 
         break;
      case 2:
         // Here, files could not be diffed because of an error in command 
         // This is already treated in executor 
         // see CommandExecutor.ReturnCodeChecker.IsNotZeroOrOne
         // Nevertheless, the return value is part of the treatment. 
         break;
       default:
         logErrUnexpectedReturnCode(command, res);
     }
       return returnCode == 0;
   }
 
   // run pdfinfo or that like
   // in the long should return a map for metdatata. 
   // currently it is the create time as epoch 
   /**
    * Returns the meta info <code>CreationDate</code> of <code>pdfFile</code>, 
    * which is in fact date and time, as epoch time in seconds 
    * by invoking a tool like <code>prefinfo</code>. 
    * @param pdfFile
    * @return
    *    <code>CreationDate</code> as epoch time. 
    * @throws BuildFailureException
    */
   long runPdfInfo(File pdfFile) throws BuildFailureException {
     //System.out.println("pdfinfo on "+pdfFile);
     String command = this.settings.getCommand(ConverterCategory.MetaInfoPdf);
     this.log.debug("Running " + command + " extracting metainformation from '" + pdfFile.getName() + "''. ");
     // TBD: neither of this works really. first yields wrong pdf, second does not work with more than 1 option 
     //String[] args = buildArguments(this.settings.getPdfMetainfoOptions(), pdfFile);
     String[] args = new String[] {this.settings.getPdfMetainfoXmpOptions(), pdfFile.toString()};
     CmdResult res = this.executor.executeEmptyEnv(null, // texFile.getParentFile(),
         this.settings.getTexPath(), command,
         CommandExecutor.ReturnCodeChecker.IsNonZero, args);
     //System.out.println("pdfinfo yields\n"+res.output);
     // TBD: eliminate literal 
 
     String patternString;
     if (res.output.isEmpty()) {
       // no XMP data, fallback 
       System.out.println("no xmp");
       args = new String[] {this.settings.getPdfMetainfoOptions(), pdfFile.toString()};
       res = this.executor.executeEmptyEnv(null, // texFile.getParentFile(),
         this.settings.getTexPath(), command,
         CommandExecutor.ReturnCodeChecker.IsNonZero, args);
         patternString = "CreationDate:\\s*(?<creationDate>.*?)\\R";
     } else {
       // Here, XMP data is available and latex then writes date into it 
       patternString = "<xmp:CreateDate>(?<creationDate>.*?)</xmp:CreateDate>\\R";
     }
     Pattern pattern = Pattern.compile(patternString);
     Matcher matcher = pattern.matcher(res.output);
 
    if (!matcher.find()) {
       // TBD: rethink 
       throw new RuntimeException("Found no creation date");
     }
     String creationDateIso8601 = matcher.group("creationDate");// TBD: eliminate literal 
     long epochTimeSec = ZonedDateTime.parse(creationDateIso8601).toEpochSecond();
     //long epochTimeSec = Instant.parse(creationDateIso8601).getEpochSecond();
 
     // String[] lines = res.output.split("\\R");
     // for (String line : lines) {
     //   line
     // }
 
     return epochTimeSec;
     
   }
 
   /**
    * The folder in the jar-file containing this application 
    * containing the files of the {@link Injection}s. 
    */
   private static final String FOLDER_INJ = "injections/";
 
   /**
    * Processes injection of files 
    * like <code>.latexmkrc</code> and <code>.chktexrc</code> 
    * as described by <code>injections</code>, e.g. 
    * <ul>
    * <li> performing filtering similar to the resources plugin, </li>
    * <li> turning the result into an executable file, 
    * </ul>
    * Filtering differs from the mechanism of the resources plugin 
    * in two respects: 
    * <ul>
    * <li> The names are those of parameters in settings, 
    * not properties in the pom. </li>
    * <li> The sources are loaded as a resource by the classloader 
    * by name <code>.latexmkrc</code> and <code>.chktexrc</code>, respectively. 
    * They are a kind of templates containing parameter names 
    * and the target is a file in the folder 
    * given by {@link Settings#getTexSrcDirectoryFile()}. 
    * This file contains the values of the parameters, finally. 
    * </ul>
    * 
    * may log: 
    * <ul>
    * <li> WFU10: if the file has not been created by this software 
    * <li> WFU11: if it cannot be ensured that the file has been created 
    *      by this software </li>
    *      or if the reader to read to decide cannot be closed. </li>
    * </ul>
    * 
    * @param injections
    *   define the files to be injected and how injection is done. 
    * @throws BuildFailureException
    *   <ul>
    *   <li>
    *   TLP03: Failure while writing file '...' or closing in-stream. 
    *   The file is created from a template replacing parameter names 
    *   by their actual values. 
    *   A reason may be that the template cannot be read 
    *   or its in-stream cannot be closed. </li>
    *   <li> TMI01: if the stream to the template cannot be read. </li>
    *   <li> TMI01: if the stream to the according properties file 
    *        could not be created </li>
    *   <li> TMI02: if the properties could not be read. </li>
    *   </ul>
    */
   //      
   public void processFileInjections(Set<Injection> injections)
       throws BuildFailureException {
     //this.settings.getProperties();
     // TBD: centralize this because also needed for goal clr
 
     for (Injection inj : injections) {
       String fileName = inj.getFileName();
       // may throw TMI01
       InputStream inStream = MetaInfo.getStream(FOLDER_INJ+fileName);
       File outFile = this.settings.rcResourceToFile(fileName);
 
       try {
         // isCreatedByMyself may emit warnings WFU10, WFU11 
         if (!outFile.exists()
             || this.fileUtils.isCreatedByMyself(outFile, inj)) {
           // Here, outFile does not exist or is a regular file. 
 
           // may throw FileNotFoundException and so IOException: 
           // if does not exist 
           // and a regular file of that name cannot be created for writing 
           // or if it does exist and cannot be opened for writing, 
           // or if some error occurs when creating or opening for writing 
           PrintStream writer = new PrintStream(outFile);
           // may throw IOException: readline. 
           // may throw TMI01, TMI02
           String version = this.metaInfo.getCoordinates().version;
           this.settings.filterInjection(inStream, writer, version, inj);
         }
         // may throw IOExeption 
         inStream.close();
       } catch (IOException ioe) {
         // Here, the goal inj must be aborted, or inStream could not be closed. 
         // THis is true not only when the Print stream cannot be created, 
         // but also if the resource cannot be read in filterRcFile. 
         // To be strict, one could go on even if inStream could not be closed. 
         throw new BuildFailureException("TLP03 Failure while writing file '"
             + fileName + "' or closing in-stream. ", ioe);
       }
 
       boolean success = outFile.setExecutable(inj.setExecutable(), false);
       assert success || !inj.setExecutable();
     }
   }
 
   /**
    * Deletes injected files if written by this software if possible. 
    * 
    * WFU10, WFU11: if a config file is not written by this software 
    *               or it is not clear or the reader cannot close. 
    * EFU05: if the config file shall be deleted but this coes not work. 
    */
   private void clearInjFiles() {
     for (Injection inj : Injection.values()) {
       File outFile = this.settings.rcResourceToFile(inj.getFileName());
       // isCreatedByMyself may emit warnings WFU10, WFU11 
       if (outFile.exists() && this.fileUtils.isCreatedByMyself(outFile, inj)) {
         // could emit EFU05
         this.fileUtils.deleteOrError(outFile, false);
       }
     }
   }
 
 }