/*
 * [MkDesc.java]
 *
 * Summary: Handles TCC file descriptions.
 *
 * Copyright: (c) 2009-2017 Roedy Green, Canadian Mind Products, http://mindprod.com
 *
 * Licence: This software may be copied and used freely for any purpose but military.
 *          http://mindprod.com/contact/nonmil.html
 *
 * Requires: JDK 1.8+
 *
 * Created with: JetBrains IntelliJ IDEA IDE http://www.jetbrains.com/idea/
 *
 * Version History:
 *  1.0 2007-05-12 initial version.
 */
package com.mindprod.zzz;

import com.mindprod.common18.EIO;
import com.mindprod.common18.ST;
import com.mindprod.fastcat.FastCat;

import java.nio.charset.Charset;

import static com.mindprod.zzz.CompilerCat.JAVA;

/**
 * Handles TCC file descriptions.
 *
 * @author Roedy Green, Canadian Mind Products
 * @version 1.0 2007-05-12 initial version.
 * @since 2009
 */
class MkDesc extends ProjectInfo
    {
    /**
     * encoding for writing bat and btm files
     */
    private static final Charset BAT_ENCODING = EIO.WINDOWS1252;

    /**
     * Copy constructor
     *
     * @param pi Copy constructor to extend class
     */
    @SuppressWarnings( { "SameParameterValue" } )
    MkDesc( ProjectInfo pi )
        {
        super( pi );
        }

    /**
     * prepare one line for the TCC describe utility to describe no file.
     *
     * @param file        unqualified name of file
     * @param description of what the file does for DESCRIPT.ION file
     *
     * @return one line bat command with \n.
     */
    private static String describe( String file, String description )
        {
        final FastCat sb = new FastCat( 5 );
        sb.append( '\"' );
        sb.append( file );
        sb.append( "\" " );
        sb.append( description );
        sb.append( "\n" );
        return sb.toString();
        }

    /**
     * prepare one line for the TCC describe utility to describe no file.
     *
     * @param file        unqualified name of file
     * @param description of what the file does
     *
     * @return one line bat command with \n.
     */
    private static String describeOther( String file, String description )
        {
        final FastCat sb = new FastCat( 7 );
        sb.append( "if exist \"" );
        sb.append( file );
        sb.append( "\" describe \"" );
        sb.append( file );
        sb.append( "\" /D\"" );
        sb.append( description );
        sb.append( "\"\n" );
        return sb.toString();
        }

    /**
     * prepare descriptions for java files
     *
     * @return generated ant script.
     */
    private String descAsms()
        {
        if ( compilerCat == CompilerCat.ASM )
            {
            final FastCat sb = new FastCat( 4 + altSourceNames.length * 4 + 2 );
            if ( hasMainProg )
                {
                sb.append( describe( mainSourceName,
                        mainClassName + " main DOS asm program source" ) );
                sb.append( describe( mainClassName + ".obj",
                        "generated: " + mainClassName + " main DOS asm program linkable object" ) );
                sb.append( describe( mainClassName + ".lst",
                        "generated: " + mainClassName + " main DOS asm program assembler listing" ) );
                sb.append( describe( mainClassName + ".map",
                        "generated: " + mainClassName + " main DOS asm program linker output" ) );
                }
            for ( int i = 0; i < altSourceNames.length; i++ )
                {
                sb.append( describe( altSourceNames[ i ]
                        ,
                        altAppNames[ i ]
                        + " alt asm program source"
                ) );
                sb.append( describe( altAppNames[ i ] + ".obj",
                        "generated: " + altAppNames[ i ] + " alt DOS asm program linkable object" ) );
                sb.append( describe( altAppNames[ i ] + ".lst",
                        "generated: " + altAppNames[ i ] + " alt DOS asm program assembler listing" ) );
                sb.append( describe( altAppNames[ i ] + ".map",
                        "generated: " + altAppNames[ i ] + " alt DOS asm program linker output" ) );
                }
            switch ( appCat )
                {
                case ASMCOM:
                    sb.append( describe( "a.bat",
                            "Assemble with MASM 6 and Link 5.6 to *.com" ) );
                    sb.append( describe( "o.bat",
                            "Assemble with OptAsm and OLink to *.com" ) );
                    break;
                case ASMEXE:
                    sb.append( describe( "ae.bat",
                            "Assemble with MASM 6 and Link 5.6 to *.exe" ) );
                    sb.append( describe( "oe.bat",
                            "Assemble with OptAsm and OLink to *.exe" ) );
                    break;
                default:
                    assert false : "program bug: invalid appCat";
                }
            return sb.toString();
            }
        else
            {
            return "";
            }
        }

    /**
     * prepare descriptions for bat and btm files
     *
     * @return description of *.bat files for DESCRIPT.ION file
     */
    private String descBats()
        {
        final FastCat sb = new FastCat( 5 );
        sb.append( describe( "desc.btm", "creates TCC file descriptions for project files" ) );
        sb.append( describe( "descother.btm", "creates TCC file descriptions for non-project files" ) );
        if ( hasMainProg )
            {
            sb.append( describe( "run.bat",
                    "execute the "
                    + mainClassName
                    + " application from the jar"
            ) );
            }
        if ( compilerCat == JAVA )
            {
            sb.append( describe( "grab.btm",
                    "copy in Java source code from IntelliJ and build it. Roedy's use only." ) );
            }
        return sb.toString();
        }

    /**
     * prepare descriptions for java files
     *
     * @return description of CPP files for DESCRIPT.ION file
     */
    private String descCPPs()
        {
        if ( compilerCat == CompilerCat.CPP )
            {
            final FastCat sb = new FastCat( 5 + altSourceNames.length * 5 );
            if ( hasMainProg )
                {
                sb.append( describe( mainSourceName,
                        mainClassName + " main C++ program source" ) );
                sb.append( describe( mainClassName + ".obj",
                        "generated: " + mainClassName + " main C++ program linkable object" ) );
                sb.append( describe( mainClassName + ".ncb",
                        "generated: " + mainClassName + " main C++ compiler intermediate file" ) );
                sb.append( describe( mainClassName + ".sln",
                        mainClassName + " main C++ project" ) );
                sb.append( describe( mainClassName + ".vcxproj",
                        mainClassName + " main C++ project" ) );
                }
            for ( int i = 0; i < altSourceNames.length; i++ )
                {
                sb.append( describe( altSourceNames[ i ]
                        /* alt.java */,
                        altAppNames[ i ]
                        + " alt C++ program source"
                ) );
                sb.append( describe( altAppNames[ i ] + ".obj",
                        "generated: " + altAppNames[ i ] + " alt C++ program linkable object" ) );
                sb.append( describe( altAppNames[ i ] + ".ncb",
                        "generated: " + altAppNames[ i ] + " alt C++ compiler intermediate file" ) );
                sb.append( describe( altAppNames[ i ] + ".sln",
                        altAppNames[ i ] + " alt C++ project" ) );
                sb.append( describe( altAppNames[ i ] + ".vcxproj",
                        altAppNames[ i ] + "alt C++ project" ) );
                }
            return sb.toString();
            }
        else
            {
            return "";
            }
        }

    /**
     * prepare descriptions for class files
     *
     * @return description of .class files for DESCRIPT.ION file.
     */
    private String descClasses()
        {
        if ( hasMainProg )
            {
            final FastCat sb = new FastCat( altAppNames.length + 1 );
            sb.append( describe( mainClassName + ".class",
                    mainClassName
                    + " main Java program compiled byte code"
            ) );
            for ( String altMainClass : altAppNames )
                {
                sb.append( describe( altMainClass + ".class",
                        "alternate Java program compiled byte code" ) );
                }
            return sb.toString();
            }
        else
            {
            return "";
            }
        }

    /**
     * prepare descriptions for java files
     *
     * @return description of *.C files for DESCRIPT.ION file
     */
    private String descCs()
        {
        if ( compilerCat == CompilerCat.C )
            {
            final FastCat sb = new FastCat( 5 + altSourceNames.length * 5 );
            if ( hasMainProg )
                {
                sb.append( describe( mainSourceName,
                        mainClassName + " main C program source" ) );
                sb.append( describe( mainClassName + ".obj",
                        "generated: " + mainClassName + " main C program linkable object" ) );
                sb.append( describe( mainClassName + ".ncb",
                        "generated: " + mainClassName + " main C compiler intermediate file" ) );
                sb.append( describe( mainClassName + ".sln",
                        mainClassName + " main C project" ) );
                sb.append( describe( mainClassName + ".vcxproj",
                        mainClassName + " main C project" ) );
                }
            for ( int i = 0; i < altSourceNames.length; i++ )
                {
                sb.append( describe( altSourceNames[ i ]
                        /* alt.java */,
                        altAppNames[ i ]
                        + " alt C program source"
                ) );
                sb.append( describe( altAppNames[ i ] + ".obj",
                        "generated: " + altAppNames[ i ] + " alt C program linkable object" ) );
                sb.append( describe( altAppNames[ i ] + ".ncb",
                        "generated: " + altAppNames[ i ] + " alt C compiler intermediate file" ) );
                sb.append( describe( altAppNames[ i ] + ".sln",
                        altAppNames[ i ] + " alt C project" ) );
                sb.append( describe( altAppNames[ i ] + ".vcxproj",
                        altAppNames[ i ] + "alt C project" ) );
                }
            return sb.toString();
            }
        else
            {
            return "";
            }
        }

    /**
     * prepare descriptions for exe/com files
     *
     * @return description of .exe files for DESCRIPT.ION file.
     */
    private String descExes()
        {
        final FastCat sb = new FastCat( 1 + altExeFilesUnqual.length );
        switch ( compilerCat )
            {
            default:
            case NONE:
                break;
            case JAVA:
                sb.append( descJetExes() );
                break;
            case ASM:
            {
            final FastCat sb2 = new FastCat( 4 );
            sb2.append( "DOS 16-bit executable to run the " );
            sb2.append( mainClassName );
            sb2.append( " program: " );
            sb2.append( description );
            sb.append( describe( mainExeFileUnqual
                    /* main.exe or main.com */,
                    sb2.toString() ) );
            for ( int i = 0; i < altExeFilesUnqual.length; i++ )
                {
                final FastCat sb3 = new FastCat( 3 );
                sb3.append( "DOS 16-bit executable to run the " );
                sb3.append( altAppNames[ i ] );
                sb3.append( " program" );
                sb.append( describe( altExeFilesUnqual[ i ]
                        /* alt.exe */,
                        sb3.toString() ) );
                }
            break;
            }
            case C:
            case CPP:
            {
            final FastCat sb2 = new FastCat( 4 );
            sb2.append( "Windows 32-bit executable to run the " );
            sb2.append( mainClassName );
            sb2.append( " program: " );
            sb2.append( description );
            sb.append( describe( mainExeFileUnqual
                    /* main.exe */,
                    sb2.toString() ) );
            for ( int i = 0; i < altExeFilesUnqual.length; i++ )
                {
                final FastCat sb3 = new FastCat( 3 );
                sb3.append( "Windows 32-bit executable to run the " );
                sb3.append( altAppNames[ i ] );
                sb3.append( " program" );
                sb.append( describe( altExeFilesUnqual[ i ]
                        /* alt.exe */,
                        sb3.toString() ) );
                }
            break;
            }
            }
        return sb.toString();
        }

    /**
     * prepare descriptions for html files
     *
     * @return description of *.html files for DESCRIPT.ION file
     * .
     */
    private String descHtmls()
        {
        final FastCat sb = new FastCat( 3 );
        if ( runsFromHtml )
            {
            sb.append( describe( projectLower + ".html",
                    "html to launch the "
                    + mainClassName
                    + " program"
            ) );
            }
        sb.append( describe( projectLower + ".manual.html",
                "detailed HTML manual for the "
                + projectHumanName
                + " project"
        ) );
        return sb.toString();
        }

    /**
     * prepare descriptions for misc junk JET creates with compiling
     *
     * @return description of misc Jet files for DESCRIPT.ION file.
     */
    private String descJETCompileJetsom()
        {
        if ( jetable )
            {
            final FastCat sb = new FastCat( 4 );
            sb.append( describe( projectLower + ".efs",
                    "generated: JET compiler internal file" ) );
            sb.append( describe( projectLower + ".rfs",
                    "generated: JET compiler control file" ) );
            sb.append( describe( projectLower + ".rsp",
                    "JET configuration file" ) );
            sb.append( describe( projectLower + ".usg",
                    "generated: JET compiler method use tracking" ) );
            return sb.toString();
            }
        else
            {
            return "";
            }
        }

    /**
     * prepare descriptions for files JET creates when distributing
     *
     * @return generated ant script.
     */
    private String descJETDistributeJetsom()
        {
        if ( compilerCat == CompilerCat.JAVA )
            {
            final FastCat sb = new FastCat( 9 );
            sb.append( describe( projectLower + "-setup.exe", "JET distributable, containing runtime" ) );
            sb.append( describe( projectLower + ".ico", "Windows icon for the project, " +
                                                        "contains multiple image sizes" ) );
            sb.append( describe( projectLower + ".jpn", "Manifest of what is included in the JET executable." ) );
            sb.append( describe( projectLower + ".log", "log of what JET did compiling and preparing the " +
                                                        "distributable" ) );
            sb.append( describe( projectLower + ".prj", "JET project configuration, " +
                                                        "compiler options and notes on what needs to be included." ) );
            sb.append( describe( projectLower + ".startup", "List of classes JET should preload for speed." ) );
            sb.append( describe( projectLower + ".xbind.script", "List of DLLs JET will need to run the app." ) );
            sb.append( describe( "build_" + projectLower + ".bat", "Build JET executable with project descriptor" ) );
            sb.append( describe( "run_" + projectLower + ".bat", "Runs the JET executable with default parm." ) );
            return sb.toString();
            }
        else
            {
            return "";
            }
        }

    /**
     * prepare descriptions for jar files, and files that go near them.
     *
     * @return description of .jar files for DESCRIPT.ION file..
     */
    private String descJars()
        {
        if ( hasJar )
            {
            final FastCat sb = new FastCat( 3 + altJarNames.length * 3 );
            sb.append( describe( mainJarName
                    /* *.jar */,
                    "jarred class files: "
                    + description
            ) );
            sb.append( describe( mainJarLookNameUnqual, "uncommented jar manifest" ) );
            for ( int i = 0; i < altJarNames.length; i++ )
                {
                sb.append( describe( altJarNames[ i ]
                        /* alt.jar */,
                        "jarred class files." ) );
                sb.append( describe( altJarLookNames[ i ], "uncommented jar manifest" ) );
                }
            for ( final String altJarName : altJarNames )
                {
                sb.append( describe( ( antJarWebDir + '/' + altJarName ).replace(
                        '/',
                        '\\' )
                        /* alt.jar */,
                        " jarred class files."
                ) );
                }
            sb.append( describe( ( projectLower + ".jnlp" ).replace( '/', '\\' ),
                    projectLower
                    + " jnlp Java Web Start launch"
            ) );
            return sb.toString();
            }
        else
            {
            return "";
            }
        }

    /**
     * prepare descriptions for java files
     *
     * @return description of .java files for DESCRIPT.ION file.
     */
    private String descJavas()
        {
        if ( compilerCat == JAVA )
            {  // other *.java and described manually.
            final FastCat sb = new FastCat( 10 + altSourceNames.length );
            sb.append( describe( "j1" + targetVersionString.charAt( 2 ) + ".txt",
                    "marker to indicate that Java compiler target version " + targetVersionString + " needed." ) );
            if ( hasMainProg )
                {
                sb.append( describe( mainClassName + ".java",
                        "main Java program source" ) );
                }
            for ( final String altSourceName : altSourceNames )
                {
                sb.append( describe( altSourceName
                        /* alt.java */,
                        "alt Java program source" ) );
                }
            if ( usesJni )
                {
                sb.append( describe( "cl32dll.bat", "compile/link 32-bit C/C++ DLL" ) );
                sb.append( describe( "cl64dll.bat", "compile/link 64-bit C/C++ DLL" ) );
                sb.append( describe( projectLower + ".c", "C source for JNI" ) );
                sb.append( describe( projectLower + ".cpp", "C++ source for JNI" ) );
                sb.append( describe( projectLower + ".h", "C include source for JNI" ) );
                sb.append( describe( projectLower + ".hpp", "C++ include source for JNI" ) );
                sb.append( describe( projectLower + ".32.dll", "JNI 32 bit DLL" ) );
                sb.append( describe( projectLower + ".64.dll", "JNI 64 bit DLL" ) );
                }
            return sb.toString();
            }
        else
            {
            return "";
            }
        }

    /**
     * prepare descriptions for Jet exe files
     *
     * @return description of jet *.exe files for DESCRIPT.ION file.
     */
    private String descJetExes()
        {
        if ( jetable )
            {
            final FastCat sb = new FastCat( 2 + altExeFilesUnqual.length * 2 );
            final FastCat sb2 = new FastCat( 2 );
            sb2.append( "JET executable " );
            sb2.append( description );
            sb.append( describe( mainExeFileUnqual, sb2.toString() ) );
            for ( final String altExeName1 : altExeFilesUnqual )
                {
                sb.append( describe( altExeName1, "JET executable" ) );
                }
            final FastCat sb4 = new FastCat( 2 );
            sb4.append( "JET executable " );
            sb4.append( description );
            sb.append( describe( ( "E:/sys/" + mainExeFileUnqual ).replace( '/', '\\' ), sb4.toString() ) );
            for ( String altExeName : altExeFilesUnqual )
                {
                sb.append( describe( ( "E:/sys/" + altExeName ).replace(
                        '/',
                        '\\' )
                        , "JET executable" ) );
                }
            return sb.toString();
            }
        else
            {
            return "";
            }
        }

    /**
     * prepare descriptions for jni extensions
     *
     * @return description of jni aux files for DESCRIPT.ION file
     */
    private String descJnis()
        {
        if ( usesJni )
            {
            final FastCat sb = new FastCat( 5 );
            sb.append( describe( projectLower + ".c",
                    " C code for native classes" ) );
            sb.append( describe( projectLower + ".cpp",
                    " C++ code for native classes" ) );
            sb.append( describe( projectLower + ".32.dll",
                    " 32-bit native classes in DLL, manually built." ) );
            sb.append( describe( projectLower + ".64.dll",
                    " 64-bit native classes in DLL, manually built" ) );
            sb.append( describe( projectLower + ".h",
                    " javah-generated headers for native classes" ) );
            return sb.toString();
            }
        else
            {
            return "";
            }
        }

    /**
     * prepare descriptions for misc extensions
     *
     * @return description of misc files for DESCRIPT.ION file.
     */
    private String descMiscs()
        {
        final FastCat sb = new FastCat( 13 );
        sb.append( describe( "mindprod.css",
                "cascading style sheet for general HTML" ) );
        sb.append( describe( "jdisplay.css",
                "cascading style sheet for displaying source code in HTML" ) );
        sb.append( describe( "package-info.java",
                "Dummy Java source with JavaDoc describing the entire package." ) );
        sb.append( describe( "untouch.digest",
                "generated: enables untouching (set date back) unchanged but redated files." ) );
        sb.append( describe( CODE_SIGNING_CERT + ".cer",
                "Public key for Mindprod code-signing certificate. Cannot be used to sign jars." ) );
        sb.append( describe( "DESCRIPT.ION", "TCC file descriptions" ) );
        sb.append( describe( "descript0.ion",
                "generated file of overriding descriptions to merge into DESCRIPT.ION" ) );
        sb.append( describe( "descript2.ion", "generated file default descriptions to merge into DESCRIPT.ION" ) );
        sb.append( describe( "MasterDistribution.site",
                "URL to find the master copy of the "
                + projectHumanName
                + " project files"
        ) );
        sb.append( describe( projectLower + ".use",
                "precis(summary) "
                + description
                + " Generated"
        ) );
        sb.append( describe( projectLower + ".vpj",
                "Slick Edit project ini file" ) );
        sb.append( describe( projectLower + ".vpw",
                "Slick Edit project ini file" ) );
        sb.append( describe( projectLower + ".vtg",
                "Slick Edit binary tag xref file" ) );
        return sb.toString();
        }

    /**
     * prepare descriptions for other png and gif files, in the icondir, not the project dir
     *
     * @return description of icon etc files for DESCRIPT.ION file..
     */
    private String descNonProjectFiles()
        {
        final FastCat sb = new FastCat( 18 + altExeFilesUnqual.length );
        sb.append( describeOther( ( antIcon16Dir + '/' + projectLower + ".png" ).
                        replace( '/', '\\' ),
                "16x16 icon for the "
                + projectHumanName
                + " project"
        ) );
        sb.append( describeOther( ( antIcon32Dir + '/' + projectLower + ".png" ).
                        replace( '/', '\\' ),
                "32x32 icon for the "
                + projectHumanName
                + " project"
        ) );
        sb.append( describeOther( ( antIcon32Dir
                                    + '/'
                                    + projectLower
                                    + ".gif" ).replace( '/', '\\' ),
                "32x32 gif icon for the "
                + projectHumanName
                + " project"
        ) );
        sb.append( describeOther( ( antIcon48Dir + '/' + projectLower + ".icon48.png" ).
                        replace( '/', '\\' ),
                "roughly 48x48 icon for the "
                + projectHumanName
                + " project"
        ) );
        sb.append( describeOther( ( antIcon64Dir + '/' + projectLower + ".png" ).
                        replace( '/', '\\' ),
                "roughly 64x64 icon for the "
                + projectHumanName
                + " project"
        ) );
        sb.append( describeOther( ( antIcon64Dir
                                    + '/'
                                    + projectLower
                                    + ".gif" ).replace( '/', '\\' ),
                "64x64 gif icon for the "
                + projectHumanName
                + " project"
        ) );
        sb.append( describeOther( ( antIcon128Dir + '/' + projectLower + ".png" ).
                        replace( '/', '\\' ),
                "roughly 128x128 icon for the "
                + projectHumanName
                + " project"
        ) );
        sb.append( describeOther( ( screenshotDir + '/' + projectLower + ".png" ).
                        replace( '/', '\\' ),
                "screenshot for the "
                + projectHumanName
                + " project"
        ) );
        sb.append( describeOther( ( splashDir + '/' + projectLower + ".gif" ).
                        replace( '/', '\\' ),
                "splash for the "
                + projectHumanName
                + " project"
        ) );
        sb.append( describeOther( ( antJarWebDir
                                    + '/'
                                    + projectLower
                                    + "icon32.gif" ).replace( '/', '\\' ),
                projectLower + " 32x32 icon gif"
        ) );
        sb.append( describeOther( ( antJarWebDir
                                    + '/'
                                    + projectLower
                                    + "icon64.gif" ).replace( '/', '\\' ),
                projectLower + " 64x64 icon gif"
        ) );
        sb.append( describeOther( ( antJarWebDir
                                    + '/'
                                    + projectLower
                                    + "splash.gif" ).replace( '/', '\\' ),
                projectLower + " splash gif"
        ) );
        sb.append( describeOther( ( antJarWebDir
                                    + '/'
                                    + projectLower
                                    + ".jnlp" ).replace( '/', '\\' ),
                projectLower
                + " jnlp Java Web Start launch"
        ) );
        switch ( compilerCat )
            {
            default:
                break;
            case ASM:
            case C:
            case CPP:
                final FastCat sb2 = new FastCat( 4 );
                sb2.append( "Windows executable to run the " );
                sb2.append( mainClassName );
                sb2.append( " program: " );
                sb2.append( description );
                sb.append( describeOther( ( "E:/sys/" + mainExeFileUnqual ).replace( '/', '\\' )
                        , sb2.toString() ) );
                for ( int i = 0; i < altExeFilesUnqual.length; i++ )
                    {
                    final FastCat sb3 = new FastCat( 3 );
                    sb3.append( "Windows executable to run the " );
                    sb3.append( altAppNames[ i ] );
                    sb3.append( " program" );
                    sb.append( describeOther( ( "E:/sys/" + altExeFilesUnqual[ i ] ).replace(
                            '/',
                            '\\' ), sb3.toString() ) );
                    }
            } // end switch
        sb.append( describeOther( ( antPrecisDir + '/' + projectLower + ".txt" )
                        .replace( '/', '\\' ),
                "precis of the "
                + projectHumanName
                + " project: "
                + description
        ) );
        sb.append( describeOther( ( antPadDir
                                    + '/'
                                    + projectLower
                                    + ".xml" ).replace( '/', '\\' ),
                "ASP PAD desc of the "
                + projectHumanName
                + " project: "
                + description
        ) );
        if ( hasDistributedZip )
            {
            sb.append( describeOther( ( antZipWebDir + '/' + zipFileUnqual ).replace( '/', '\\' )
                    /* *.zip */,
                    projectHumanName
                    + " "
                    + versionString
                    + " distribute zip archive: "
                    + description
            ) );
            }
        return sb.toString();
        }

    /**
     * prepare descriptions for png and gif files
     *
     * @return description of distributed *.png and *gif  files for DESCRIPT.ION file.
     */
    private String descPngs()
        {
        // see also descJars to describe images in the jar directory
        final FastCat sb = new FastCat( 9 );
        sb.append( describe( projectLower + ".icon16.png",
                "16x16 icon for the "
                + projectHumanName
                + " project"
        ) );
        sb.append( describe( projectLower + ".icon32.png",
                "32x32 icon for the "
                + projectHumanName
                + " project"
        ) );
        sb.append( describe( projectLower + ".icon48.png",
                "roughly 48x48 icon for the "
                + projectHumanName
                + " project"
        ) );
        sb.append( describe( projectLower + ".icon64.png",
                "roughly 64x64 icon for the "
                + projectHumanName
                + " project"
        ) );
        sb.append( describe( projectLower + ".icon128.png",
                "roughly 128x128 icon for the "
                + projectHumanName
                + " project"
        ) );
        sb.append( describe( projectLower + ".screenshot.png",
                "screenshot for the "
                + projectHumanName
                + " project"
        ) );
        sb.append( describe( projectLower + ".splash.gif",
                "splash gif for the "
                + projectHumanName
                + " project"
        ) );
        sb.append( describe( projectLower + ".icon32.gif",
                "32x32 gif icon for the "
                + projectHumanName
                + " project"
        ) );
        sb.append( describe( projectLower + ".icon64.gif",
                "64x64 gif icon for the "
                + projectHumanName
                + " project"
        ) );
        return sb.toString();
        }

    /**
     * prepare descriptions for txt files
     *
     * @return description of distributed *.txt  files for DESCRIPT.ION file..
     */
    private String descTxts()
        {
        final FastCat sb = new FastCat( 5 );
        sb.append( describe( OVERVIEW_FILE,
                "Commented List of all files for "
                + projectHumanName
                + ", with one line descriptions."
        ) );
        sb.append( describe( "use.txt",
                "key facts about the "
                + projectHumanName
                + " project. Generates "
                + projectLower
                + ".use"
        ) );
        // *.use handled in descMiscs
        sb.append( describe( "version.txt",
                "key current version info about the "
                + projectHumanName
                + " project. Generates "
                + projectLower
                + ".use"
        ) );
        sb.append( describe( "versionhistory.txt",
                "complete version history of the "
                + projectHumanName
                + " project. Generates "
                + projectLower
                + ".use"
        ) );
        sb.append( describe( projectLower + ".txt",
                "ASCII text manual for the "
                + projectHumanName
                + " project."
        ) );
        return sb.toString();
        }

    /**
     * prepare descriptions for xml files
     *
     * @return description of  *.xml  files for DESCRIPT.ION file.
     */
    private String descXmls()
        {
        final FastCat sb = new FastCat( 3
                                        + ( hasJar ? altProgsCount * 2 + 3 : 0 )
                                        + ( hasZip ? 1 : 0 )
                                        + ( hasDistributedZip ? 1 : 0 ) );
        sb.append( describe( "build.xml",
                "Complex ANT build script for "
                + projectHumanName
        ) );
        sb.append( describe( "rebuild.xml",
                "Simplified ANT build script for "
                + projectHumanName
        ) );
        sb.append( describe( "forgather.xml",
                "list of extra gather steps for ANT." ) );
        if ( hasJar )
            {
            sb.append( describe( "forjar.xml",
                    "genjar list of extra files to include in "
                    + mainJarName ) );
            sb.append( describe( "forjarexe.xml",
                    "jar.exe list of extra files to include in "
                    + mainJarName
            ) );
            for ( int i = 0; i < altProgsCount; i++ )
                {
                sb.append( describe( altForJarNames[ i ]
                        /* forxxxjar.xml */,
                        "genjar list of extra files to include in "
                        + altJarNames[ i ]
                ) );
                /* forxxxjarexe.xml */
                final String altForJarExeName = ST.chopTrailingString( altForJarNames[ i ],
                        ".xml" ) + "exe.xml";
                sb.append( describe( altForJarExeName,
                        "jar.exe list of extra files to include in "
                        + altJarNames[ i ]
                ) );
                }
            sb.append( describe( "forpost.xml",
                    "list of extra posting steps for ANT." ) );
            }
        if ( hasZip )
            {
            sb.append( describe( "forzip.xml",
                    "list of extra files for ANT include in "
                    + zipFileUnqual
            ) );
            }
        if ( hasDistributedZip )
            {
            sb.append( describe( projectLower + ".xml",
                    "ASP PAD desc of the "
                    + projectHumanName
                    + " project: "
                    + description
            ) );
            }
        return sb.toString();
        }

    /**
     * prepare descriptions for *.zips
     *
     * @return description of  *.sip  files for DESCRIPT.ION file..
     */
    private String descZips()
        {
        if ( hasZip )
            {
            final FastCat sb = new FastCat( 2 );
            sb.append( describe( zipFileUnqual
                    /* *.zip */,
                    projectHumanName
                    + " "
                    + versionString
                    + " distribute zip: "
                    + description
            ) );
            sb.append( describe( zipLookName, "uncommented zip manifest for " + zipFileUnqual ) );
            return sb.toString();
            }
        else
            {
            return "";
            }
        }

    /**
     * make bat file to describe files and tidy description file
     */
    private void mkDescBtm()
        {
        final FastCat sb = new FastCat( 30 );
        sb.append( "@echo off\n" );
        sb.append( echoFlash(
                "desc.btm: add TCC descriptions to all "
                + projectLower
                + " files"
        ) );
        sb.append( "rem Update the TCC file descriptions in DESCRIPT.ION and ", OVERVIEW_FILE, "\n" );
        sb.append( "rem This script was generated by com.mindprod.zzz.MkDesc.  D o   N o t   E d i t .\n" );
        sb.append( cdToWinProjectDir );
        sb.append( "attrib -h DESCRIPT.ION > nul:\n" );
        sb.append( "rem Provide generic descriptions for *.class files still without specific descriptions.\n" );
        sb.append( "for %i in (*.class ) do describe %i /D\"compiled Java byte code\"\n" );
        sb.append( "rem Merge generated descript0.ion and descript2.ion to fill in missing descriptions.\n" );
        sb.append( "rem descript0.ion takes precedence over DESCRIPT.ION which takes precedence over descript2.ion" +
                   ".\n" );
        sb.append( "if exist DESCRIPT.ION goto patch\n" );
        sb.append( "copy /Q /B descript0.ion +  descript2.ion DESCRIPT.ION\n" );
        sb.append( "goto patched\n" );
        sb.append( ":patch\n" );
        sb.append( "copy /Q /B descript0.ion + DESCRIPT.ION + descript2.ion temp.ion\n" );
        sb.append( "del /Q DESCRIPT.ION\n" );
        sb.append( "rename /Q temp.ion DESCRIPT.ION\n" );
        sb.append( ":patched\n" );
        sb.append( "rem Build " );
        sb.append( OVERVIEW_FILE );
        sb.append( " from TakeCommand/TCC DESCRIPT.ION file descriptions.\n" );
        sb.append( "rem Tidy, sort and dedup descriptions keeping most detailed description.\n" );
        sb.append( "fourtidy.exe -f\n" );  // -d keep longest existing, -f keep first
        sb.append( "echo done\n" );
        sb.append( "rem -30-\n" );
        // save inserting \r
        save( winAbsoluteProjectDir + "\\" + "desc.btm", sb.toString(), EIO.WINDOWS1252, true );
        }

    /**
     * make bat file to describe non project files
     */
    private void mkDescOtherBtm()
        {
        final FastCat sb = new FastCat( 6 );
        sb.append( "@echo off\n" );
        sb.append( echoFlash( "descother.btm: add TCC descriptions to all " + projectLower + " non-project files" ) );
        sb.append( "rem This script was generated by com.mindprod.zzz.MkDesc.  D o   N o t   E d i t .\n" );
        sb.append( descNonProjectFiles() );
        sb.append( "echo done\n" );
        sb.append( "rem -30-\n" );
        // save inserting \r
        save( winAbsoluteProjectDir + "\\" + "descother.btm", sb.toString(), BAT_ENCODING, true );
        }

    /**
     * make list of file descriptions to override existing descriptions
     */
    private void mkDescript0Ion()
        {
        final FastCat sb = new FastCat( 13 );
        sb.append( descBats() );
        sb.append( descClasses() );
        sb.append( descExes() );
        sb.append( descHtmls() );
        sb.append( descJars() );
        sb.append( descJETCompileJetsom() );
        sb.append( descJETDistributeJetsom() );
        sb.append( descJnis() );
        sb.append( descMiscs() );
        sb.append( descPngs() );
        sb.append( descTxts() );
        sb.append( descXmls() );
        sb.append( descZips() );
        save( winAbsoluteProjectDir + "\\" + "descript0.ion", sb.toString(), BAT_ENCODING, true );
        }

    /**
     * make list of file descriptions to use if there is not already another description.
     */
    private void mkDescript2Ion()
        {
        final FastCat sb = new FastCat( 4 );
        sb.append( descAsms() );
        sb.append( descCPPs() );
        sb.append( descCs() );
        sb.append( descJavas() );
        save( winAbsoluteProjectDir + "\\" + "descript2.ion", sb.toString(), BAT_ENCODING, true );
        }

    /**
     * generate TCC descriptions of ALL files. Master method.
     */
    void mkDescsBtm()
        {
        mkDescBtm();
        mkDescript0Ion();
        mkDescript2Ion();
        mkDescOtherBtm();
        }
    }