*! version February 14, 2020 @ 10:30:21

Title

putwrap -- Wrapper to simplify putdocx and putpdf files

Syntax

putwrap
using filename
[,
options
]

Description

putwrap is a simple-minded wrapper for making putdocx and
putpdf easier to use. It allows new paragraphs to be defined
using blank lines and text to be typed as-is, negating the need for
endless putxxx paragraph and putxxx text commands. The aim
is to make a more-readable source document.

Options

saving(filename) allows overriding the default file name for the do-file saved by putwrap.

The default value of the generated do-file depends on the
extension of the using file.
If the using file is named, say simple.wrap, then the
resulting do-file will be named simple.do.
If the using file is named, say simple.do, however, then the resulting do-file will be named simple_conv.do.

replace allows replacing the generated do-file.

defpar(str) allows specifying arguments for the generated putxxx paragraph commands.
This probably is better handled by setting the style for the document as a whole, but the option could be useful if the source document were split into pieces with different styles.

Remarks

Both putdocx and putpdf require every paragraph to start
with a putxxx paragraph.
They also require that simple text be embedded in putxxx text
commands.
This makes simple narrative text nearly impossible to read in the base
document.
putwrap allows narrative text to be written as simple text without these markers.

The rules are simple enough:

To make a new paragraph, put in at least one blank line.

To start Stata (non-narrative) code, type

putxxx pause

To go back to narrative mode, type

putxxx resume

If you would like to include comments in the narrative, start them with an *.

If you need something fancier than the default formatting in the narrative, use standard putpdf or putdocx commands.

This is meant to be a very simple-minded wrapper (and perhaps to get
others interested in better simple-minded wrappers). It is not a markdown
processor or anything which replaces the directives of putxxx
with another language. It is just a simpler way to write narrative.

One final note: Do not use a continuation comment (///) between putdocx and pause or between putdocx and resume. It is not only silly to split such a short line, it will cause an error because of the way putwrap looks for these two added subcommands.

Example

Here is an example to illustrate what a file would look like (it
is included in the ancillary files as example.do).
Note: copying and pasting the following as an example will not work
well, because the resulting leading spaces get preserved in the
narrative.

putdocx clear

putdocx begin

putdocx paragraph, style(Heading1)

This is the title for this document

This for text inside of the document. It can go on and on. After all, most documents are mostly text. It can have new paragraphs without a bunch of extra commands. The important part is that it is halfway possible to read what is being done here.

This is now a second paragraph, which is starting with two linebreaks in a row. The two line breaks are just the equivalent of a simple putdocx paragraph, with no options.

If you wanted to be fancy, and have the putdocx command above show up like code in the docx document, you still do standard putdocx work.
The blank lines are equivalent of a simple

putdocx text ("putdocx paragraph"), font("Courier New",10)

with no options.

Now we can put in some Stata code... which will not appear in the document.

* Star-comments can be used to make things readable

* The indentation of the code is not not special... it is for readability

putdocx pause

sysuse auto, clear

gen gp100m = 100/mpg

graph matrix gp100m weight length turn

graph export gphmat.png, replace

regress gp100m weight length turn i.foreign

** end of Stata code

putdocx resume

Now some results from our analysis. First a picture of the results

putdocx image gphmat.png, width(4)

Now the result of the regression:

putdocx table reg = etable

* tables require a new paragraph to flush the table, hence the blank line

There we go... some analysis and some text in one document.
This still has some programmerish stuff in it, but it can be typed and read a bit more quickly.

putdocx save example, replace

Stored results

None

Author

Bill Rising, StataCorp

email: brising@stata.com

web: http://louabill.org