How to Add New Forms:

There are five (5) or six (6) steps to adding a new form to OTS.

The following steps assume that you have downloaded the latest working package of OTS. Navigate into/under the top directory, and make the following modifications to the existing files:

1. Create the blank-template file for your new form. -
   1. Make a new directory, under the tax_form_files directory, with name of your new form.
      For example: tax_form_files/Form_xxxx
      Create the following two files inside your new directory.
   2. Create a blank template text-file in your new directory.
      For example: tax_form_files/Form_xxxx/Form_xxxx_template.txt
      Then create the following contents within that text file.
      The first line must begin: Title: ....
      Where the ... can describe the form-name and year. See the other directories for examples.
      The the rest of the lines will contain comments in squiggly brackets {}, and line labels that correspond to the new form you are doing. Again, see the examples in other directories for examples. Lines that can accept multiple values to be summed, should end with a semi-colon (;).
      For example:

      Title: Form XXXX for tax-year 2032

      L1               ; { Wages. }
      L2               ; { Interest. }

   3. After you create the blank template file, create a copy in the same directory, but named Form_xxxx_example.txt, and place some numerical values on the lines. You will use this example file for testing, as well as showing how to use the form.
      For example:

      Title: Form XXXX for tax-year 2032 - EXAMPLE

      L1         2389.67       ; { Wages. }
      L2           80.21    ; { Interest. }

2. Create the form-program to process your new form. - Navigate up and over to the src directory. Create your program source-code for processing your form in the src directory. You can start with this generic program shell. Of course you must rename it to taxsolve_xxxx.c, where xxxx is your chosen form-name. Then open it with a text-editor, navigate down inside the main(...) routine, and add the lines for accepting and processing your form data. You can look at the other programs in the src for examples of how it is done. Of course replace the xxxx with your form's name. And fill-in the section under the comment: /* ----- Place all your form-specific code below here ... ---- */

   How to write and debug code is generally beyond the scope of this tutorial. But you may be able to pick up some of the ideas from the neighboring ".c" files. For convenience, this link provides a Summary of OTS Functions that are used most often, along with a brief summary of what each one does. And as time goes by, we may be able to add more coding guidelines about the base functions. In the meantime, we may be able to answer some quick questions occasionally.

3. Add your form-program name to the src/Makefile and compile it. - Edit the Makefile to add the corresponding references to your new program file, just like the references for all the other programs. This means adding three lines.
   1. In the "all:" section near the top, maybe just above the "../Run_taxsolve_GUI" line, add a line like:
            ../bin/taxsolve_Form_xxxx \
      Where ...Form_xxxx will be your form-name of course.
   2. Somewhere below amongst the other similar statements, add two lines like:
            ../bin/taxsolve_Form_xxxx: taxsolve_Form_xxxx.c taxsolve_routines.c
                  $(CC) $(CFLAGS) $(COPTIM) -o ../bin/taxsolve_Form_xxxx taxsolve_Form_xxxx.c $(SRCS) $(LIBS)

      Note that the second line MUST start with a <tab> character. before the $(CC) ...

   Now you can try compiling your program. Of course you will need a working compiler and developer libraries.

   • On Linux, if not already installed, this is easily set up. For example:
           appget gcc
           appget gtk2-devel
     Or in non-appget distros, use yum install or dnf install.

   • If you are on a Mac, you can install Xcode from the Apple's App Store.

   • On MS-Windows, install Minimum GNU for Windows MinGW, to provide the C-compiler and all development libraries. Then install MSYS to provide the Make utility and the command-line environment for compiling with the same POSIX commands and scripts as on the other platforms. Then do the compile from your MSYS window.

   Compile the Programs:

   In whichever platform you use, once you have the compiler environment established as above:
   1. Navigate to OTS's top directory,
   2. Run the build-script:
           src/Build_taxsolve_packages.sh
      It will run the Makefile(s) and compile the programs you edited.
      Watch for any error messages, and if any, then fix them and re-compile until successful.

But many people prefer using the Graphical-User-Interface (GUI) and using the PDF Auto-Fill-out program to automatically produce your filled-out forms ready to mail. So you are half-way there. Just follow the remaining steps to graphically enable your new form program.

4. Register your new form in the OTS GUI. - The simplest way to add new forms is under the Other category of the GUI. Do this by editing the src/Gui_gtk/ots_gui2.c file. There are three places within this file where you will add changes. The easiest way to find them is by searching for "f8889", since you will be making similar entries as were done for the "f8889" form
   1. Add the reference to your "instructions" file in the read_instructions() routine.
      Change:

      
          default:
              if (strstr( taxsolvestrng, "taxsolve_HSA_f8889" ) != 0)
               instructions_filename = strdup( "f8889_instructions.dat" );
              else
               return;
      		

      To:

      
          default:
              if (strstr( taxsolvestrng, "taxsolve_HSA_f8889" ) != 0)
               instructions_filename = strdup( "f8889_instructions.dat" );
              else
              if (strstr( taxsolvestrng, "taxsolve_Form_xxxx" ) != 0)
               instructions_filename = strdup( "Form_xxx_instructions.dat" );
              else
               return;
      		

      Of course replace "Form_xxxx" with the name of your form.

   2. Set the PDF-supported flag for your form in the set_tax_solver() routine, by adding at the bottom:

      
      	if (strstr( taxsolvestrng, "taxsolve_Form_xxxx" ) != 0)
      	  supported_pdf_form = 1;
      		

      Again of course replace "Form_xxxx" with the name of your form.

   3. Set the PDF conversion commands by adding, at the bottom of the do_pdf_conversion() routine, in the default: case-block just before the final else, the following code:

      
              else
              if (strstr( taxsolvestrng, "taxsolve_Form_xxxx" ) != 0)
               {
                statusw.nfiles = 0;
                setpdfoutputname( wrkingfname, ".pdf", outputname );
                prepare_universal_pdf_cmd( "", "Form_xxxx_meta.dat", wrkingfname, 
      					 "Form_xxxx_pdf.dat", outputname );
                printf("Issuing: %s\n", fillout_pdf_command );
                add_status_line( outputname );
                execute_cmd( fillout_pdf_command );
                update_status_label( "Completed Filling-out PDF Form:" );
                statusw.fnames[ statusw.nfiles ] = strdup( outputname );
      	  statusw.nfiles = statusw.nfiles + 1;
                add_view_pdf_button();
               }
      		

      Again of course replacing the "Form_xxxx" strings with the name of your form.

5. Add your form's PDF files. - For each form, you need two files to make the PDF Auto-fillout work. These files must be placed in the src/formdata directory:
   1. Form_xxxx_pdf.dat - This is the binary PDF-data file that carries the form backgrounds for all your form's pages. It is made automatically from the government forms, which you need to download and have ready for this step. (You cannot open the resulting binary file for viewing.) This file is automatically made by the Extract_pdf_file_to_Universal_pdf_objs utility available inexpensively from the Behemoth Software Company.
      Assuming the original government-provided PDF form file is called: fxxxx.pdf
      Run the conversion program as:

      
      	Extract_pdf_file_to_Universal_pdf_objs   fxxxx.pdf
      		

      It will produce a file called:   universal_pdf_obj.data     ... which you should rename to:   fxxxx_pdf.dat
      And then move that file into your src/formdata directory. Name it so that it corresponds with your form's naming scheme.

      For convenience, the Extractor tool also writes out a blank metadata file, called blank_meta.txt, which can be used to start your metadata file (for step-ii, next), because it has the correct number of page boundary keywords in it, but nothing else.

   2. Form_xxxx_meta.dat - This is a regular text-file that you populate with your text-editor. Start it by editing the blank_meta.txt created by the Extractor tool above. Re-name it into the src/formdata directory, placing it next to your fxxxx_pdf.dat file, as above (from step-i). Make your metadata file have the same name as your corresponding _pdf.dat file, but with _meta.dat instead.

      The metadata file sets the position of each tax-line answer on each PDF page. It lists the page coordinates of each line-label, as well as some other formatting information, such as the justification, color, and number of numerical spaces to use. You can look at the neighboring ..._meta.dat files to see what it must contain. Hint: The easiest way to determine the coordinates is by opening an image-editor, such as GIMP or Photoshop on the government PDF file at a resolution of 110-points/inch, move your cursor to each line position, and read off the pixel coordinates, and paste or type them into your Form_xxxx_meta.dat file. See the documentation on the uPDF-Modifier site for help about the syntax of the available formating commands.

6. Optionally - Add your form's Instructions file. - Create the text file Form_xxxx_instructions.dat under the src/formdata directory - This is the optional text-file containing additional instructions for tax-lines, which can be accessed by clicking any populated line in the GUI. You can create this file by simply Copy&Pasting from the instruction booklet for your form. You can see how it works by looking at the neighboring example files. You would create a corresponding file for your form. Very straight-forward.

Usage:

From this point, the run-time operation is the same as any of the other first-tier forms in OTS. You can now Save-As, Compute, and Print your form(s) by clicking the appropriate buttons as normal.

Example:

• Look under the tax_form_files directory for the HSA_Form_8889 directory. You will see the template and example text files for that HSA 8889 Form. Look inside those two files to see what they contain. You will see that you can easily create a similar directory under tax_form_files named after whatever new form you want to add. And then you can replicate the template and example text files corresponding to the fields in your new form.
• Next look under the src directory at the taxsolve_HSA_f8889.c program. You will see the outer shell that is similar for all OTS form programs, consisting of the #include files, and the main(...) routine. Inside the main(...) routine you will see the GetLine... and showline() statements with some calculations in between. You will replicate the program within the src directory, but naming it after your new form, and just replacing the line statements and calculations with the corresponding ones for your new form.
• Finally, look inside the src/Makefile for references to the taxsolve_HSA_f8889 program. You would add corresponding entries for your new program, so that it will get compiled and the executable will be placed correctly into the bin directory.

• Look into the src/Gui_gtk/ots_gui2.c file. Search for f8889 to where entries were made to support that form. For each of them, you would make corresponding entrees with your new form name. Realize of course that you will need to be consistent with your naming scheme.
• Finally, look into the src/formdata directory for the three f8889_xxx.dat files:
  • f8889_meta.dat - This is a text-file that you can open and look at. You would produce a corresponding file for your new form. It sets the position of each tax-line answer on each PDF page. It lists the page coordinates of each line-label, as well as some other formatting information, such as the justification, color, and number of numerical spaces to use.
  • f8889_pdf.dat - This is the binary PDF-data file that carries the form backgrounds for each page. It is made automatically from the government forms. (You cannot open these binary files for viewing.)
  • f8889_instructions.dat - This is the optional text-file containing additional instructions for tax-lines, which can be accessed by clicking in the GUI. You can create this file by simply Copy&Pasting from the instruction booklet for your form. You can see how it works by looking at this example file. You would create a corresponding file for your form. Fairly straight-forward.

1. All the files you need to author are Plain Text Files (except for the src/formdata/xxxx_pdf.dat file). Most anyone working on Linux or Mac OS should not have any problem creating real text-files, by using popular text-editors like emacs, vim, gedit, edt, pico, etc.. However, anyone using Microsoft Windows must know to use a text editor, such as those, or WordPad. Be careful not to save the files in a word-processor format, such as DocX, RTF, etc.. That will NOT work. (If you do use MS-Word or any word-processor app, be sure to Save-As TXT.)