Installation:

    Install: make install

    Important: Whenever you install a system update that affects PostgreSQL or

        any of its dependencies, such as libc, you should restart the PostgreSQL

        server. Otherwise, you may get strange errors like "the database system

        is in recovery mode" which go away upon reimport.

        make test by_col=1

    For each newly-uploaded datasource: make inputs/<datasrc>/reinstall

        WARNING: This will delete the current public schema of your VegBIEN DB!

        To save it: make schemas/rotate

        To use row-based import: . bin/import_all

            won't be owned by your shell.

            TNRS names before returning control to the shell.

    Check that every input's log ends in "Encountered 0 error(s)"

    If many do not, fix the bug and discard the current (partial) import:

        make schemas/public/reinstall

    Otherwise, continue

        bin/import_name inputs/{.,}*/*/logs/*.r<revision>[.-]*log.sql

    Archive the last import: make schemas/rename/public.<import_name>

        /home/bien/svn/backups/analytical_aggregate.public.<version>.csv

    On nimoy:

        cd /home/bien/svn/

        svn up

        In the bien_web DB:

            Rename any existing analytical_aggregate table

            Create the analytical_aggregate table using its schema in

                schemas/vegbien.my.sql

        bin/publish_analytical_db backups/analytical_aggregate.public.<version>.csv

        Open inputs/import.stats.xls

        Insert a copy of the leftmost Column-based column group before it

        Update the import date in the upper-right corner

            row counts match up with the previous import's row counts

        If the row counts do not match up, insert or reorder rows as needed

            until they do

        public should be set to the current import's schema name

            tail -f inputs/analytical_db/logs/make_analytical_db.log.sql

        Back up: make backups/public.<date>.backup &

                make schemas/rotate

        Remove: make backups/public.<date>.backup/remove

        Back up: make backups/TNRS.backup-remake &

        Restore:

            yes|make inputs/.TNRS/uninstall

            make backups/TNRS.backup/restore &

            yes|make schemas/public/reinstall

                Must come after TNRS restore to recreate tnrs_input_name view

        Restore: make backups/vegbien.<date>.backup/restore &

        Download: make inputs/download-logs

        <datasrc> may not contain spaces, and should be abbreviated.

        If the datasource is a herbarium, <datasrc> should be the herbarium code

            as defined by the Index Herbariorum <http://sweetgum.nybg.org/ih/>

        For .sql exports:

            Place the original .sql file in _src/ (*not* in _MySQL/)

            Create a database for the MySQL export in phpMyAdmin

            mysql -p database <inputs/<datasrc>/_src/export.sql

        mkdir inputs/<datasrc>/_MySQL/

        cp -p lib/MySQL.{data,schema}.sql.make inputs/<datasrc>/_MySQL/

        Edit _MySQL/*.make for the DB connection

            For a .sql export, use your local MySQL DB

        For CSV files, you can use any name. It's recommended to use a table

            name from <https://projects.nceas.ucsb.edu/nceas/projects/bien/wiki/VegCSV#Suggested-table-names>

            name must end in ".src"

                This command also creates necessary subdirs, such as logs/.

            Otherwise, place the CSV(s) for the table in

            together in inputs/<datasrc>/<table>/create.sql

            that embedded quotes are escaped by doubling them, *not* by

            preceding them with a "\" as is the default in phpMyAdmin

            in each part, make sure each header is EXACTLY the same.

             (If the headers are not the same, the CSV concatenation script

             assumes the part files don't have individual headers and treats the

             subsequent headers as data rows.)

        To view progress: tail -f inputs/<datasrc>/<table>/logs/install.log.sql

        View the logs: tail -n +1 inputs/<datasrc>/*/logs/install.log.sql

            +1 starts at the first line, to show the whole file

        For every file with an error 'column "..." specified more than once':

                    "_" unfortunately sorts *after* capital letters in ASCII.

                Create a text file containing the header line of the flat files

                Add an ! at the beginning of the line

                    This signals cat_csv that this is a header override.

                For empty names, use their 0-based column # (by convention)

                For duplicate names, add a distinguishing suffix

                For long names that collided, rename them to <= 63 chars long

                Do NOT make readability changes in this step; that is what the

                    map spreadsheets (below) are for.

                Save

        If you made any changes, re-run the install command above

                left column of the core map

            Save

            -   If the error was due to a bug, fix it

            -   Add a SQL function that filters or transforms the invalid data

            -   Make an empty mapping for the columns that produced the error.

                Put something in the Comments column of the map spreadsheet to

                prevent the automatic mapper from auto-removing the mapping.

                (see WinMerge setup below for configuration)

            If you get errors this time, this always indicates a bug, usually in

        On vegbiendev: svn up

        On local machine: make inputs/upload

            Follow the steps under Install the staging tables above

            make inputs/<datasrc>/test

    VegBank:

        make inputs/VegBank/vegbank.sql-remake

        make inputs/VegBank/reinstall quiet=1 &

        schemas/filter_ERD.csv

        mappings/VegCore-VegBIEN.csv

        Run make schemas/vegbien.my.sql

        Open schemas/vegbien.ERD.mwb in MySQLWorkbench

        Go to File > Export > Synchronize With SQL CREATE Script...

        For Input File, select schemas/vegbien.my.sql

        Click Continue

        Click Continue

        Note: The generated SQL script will be empty because we are syncing in

            the opposite direction

        Click Execute

        Reposition any lines that have been reset

        Add any new tables by dragging them from the Catalog in the left sidebar

            to the diagram

        Remove any deleted tables by right-clicking the table's diagram element,

            selecting Delete '<table name>', and clicking Delete

        Save

    Update graphical ERD exports:

        In the lower left corner, click PDF > Save as PDF...

        Set the Title and Author to ""

        To rename a table:

            In vegbien.sql, do the following:

                Replace regexp (?<=_|\b)<old>(?=_|\b) with <new>

                    This is necessary because the table name is *everywhere*

                Search for <new>

                Manually change back any replacements inside comments

        To rename a column:

            Rename the column: ALTER TABLE <table> RENAME <old> TO <new>;

            Recreate any foreign key for the column, removing CONSTRAINT <name>

                This resets the foreign key name using the new column name

                of another): 16.3cm/24 lines = 0.679cm

            Measure the height of the ERD: 35.4cm*2 = 70.8cm

            Zoom in as far as possible

            Measure the height of a capital letter: 3.5mm

            Measure the line height: 8.5mm

            Calculate the text's fraction of the line height: 3.5mm/8.5mm = 0.41

            Calculate the text height: 0.679cm*0.41 = 0.28cm

            Calculate the text height's fraction of the ERD height:

                0.28cm/70.8cm = 0.0040

            Measure the text height on the *VegBank* ERD poster: 5.5mm = 0.55cm

            Calculate the VegBIEN poster height to make the text the same size:

                0.55cm/0.0040 = 137.5cm H; *1in/2.54cm = 54.1in H

            The ERD aspect ratio is 11 in W x (2*8.5in H) = 11x17 portrait

            Calculate the VegBIEN poster width: 54.1in H*11W/17H = 35.0in W

            The minimum VegBIEN poster size is 35x54in portrait

            The FedEx Kinkos near NCEAS (1030 State St, Santa Barbara, CA 93101)

                charges the following for posters:

                base: $7.25/sq ft

                lamination: $3/sq ft

                mounting on a board: $8/sq ft

    Mapping process: make test

            row counts, this usually means that a table is underconstrained

            (the unique indexes don't cover all possible rows).

            This can occur if you didn't use COALESCE(field, null_value) around

            a nullable field in a unique index. See sql_gen.null_sentinels for

            the appropriate null value to use.

    Install WinMerge from <http://winmerge.org/>

    Go to Edit > Options and click Compare in the left sidebar

        <http://manual.winmerge.org/Configuration.html#d0e5892>.

        <http://manual.winmerge.org/Configuration.html#d0e5758>.

    To generate a Redmine-formatted list of steps for column-based import:

    To see a program's description, read its top-of-file comment

    To see a program's usage, run it without arguments

    To remake a file: make <file>-remake