*! version 1.7 29sep2019

*! Doug Hemken

Title

stmd --
Convert standard dynamic Markdown to HTML, DOCX, or PDF format, using
Stata dyndoc

Syntax

stmd
srcfile
[arguments]
[, options]

srcfile is a plain text file containing text
and code blocks in standard dynamic Markdown format.

arguments are stored in the local macros `1', `2', etc,
and passed to srcfile.

Enclose filenames in double quotes
if they contain blanks or other special characters.

Main
saving(targetfile) specify the target HTML, Word,
or PDF file to be saved

replace replace targetfile if it already exists

Other
docx output a Word (.docx) document

pdf output a PDF document

embedimage for HTML documents, embed images
rather than link them

hardwrap conserve line breaks from the
srcfile

nomsg suppress file messages

noremove suppress <<dd_remove>> processing

nostop do not stop if an error occurs

Description

stmd takes a dynamic Markdown document which uses conventional
markdown specification and converts it to HTML, Word, or PDF via
Stata's dyndoc command. stmd is a wrapper for
stmd2dyn followed by dyndoc.

Options

Main

saving(filename:targetfile) to specify the final document's file
name. If not specified this defaults to
srcfile with the appropriate file extension.

replace replace the targetfile if it already exists

Other

Additional options (which are passed to dydndoc)
are docx, pdf, embedimage, hardwrap,
nomsg, noremove, and nostop

docx specifies the targetfile be saved in
Microsoft Word format.

pdf specifies the targetfile be saved in
Adobe PDF format.

embedimage specifies that any images be saved as
part of the (HTML) targetfile, rather than as
linked files.

hardwrap specifies that hard wraps (line breaks) in the
srcfile are reproduced in the targetfile.

nomsg suppresses intermediate file messages and the
link to the targetfile.

noremove specifies that <<dd_remove>> and <</dd_remove>>
tags should not be processed.

nostop allows the document to continue being processed even if an error
occurs.

Remarks

The conventional style for dynamic Markdown files is for the dynamic
content to be specified in fenced code blocks with an
information tag. For example

```stata

sysuse auto

```

would be a dynamic code block that loaded the auto data set. To
accomodate some existing Stata markdown usage, this may be written as three
or more backticks or tildes, curly braces around "stata" may be added,
and "stata" may be abbreviated simply "s".

In addition to marking a fenced code block for dynamic execution, various
options may be included in the information tag that control whether a
block is executed, and what resulting text may be included in the document.

This takes the general form

```stata, option(s)

-- stata commands --

```

NO COMMANDS: To prevent the code from being echoed in your
document use the nocommands option. Alternatively, this
may be specified as echo=FALSE, or a forward
slash immediately after "stata".

NO PROMPT: To prevent the typical period prefixing echoed commands,
use the option noprompt.

NO OUTPUT: To prevent the output from appearing in your document
(but to still see the commands and have them execute),
use the option nooutput. Alternatively, use
results=FALSE or results="hide".

NO COMMANDS OR OUTPUT: To prevent ANY output from appearing in your document
(but to still have your code execute),
use the option quietly.

NO EVALUATION: To prevent code evaluation, simply don't include an
information tag. Alternatively, include the eval=FALSE option
(from R).

For example, this would show your regression results, but not the
code that produced them:

```stata, nocommands

sysuse auto

regress price weight

```

For further information on writing Markdown documents, see
help markdown

Examples

. stmd example.stmd, replace

Author

Doug Hemken

Social Science Computing Cooperative

Univ of Wisc-Madison

dehemken@wisc.edu

https://www.ssc.wisc.edu/~hemken/Stataworkshops

https://github.com/Hemken/stmd