Generates web pages from spreadsheet generated .csv files. The pages are designed to
support hyperlinks to books.

The source code for mkPage.awk is here.

SYNOPSIS

mkpage.awk [-FSEP] [-v site=URL] [-v name=topic] [comment.txt] file1.csv …

DESCRIPTION

     -f    gawk script to be executed
     -FSEP Separation character used in csv file - default = ','
           Must be a single character, can not be a 
           double quote (")
     .csv  field separated file
           title SEP author SEP target SEP URL
           title    book title or table topic
           author   book author or null
           target   null or any character. Generates 'target="_blank"'
           URL      hyperlink to downloadable address of book or null
     -v site=URL
           URL where the fileS ARE located. For example,
              -v site=https://slipbits.com
           The generated base file will contain references to the 
           file_TABLES file as in ">a href="URL/file_TABLES<".
     -v name=topic
           Prefix of the output file names (topic & topic_TABLES)
           If name is not given, then the output file name prefix is
           the file name without the '.csv' suffix.

INPUT FILE FORMAT

    Comment file: If a comment file is provided then it should be 
                  an HTML formatted file. 
                  
                  Leading and trailing double quotes (") are removed.
                  
                   <p>Open line</p> => <p>Open line</p>
                  "<p>Open Line</p> => <p>Open line</p>
                  
    Comma Separated Text File (csv)
        caption,,,
        title,[suthor],[char],URL
        
        where 
            caption is the table name
            title   is the 'book' title
            author  is the 'book' author
            char    is a single character
            URL     internet address
            
        If any of the items have an embedded separator 
        character or double quote then the field must 
        be sorrounded with double quotes.
        
        Each embedded double quote must be doubled.
        
        For example: SEP = ','
            table name,,,
            last name,     first, x, https://slipbits.com
            "last, name", "first",,  https://slipbits.com
            "last""name",  first, ,  https://slipbits.com
        

OUTPUT FILES

• file1.htnl   Contains references to tables in file1_TABLES
• file1_TABLES Contains a table of contents and tables for each topic

The Problem

It is burdensome to maintain a table with many entries. Sorting of entries must be done by ‘hand’, deleting or adding an entry is burdensome, and moving an entry from one webpage to another is a chore.

The Solution

All these issues are easier in a spreadsheet. Sorting entries is done by the underlying spreadsheet software on command of a user, adding and deleting a row is simple, and exhanging data between two spreadsheets becomes a copy and paste operation of a row between two (or more) spreadsheets.

In this case, the tables have a title, headers for two columns, and two columns. Generating a webpage is based on a simple template and the output is one-to-one and onto with the information in the spreadsheet.

After processing we are left with two files. One containing tables, the ref file, and one containing references to those tables, the base file. But something is left out. We would like to insert text into the base file describing what the tables are, and we would like to have not only a reference to the tables, but a one-line description of what is being referenced. In the ref file it would be nice to include a description before each table providing detail as to what the table is. The program accomodates this.

There is one more little nugget that would be nice to have. In some cases a topic area has minor topics contained within it. In this case it would be nice if the base file contains a list of major topics and an indented list of minor topics. Somthing like this:

• Major Topic
• minor topic₁
• minor topic₂
• o o o
• minor topic_n

This option is available. Inputting a command line option specifying the overall category, each input file is divided into two parts. One part is the Major Topic. This is considered to be the .csv file name. The other part are the subordinated tables. If there are more than one table definition in the .csv file, then the base file reference is constructed as above. If there is only one table, then the Major Topic is hyperlinked to this table, and a subordinated list is not created.

Use of this option generates two files, the base file and the ref file. The base file is as described, the ref file concatenates all input table definitions into a single file. Sort of a “for the many, one” approach.

All other options remain avalable. The user can provide text for the base file, annotate each table, and provide for includsion of a one-line annotation to the hyperlinked reference in the base file.

How this all works

There are two cases; (1) A non-subordinated single file input, (2) A subordinated multiple file input. Lest look at the user requiresments.

1. Non-subordinated single file.

> mkpage.awk [-FSEP] [-v site=URL] file₁.csv …

For each .csv file, two files are created. The base file, named file₁ references all tables in its companion file, file₁_TABLE. The base file references are all at the same level, and each reference points to a single table.

If the input file.csv has two tables (table₁, table₂), then the basefile reference looks like:

• table₁
• table₂

and the ref file, file_TABLE, has both table₁ and table₂ in it.

2. Subordinated multiple files:

> mkpage.awk [-FSEP] [-v site=URL] -v name=topic₁.csv …

All the .csv defined tables are combined into a single file named topic_TABLE. The base file contains hyperlinks to each table in topc_TABLE. The base organization is that where a .csv file has more than one table, the base file uses the .csv flie name as a list element in the outermost list, and has hyperlinks to each table in the .csv file at a subordinate level. If there is only one table inthe .csv file, then the .csv file name is created at the outermost list level and hyperlinked to the table.

Let’s use the following as an example:

1. Topic₁.csv has a single table, table₁.
2. Topic₂.csv has two tables, table₂ and table₃.

Then:

> mkpage.awk [-FSEP] [-v site=URL] -v name=Math Topic₂.csv

Produces the following in the base file, Math, containing:

1. Topic₁
2. Topic₂
1. table₂
2. table₃

With Topic₁ having a hyperlink to table₁, Topic₂ having no linkage, and table₂ and table₃ hyperlinked to their respective tables.

The ref file is named Math_TABLE and contains table₁, table₂ and table₃.

Comments

The base file can be commented, each hyperlink in the base file can have a one-line comment, the ref file can be commented, and each table in the ref file can be commented. one-line comments, ref file comments and table comments are treated the same in the base file and ref file. base file comments are treated differently for non-subordinateed and subordinated lists.

For our purposes let’s restrict ourselves to comma seperated fields, but the choice of which character to use is user selectable.

one-line comments

The input .csv file is seperated into fields. The general field structure is:

     Legal .csv field input     Description
     #!,base file comment       base file text for non-subordinated lists
     #,table comments           table descripton
     topic,,,one-line comment   new topic 
     title,,,URL                book entry + hyperlink
     title,,x,URL               book entry + hyperlink + separate page
     title,author,,URL          book entry + hyperlink + author name
     title,author,x,URL         book entry + hyperlink + author name + separate page
   

The only item which is not self explanatory is the “separate page”. This
option is there for those book hyperlinks which requre user selection, or
othe user input, before the book can be dounloaded. When the option is
present, the gereated HTML will force a borwer to create a separate tab
for dialog wiht the download site.

Other than that, if the fifth field of the table topic entry contains
text with or without HTML tags, then this text will be inserted as a
one-line comment in the base file generated table links.

Suppose the input file is “knitting.csv”. Suppose we have the following
tables and text:

Knitting,,,How to Knit
Yarn,,, – Types of Yarn
Needles,,,$ Where to purchase needles

The base file for non-subordinated implementation is:

1. Knitting How to Knit
2. Yarn – Types of Yarn
3. Needles $ Where to purchase needles

The base file for a subordinated implementation is:

1. Knitting
1. Knitting How to Knit
2. Yarn – Types of Yarn
3. Needles $ Where to purchase needles

Table Description

If field 1 contains an “#’ then field 2 is considered as line in the table description. All lines for a given table must immediately precede the start of the table defintion, the table topic line.

All description lines are concatenated together and are output as a table description prior to the HTML for a table. Each line can have HMTL tags within it.

Suppose the input file is “knitting.csv”. Suppose we have the following tables and text:

#,Knitting is an art, not something that is casually acquired.
#,Gratefully, practitioners of the are have written about it.
#,They have expressed the mechanics of knitting and have
#,shown examples of what you can do. Here are their books:
Knitting,,,How to Knit

#,An important part of knitting is to select the correct
#,material to knit with. Knitting a sweater requires different
#,yarn than knitting a doilie. Here are links to various
#,resources that can be used to purchase the correct material
#,for your projects.
Yarn,,, – Types of Yarn

#,Knitting requires needes. The needles come in various
#,forms, are made of various materials, and perform different
#,funtions. Here are some books which describe the needles
#,available and how best to use them.
Needles,,,$ Where to purchase needles

This is the what the use sees after double clicking each hyperlink in the base file:

1. Knitting How to Knit

Kitting is an art, not something that is casually acquired. Gratefully, practitioners of the are have written about it. They have expressed the mechanics of knitting and have shown examples of what you can do. Here are their books:

                  Knitting
            Book             Author

2. Yarn – Types of Yarn

An important part of knitting is to select the correct material to knit with. Knitting a sweater requires different yarn than knitting a doilie. Here are links to various resources that can be used to purchase the correct material for your projects.

                         Yarn
                Book             Author

3. Needles $ Where to purchase needles

Knitting requires needes. The needles come in various forms, are made of various materials, and perform different funtions. Here are some books which describe the needles available and how best to use them.

                        Needles
                Book             Author

Base File Comments

Inserting comments in the base file is treated differently for subordinate and non-subordinated lists. For subordinated lists a text file named topic.txt must be provided. The test file contents become the base file, named “topic”, comments. For non-subordinated you can provide a text file before each .csv file containing the comments, or in each .csv file any rows with “#!” in the first field is considered to be a
base file comment. All such rows within the .csv file are concatenated.

Giving examples for subordinated and non-subordinated lists:

> mkpage.awk [-FSEP] [-v site=URL] -v name=Math Topic₂.csv
> mkpage.awk [-FSEP] [-v site=URL] file₁.txt file₁.csv …
>> mkpage.awk [-FSEP] [-v site=URL] file₁.csv …

Suppose we want the following comment:

Knitting is an art form which has been arond for centuries, from about the 11th century C.E to the present.

All the following will yield the same result.
topic.txt contining the offending paragraph.
file_x.txt contining the offending paragraph.

or for non-subordinated lists only:
#!.Knitting is an art form which has been arond
#!.for centuries, from about the 11th century C.E
#!.to the present.

In each case the base file will contains the text preceding the list.

Restriction

1. Double quotes should not be used!
2. Do not use linefeeds.
3. Do not use a carriage return as a line terminator.

Input .csv Format

A .csv output of a spreadsheet file:

#!,base file comment for non-subordinated lists only
#,table description
topic,,,comment must be first line of any table or
topic,,, must be first line of any table
title,author,target,URL
title,author,,URL
title,,target,URL
title,,,URL


where

topic	table caption
title	book title
author	book author
target	“” if the book is directly downloadable [:print:] if there is a required interaction
URL	hyperlink address of the book download
comment	One liner to be inserted in the reference to the table

Output files

topic	base file containing references to tables
topic_TABLES	table file

In Apologia (and other things)

The choice of gawk was because I wanted to learn the language and I wanted an OS and computer independant resource. I chose gawk over Java and Perl. I already have ongong projects in these languages and, well, it was time to learn gawk. The choice was unfortunate. gawk has some large drawbacks as a production language for moderate sized projects, and that with my own inherent lack of style and ignorance, makes for (almost) unmaintainable code. I pity the maintainer, sigh.

If this thing grows legs, then future efforts will probably lead to a recoding in either Java or Perl. This dog deserves to be put to sleep. But any future modifications depends on outside interest. For me, the code serves its purpose and supports my needs.

I am well served by any comments you may have. The good and the ill aid me.