*! version 3.2 06Oct2015
Version 3.3.8

*! cmd:help Weaver

weaver -- A general purpose package for creating dynamic report in HTML, LaTeX, and
PDF. Weaver includes a built-in JavaScript syntax highlighter for Stata code, an engine for
rendering LaTeX mathematical notations in LaTeX and HTML log files,
a number of specialized commands for creating publication-ready dynamic table,
inserting and resizing a figure, and writing dynamic text.
Moreover, Weaver also includes a built-in JavaScript-based language called
Weaver markup Language which allows the users to create a
sophisticated HTML document using a simplified and minimalistic markup language,
similar but not identical to Markdown.

Weaver is essentially an independent HTML or LaTeX log system
that runs in paralel to Stata log and can be used simultaniously with regular
smcl or text logfile. In contrast to smcl log file, the main idea of the Weaver
package is to provide the possibility of deciding which commands, results, and
figures should appear in the Weaver log (dynamic report). Therefore, Weaver log is
not autonomous. The big advantage of this approach to
dynamic reporting is that as the user carries out the data analysis interactively,
the dynamic document can be viewed in real-time by refreshing the HTML web-browser,
or opening the LaTeX document in TeXstudio or any advanced text editor such as
Sublime Text, or alternatively, reandering a
PDF document at any point.
These features work smoothly for both LaTeX and HTML. Another example
would be a LaTeX table exported from tabout command which can be merged in
Weaver's LaTeX log.

Weaver is a general purpose package that is designed to effectively handle HTML and
LaTeX documents. It includes many additional features that makes it a prime package
for collaborating with all other packages for developing automated outputs such as
MarkDoc, tabout, etc. Any package that produces LaTeX or HTML output,
cal collaborate with Weaver because Weaver allows importing HTML and LaTeX
documents. For example, a document written in Markdown language
and exported to LaTeX or HTML using the MarkDoc package, can be simple merged
into Weaver's LaTeX or HTML log respectively.

Visit
http://haghish.com/weaver
for a complete tutorial on Weaver as well as downloading template do-files.

Author

E. F. Haghish

Center for Medical Biometry and Medical Informatics

University of Freiburg, Germany

haghish@imbi.uni-freiburg.de

http://haghish.com/weaver

Package Updates on Twitter

Related help files

Simplified Weaver Markup Language

Rendering LaTeX mathematical notations in HTML and LaTeX log files

Statax JavaScript Syntax Highlighter

div command for ncluding Stata code and output in the document

img command for inserting a figure or image in the document

txt command for writing dynamic text in the document

tbl command for creating dynamic table

Summary of Weaver commands

Weaver includes two sets of commands. The "weave commands" are related to the
Weaver log file. For example, opening
and closing a log file, turning the log file on or off, preserving and restoring the
log file, rendering a pdf document from the log, etc. Therefore, a
dynamic document begins and ends with these commands. The syntax of "weave commands"
is very similar to Stata smcl log syntax although Weaver provides more features.
The other commands which are div, txt, img, and tbl are
generally related to the content of Weave log. For example, they are used for annotating the
document, writing code and output to the Weaver log, inserting image, and creating
dynamic table. These commands
are explained in two separate sections.

weave using filename [, options]

weave merge using filename

weave pdf [, replace]

weave query

weave {off|on}

weave {preserve|restore}

weave close

weave setup

div [code|result] command

txt [code] "string"

img filename [, options]

tbl (*[,*...] [\ *[,*...] [\ [...]]]) [, options]

Syntax of weave commands

Report status of Weaver log file

weave query

Open Weaver log file to begin the dynamic report

weave using filename [,
install
nopdf
printer(str)
markup(name)
append
replace
papersize(name)
margin(int,int,int,int)
style(name)
template(filename)
landscape
toc
font(name)
title(str)
author(str)
affiliation(str)
address(str)
summary(str)
date
synoff
noisily
]

Merge a HTML file (html, xhtml, htm) or LaTeX document to Weaver HTML or LaTeX log respectively

weave merge using filename

PDF live-preview of dynamic document

weave pdf [, replace]

Close Weaver log and print the final pdf dynamic document

weave close

Temporarily suspend logging or resume logging

weave {off|on}

Preserve and restore the Weaver log

weave {preserve|restore}

Permanently set the default file paths to the required third-party software

weave setup

Syntax of annotating commands

Include both the Stata command and output in the Weaver log. The code and
result subcommands only echo the command or outputs in the Weaver log respectively.

div [code|result] command

Inserts, style, and resize a graph in Weaver log

img filename [, title(str) width(int)
height(int) left center ]

Create a HTML or LaTeX dynamic table in Weaver log

tbl (*[,*...] [\ *[,*...] [\ [...]]]) [, title(str) width(int)
height(int) left center ]

Write and style dynamic text and mathematics
notations. The code subcommand prints anything as-is on the
log.

txt [code] display_directive

Weave Options

install installs the wkhtmltopdf
PDF driver and MathJaX automatically in
the ~/plus/Weaver directory, if it is not already installed. For manual installation and more details, see below.

nopdf runs Weaver without requiring any third-party software by
omitting rendering a PDF and mathematical notations in the HTML log.

printer:(string) defines the file path to the
wkhtmltopdf or pdfLaTeX drivers. This option is only needed if the third-party
is not automatically installed in
the ~/plus/Weaver directory (see Software troubleshoot for more details).

markup:(name) define the log format which can be
html or latex.

replace replaces the log and pdf files if already exist.

append appends more content to the existing HTML or LaTeX file.

papersize:(name) defines the page size of the PDF document. The
default paper size is A4, however, Weaver supports most of the popular page sizes
including A0, A1, A2, A3, A4 A5
A6, A7, A8, A9, B0, B1, B2, B3, B4, B5,
B6, B7, B8, B9, B10, C5E, Comm10E, DLE, Executive,
Folio, Ledger, Legal, Letter, and Tabloid. These names can also
be specified in lower cases.

margin(int,int,int,int) defines 4 integers that change the margins of the
document clockwise, beginning with the top margin, to the right margin, then bottom margin,
and then the left margin of the document respectively. The integer sets the margin in terms
of number of mm.

style:(name) change the style of the document. The available
styles are modern, classic, stata, elegant, minimal, and empty.
The stata style is the default style. The empty style creates an empty
HTML or LaTeX document, allowing the user to create the dynamic document from
scratch which also excludes all of the JavaScripts programs and the syntax
highlighter as well or the LaTeX template.

template:(filename) link an external style sheet file to allow
users to change the appearence of the document. All the styles
relating to the document, syntax highlighter, and the dynamic table can be
overruled using this option. For HTML log, attach a CSS file and for LaTeX log, write the heading in a file and use it as a template. Weaver can also automatically extract the heading from other LaTeX documents if you use them as templates.

landscape flips the page orientation to the landscape mode.

toc add an automatic table of contents.

font:(string) specifie the text font for all
headings, subheadings, and paragraphs. Each style:(name)
option automatically
applies different fonts. Therefore, use this option only if you are
unsatisfied with the default fonts. Note that the available LaTeX fonts differ
from HTML fonts. The list of available LaTeX fonts is cmr, lmr,
pbk, bch, pnc, ppl, ptm, cmss, lmss,
pag, phv, cmtt, lmtt, pcr
(Read more about LaTeX fonts).

title:(string) specify the title of Weaver log.

author:(string) specify the author name.

affiliation:(string) prints the author's affiliation
(or any preferred relevant information).

address:(string) prints the author's contact information
(or any preferred relevant information).

summary:(string) add a summary paragraph.

date prints the current date on the first page

synoff turns off Statax JavaScript syntax highlighter engine.

noisily noisily performs Weaver commands ; if specified, Weaver
commands print outputs on the results windows and thus, MarkDoc
package can be used with Weaver simultaniously.

Description

The Weaver package provides a set of commands for writing and styling a dynamic report
in Stata. What makes Weaver different from the MarkDoc package - which
also create dynamic reports- is that Weaver creates an HTML or LaTeX log file that
runs in paralel to Stata log file and can select
what Stata commands, outputs, text, and comments to appear in the dynamic
document. This feature is particularly
interesting because it avoids starting a new do-file for creating the dynamic document.
The Weaver log file system is distinguished from smcl log files and thus, the
user can use them both at the same time, to register all the
commands and results in the Stata smcl log as well as creating a selective
dynamic document that can also include figures and graphs, render mathematical
notation, include a syntax highlighter for Stata code, create publication-ready
dynamic tables, and also dynamic text for interpreting the results of the analysis.

The biggest advantage of Weaver compared to MarkDoc is
that it does not need to be compiled and is independent of smcl log files. In
fact, Weaver is based on HTML or LaTeX and stores
text, commands, and output in these rather than smcl. As a
result, the document
can be live-viewed in by opening the HTML log file and refreshing the
browser or using a LaTeX editor such as TeXstudio at any point.

Command Description

weave using filename [, options] creates a HTML or LaTeX log
for the dynamic document. Therefore, the dynamic document begins with this command. weave can
accept several options that determine the title, author name, author information and
affiliation, date, running head, summary of the report, table of content, document format and style, etc.

weave merge using filename Merges the content
of a file to the HTML or LaTeX log. It can be used for adding existing html,
htm, and xhtml documents to the HTML log or a LaTeX tex document
to the LaTeX log. Note that in contrast to HTML, LaTeX document has a very
strict structure, beginning with loading packages, \begin{document} and
ending with \end{document}. If there is a multiplication of this
command, the LaTeX document will not be compiled. However, Weaver is programmed
to take care of all of the potential risks in merging LaTeX documents, which means
if the document that is being merged is not properly prepared for a straightforward
copy and past, Weaver will identify the problematic code and turn merges them as
comments and notifies the user.

weave close closes the Weaver log file and prints the pdf document, if the pdf
driver is installed. The dynamic document ends with this command.

weave pdf [, replace] creates a
live-preview pdf document from the HTML or LaTeX log at any point. This command is useful for checking
the document to make sure its format and content is desirable.

weave {off|on} temporarily turnes the log file on or off.

weave {preserve|restore} preserves the current status
of the Weaver log file and restore it back. These two subcommands are useful while
doing exploratory analysis and deciding to restore the older version of the Weaver log.

weave setup permanently define the paths to executable
wkhtmltopdf, pdfLaTeX, and MathJax third-party software.

Required Software

As long as the nopdf option is specified, Weaver does not require
any third-party software. However, for rendering PDF from the HTML or LaTeX log
files as well as rendering MathJax mathematic notations in the HTML log, Weaver
requires additional third-party software.
The required software can be installed
manually or automatically and both procedures are explained below.

Automatic Installation

For automatic installation of wkhtmltopdf and mathJax, use the install option
when opening a new log file. For example:

. weave using example.tex, install

Weaver will automatically check for the software
on your machine and if it does not access the software, it will download a portable
version of the software in Weaver directory, which is located in
~/ado/plus/Weaver/ on your machine. To find the location of PLUS directory
on your machine check the system directories of Stata by typing
sysdir in Stata command window. The usual complete
paths to the Weaver directory are shown below. Note that username refers to your machine's username.

Windows: C:\ado\plus\Weaver

Macintosh: /Users/username/Library/Application Support/Stata/ado/plus/Weaver

Unix: /home/username/ado/plus/Weaver

The automatic installation is expected to
work properly with Microsoft Windows XP, Windows 7, and Windows 8.1, Macintosh
OSX 10.9.5 and 10.10, Linux Mint 17 Cinnamon (32bit & 64bit), Ubuntu 12 and 14 (64bit), and
CentOS 7 (64bit). Other operating systems may require manual software installation.

Please read the license agreement of wkhtmltopdf
and mathjax software. By choosing automatic
installation, you also confirm that you are aware and agreed with the license agreements.

Manual Installation

wkhtmltopdf is a free open source (LGPL)
command line tools to render HTML into PDF. The application is available for Windows, Mac,
and Unix as a freeware. Users can download and install this application on their machines and
give the path to executable wkhtmltopdf using the printer(str) or
specify the path to this application permanently, by editing the weaversetup.ado
file using the weave setup command. Visit
Installing PDF Printers for more details.

Weaver also requires mathjax.org JavaScript
which renders LaTex mathematical notations in HTML log. This software
is not required in LaTeX log files. On the main page of mathjax.org,
you can download MathJax-master.zip file and unzip it inside Weaver directory,
in ~/ado/plus/Weaver/ on your machine. Alternatively, you can define the
path ro the MathJax-master directory by editing weaversetup.ado
file using the weaver setup command. This file is automatically generated the first time the weaver setup command is executed and will serve as a long-term memory file for the
Weaver as well as MarkDoc package.

Remarks

Weaver interacts with the operating system for installing, creating, replacing, and removing files.
It is recommended to the users to use the machine as an administrator, run Stata as administrator,
and make sure they have the permission if creating and replacing files in the working directory.
Stata should be allowed to remove or replace files in the working directory.

Example

Visit http://www.haghish.com/weaver
for downloading example do-files for the Weaver package.

Also see

Markdoc: Converting SMCL to any format using Pandoc

Statax: JavaScript syntax highighter for Stata

Synlight: SMCL to HTML translator and syntax highlighter