help for htmltit (Roger Newson)

Generate a document title variable for a HTML filename variable

htmltit varname [if] [in] , generate(newvarname)

Description

htmltit inputs a string variable,
assumed to contain the file names (or paths) of existing readable HTML documents,
and outputs a new string variable,
to contain the corresponding HTML document titles,
if they can be found in the documents.
htmltit is designed for use by users who want to create HTML documents
containing HTML tables to index (and link to) other HTML documents.
This can be done using the SSC packages htmlutil
(to generate the HTML documents},
xdir
(to generate datasets with 1 observation for each of a list of files which may be HTML documents),
and listtab (to generate the HTML tables).

Options

generate(newvarname) specifies the name of the new string variable,
containing the document titles.
This option must be present.

Remarks

htmltit is designed for use in output datasets (or resultssets),
with one observation for each of a list of files,
created using the xdir package,
which can be downloaded from SSC.
It inputs a variable containing file names, or file paths,
some of which may belong to readable HTML documents.
It attempts to find, in each readable document,
the HTML document title,
and to store that document title (if found) in the generated output variable
specified by the generate() option.
It does this by searching down the document (if the document is readable),
and stopping the search if and when it finds a line of text
which (after trimming space characters from the left and the right)
begins with a HTML <title> tag and ends with a HTML </title> tag.
htmltit then writes this line of text
to the corresponding observation of the generated output variable,
after removing the HTML <title> and</title> tags.

A valid HTML document should always have a document title.
Most browsers will open a HTML document without a document title,
but they will then have an alien-looking file location in the browser tab,
instead of a user-friendly document title.
The document title is located in the head of the HTML document,
between a HTML <title> tag and a HTML </title> tag.
It is not strictly compulsory for the document title to be on a single line,
with no other HTML code,
except for space characters to the left of the HTML <title> tag
and space characters to the right of the HTML </title> tag.
However, the document title will probably have this feature in most valid HTML documents,
most of the time.
In particular,
a document title will have this feature if the document was generated
using the SSC package htmlutil,
at least if the document title was inserted
using the title() option of the htmlopen module.

The htmltit package was written to work with HTML documents written in Unicode.
The file search procedure therefore uses the Unicode versions of
Stata string functions.
This should make htmltit useful for users who wish to generate HTML document indices
using non-ASCII scripts.

The htmltit package was designed for use with the SSC packages
htmlutil (to generate HTML documents),
xdir (to generate datasets with 1 observation for each of a list of files),
and listtab (to generate HTML tables).
The htmlutil package is designed for use with the official Stata file suite of commands.
For more about the use of listtab to generate tables in HTML and other formats,
see Newson (2012).

Examples

The examples are designed to be demonstrated in an output dataset (or resultsset)
produced by the SSC package xdir.
This resultsset has one observation for each of a list of files,
all of which are HTML documents,
and variables dirname (containing the directory location)
and filename (containing the file name).
The htmltit package adds a new variable,
containing the HTML document titles.

Set-up:

. clear

. xdir, dir(.) pattern(*.htm) norestore

. describe, full

. list, abbr(32)

The following example simply creates a new variable doctitle,
containing the document titles,
and lists all the variables for all the documents
for inspection by the user:

. htmltit filename, generate(doctitle)

. describe, full

. list, abbr(32)

The following more advanced example creates a new document title variable doctitle2,
and then uses the SSC package htmlutil
to create a very basic HTML document index.htm,
which contains a very basic HTML table,
with 2 columns, containing the HTML document file names
and their document titles.
Note that we use a capture noisily block
to ensure that,
in the event of an error in any of the output commands between htmlopen and htmlclose,
the HTML document index.htm
will be closed,
and available for inspection by the user
by opening it in a Web browser:

. htmltit filename, generate(doctitle2)

. tempname htmb1

. htmlopen `htmb1' using "index.htm", title("All my HTML files in this folder") replace

. capture noisily {

. file write `htmb1' "<h1>My HTML files in this folder</h1>" _n

. listtab filename doctitle2, handle(`htmb1') rstyle(html) headline(<table>) footline(</table>)

. }

. htmlclose `htmb1'

A real-world example would be more advanced than this.
The table would probably have a heading.
And the table entries would probably contain HTML links,
enabling the user to click on entries in a browser and open the corresponding HTML documents.
We might also use the SSC package tfinsert
to insert HTML code to explain the tables.

Author

Roger Newson, Imperial College London, UK.
Email: r.newson@imperial.ac.uk

References

Newson, R. B. 2012.
From resultssets to resultstables in Stata.
The Stata Journal 12(2): 191-213.
Download from The Stata Journal website.

Also see

Manual: [P] file

Help: [P] file

xdir, htmlutil, listtab, tfinsert if installed

Other: The W3C HyperText Markup Language (HTML) Home Page at http://www.w3.org/MarkUp/