help for htmlutil(Roger Newson)

Utilities for writing Hypertext Markup Language (HTML) files

Open a HTML file

htmlopen handle using filename [ , replace attributes(attributes_list)

head headattributes(head_attributes_list)
title(string)
headfrom(filename)

body bodyattributes(body_attributes_list)

bom(bom_option)

]

where attributes_list is a list of attributes for the <html> tag in HTML,
head_attributes_list is a list of attributes for the <head> tag in HTML,
body_attributes_list is a list of attributes for the <body> tag in HTML,
handle is a file handle as recognized by the file utility,
and bom_option can be an empty string or utf-8.

Insert an image in an open HTML file

htmlimg handle [ , attributes(attributes_list)
]

where attributes_list is a list of attributes for the <img> tag in HTML,
and handle is a file handle as recognized by the file utility.

Insert a hyperlink in an open HTML file

htmllink handle [ ,
attributes(attributes_list) linktext(link_text)
]

where attributes_list is a list of attributes for the <img> tag in HTML,
link_text is a piece of HTML code,
and handle is a file handle as recognized by the file utility.

Close an open HTML file

htmlclose handle [ , body ]

where handle is a file handle as recognized by the file utility.

Description

The htmlutil package is a suite of file handling utilities
for producing Hypertext Markup Language (HTML) files in Stata.
The user can open the file for input using htmlopen,
and close the file using htmlclose.
In between these statements,
the user can insert linked images from files using htmlimg,
insert hypertext links using htmllink,
insert HTML tables using the listtab package,
and insert more HTML using the tfinsert package.
The packages listtab and tfinsert are downloadable from SSC.

Options for htmlopen

replace specifies that any existing file with the name specified by the filename
will be replaced.

attributes(attributes_list) specifies a list of attributes,
to be passed to the <HTML> tag at the start of the HTML file.

head specifies that a HTML head will be added to the new HTML file.
If the headattributes(), headfrom() and title() options are not specified,
then this HTML head will contain only the tags <head> and </head>.

headattributes(head_attributes_list) specifies that a HTML head will be added to the new HTML file,
with attributes for the <head> tag specified by the head_attributes_list.
The headattributes() option implies the head option,
even if head is not specified by the user.

title(string) specifies a title for the HTML document being created,
which will be output in the document head between a <title> tag and a </title> tag,
and will specify the Web page title visible on the browser tab when the HTML file is opened in a browser.
The title() option is not compulsory,
and the HTML document will still open in most browsers if it is not specified.
However, the HTML document will then probably not be a valid HTML document,
under the strict definition of HTML,
and the browser tab will probably display an alien-looking file path,
instead of a friendly-looking Web page title.
The title() option implies the head option,
even if head is not specified by the user.

headfrom(filename) specifies that the HTML head will contain
HTML code from the file specified by the filename.
If the head option is specified (implicitly or explicitly),
then the code from the filename will be inserted after the <head> tag,
and before the <title> and </title> tags requested by the title() option.
If the head option is not specified (either explicitly or implicitly),
then the code in the file specified by the filename
has to start with a HTML <head> tag, and end with a HTML </head> tag,
and should also contain a <title> tag and a </title> tag,
with the Web page title in between.
The headfrom() option enables the user to build libraries of customized HTML head inserts in files,
containing HTML style information, metadata and other specifications,
and to use them regularly in multiple HTML documents, with different titles,
generated using the htmlutil package.
If the file specified by headfrom() does not exist,
then htmlopen will give an error message, but will complete execution normally,
inserting no HTML head insert.

body specifies that a HTML <body> tag will be added to the new HTML file,
after any HTML head specified by the head, headattributes() and/or headfrom() options.
If the bodyattributes() option is not specified,
then this tag will have no attributes, and will simply be <body>.

bodyattributes(body_attributes_list) specifies that a HTML <body> tag will be added to the new HTML file,
after any HTML head specified by the head, headattributes() and/or headfrom() options,
with attributes specified by the body_attributes_list.
The bodyatributes() option implies the body() option,
even if body() is not specified by the user.

bom(bom_option) specifies a byte order marker (BOM) to be the first byte of the HTML output file.
It may be an empty string (the default, specifying no BOM)
or utf-8, specifying the UTF-8 byte order marker "\uFEFF".
The option bom(utf-8) should be specified if the output HTML file is intended to be a UTF-8 file,
as it should be if there will be Stata unicode strings in it.

Options for htmlimg

attributes(attributes_list) specifies a list of attributes for the HTML <img> tag.
These attributes should include a src=filename attribute,
to specify the image source file.
This image source file might be an exported Stata graphics file, created by the graph export command.

Options for htmllink

attributes(attributes_list) specifies a list of attributes for the HTML <a> tag.
These attributes should include a href=filename attribute,
to specify the hypertext reference location.

linktext(link_text) specifies the link text
to be inserted in the HTML link between the <a> tag and the </a> tag.
Note that the link text does not have to be plain text, but can be any HTML code.
For instance, it might contain a HTML <img> tag, specifying an image for the reader to click on.

Options for htmlclose

body specifies that a HTML </body> tag should be added just before the </html> tag at the end of the new HTML file.
The body option for htmlclose should be used if and only if the corresponding htmlopen command
also has a body option (supplied explicitly or implicitly).

Remarks

The htmlutil package produces Hypertext Markup Language (HTML) documents.
The htmlopen command opens a file and initializes the output with the lines

<!DOCTYPE html>

<html>

if no attributes() option is supplied, and with the lines

<!DOCTYPE html>

<html attributes_list>

if a non-empty attributes() option is supplied.
The htmlopen command may then add a HTML head,
if one is specified using the head and/or headattributes() and/or title() and/or headfrom() options,
and/or initialize a HTML body by adding a HTML <body> tag,
if one is specified using the body and/or bodyattributes() options.

The htmlclose command outputs, to a file already open for text output, the lines

</body>

</html>

if a body option is specified, and only the line

</html>

if no body option is specified,
and then closes the open file.
This ensures that,
if the htmlopen and htmlclose commands either both specify a HTML body or both do not specify a HTML body,
and if the user outputs well-formed HTML code between the htmlopen and htmlclose statements,
then the HTML document as a whole will be well-formed and readable using a browser.

It is a good idea to enclose all code between a htmlopen command and the corresponding htmlclose command
in a capture noisily block,
beginning with the command

capture noisily {

and ending with the command

}

This ensures that, if any command in the capture noisily block fails,
then Stata will transfer control to the htmlclose command
immediately following the capture noisily block,
and the new HTML file specified by htmlopen will be closed,
and will be available for inspection by the user,
using a Web browser.

The SSC package listtab can be used for inserting HTML tables into a HTML file created using the htmlutil package.
For more about listtab, see Newson (2012).
For more about outputting HTML documents from Stata, see Quintó et al. (2012),
Jann (2005) and Jann (2017).

Examples

The following example generates a document mydoc1.htm,
containing HTML code inserted using the tfinsert package,
downloadable from SSC..

. tempname handle1

. htmlopen `handle1' using "mydoc1.htm", replace

. capture noisily {

. tfinsert `handle1', terminator(END_OF_HTML)

. <head>

. <title>My Hello World webpage</title>

. </head>

. <body>

. <p>

. Hello, World!!!!

. </p>

. </body>

. END_OF_HTML

. }

. htmlclose `handle1'

The following example generates a document mydoc2.htm,
which contains a HTML table of the mileages and weights of the 22 non-American cars in the auto data.
This table is generated using the listtab package,
downloadable from SSC.
The rest of the HTML is generated using the tfinsert package.

. sysuse auto, clear

. keep if foreign==1

. tempname handle2

. htmlopen `handle2' using "mydoc2.htm", attributes(lang=en-US) replace

. capture noisily {

. tfinsert `handle2', terminator(END_OF_HTML)

. <head>

. <title>My non-US cars webpage</title>

. </head>

. <body>

. <h1>Mileage and weight in non-US cars</h1>

. <table>

. END_OF_HTML

. listtab make mpg weight, handle(`handle2') rstyle(html) head("<tr><th>Make</th><th>Mileage (mpg)</th><th>Weight (lb)</th></tr>")

. tfinsert `handle2', terminator(END_OF_HTML)

. </table>

. </body>

. END_OF_HTML

. }

. htmlclose `handle2'

The following example generates a document mydoc3.htm,
which contains the same HTML table of the mileages and weights as the previous example.
It also contains a graph of the same data,
produced using graph export in Stata to produce a Scalable Vector Graphics (.svg) file mydoc3_1.svg,
and inserted into the HTML document using the htmlimg command,
and a hyperlink (inserted using htmllink)
to the .pdf graph of the same data in the file mydoc3_1.pdf,
also produced using graph export.
Note that the attributes list passed to htmlimg
is enclosed in compound quotes,
as the attributes list itself contains double quotes.

. sysuse auto, clear

. keep if foreign==1

. tempname handle3

. htmlopen `handle3' using "mydoc3.htm", attributes(lang=en-US) head title("My graphic non-US cars webpage") body replace

. capture noisily {

. scatter mpg weight

. graph export mydoc3_1.svg, replace

. graph export mydoc3_1.pdf, replace

. htmlimg `handle3', attributes(`"src="mydoc3_1.svg" style="width:640px;""')

. htmllink `handle3', attributes(`"href="mydoc3_1.pdf""') linktext("<p>View the .pdf version of this image</p>")

. listtab make mpg weight, handle(`handle3') rstyle(html) head("<table>" "<tr><th>Make</th><th>Mileage (mpg)</th><th>Weight (lb)</th></tr>") foot("</table>")

. }

. htmlclose `handle3', body

The following advanced example generates a document mydoc4.htm,
which contains the same HTML table of the mileages and weights as the previous examples,
and uses a HTML head insert from a HTML file myhead1.htm,
which is inserted into the generated HTML document using the headfrom() option of htmlopen.
The file myhead1.htm contains a HTML head insert,
specifying that tables in the corresponding HTML body will be framed
using solid black lines 4 pixels in width,
and is listed as follows:

<style>

table, td, th {

border: 4px solid black;

}

</style>

The Stata code to use this user-specified customized HTML head insert in a new HTML document is as follows:

. sysuse auto, clear

. keep if foreign==1

. tempname handle4

. htmlopen `handle4' using "mydoc4.htm", head headfrom("myhead1.htm") title("My stylish non-US cars webpage") body replace

. capture noisily {

. listtab make mpg weight, handle(`handle4') rstyle(html) head("<table>" "<tr><th>Make</th><th>Mileage (mpg)</th><th>Weight (lb)</th></tr>") foot("</table>")

. }

. htmlclose `handle4', body

Author

Roger Newson, Imperial College London, UK.

Email: r.newson@imperial.ac.uk

References

Jann, B. 2005.
Making regression tables from stored estimates.
The Stata Journal 5(3): 288-308.
Download from The Stata Journal website.

Jann, B. 2017.
Creating HTML or Markdown documents from within Stata using webdoc.
The Stata Journal 17(1): 3-38.
Download from The Stata Journal website.

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

Quintó, L., S. Sanz, E. De Lazzari, and J. J. Aponte. 2012.
HTML output in Stata.
The Stata Journal 12(4): 702-717.
Download from The Stata Journal website.

Also see

Manual: [P] file

Help: [P] file

listtab, tfinsert if installed

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