help texdoc    Jump to: Syntax, Description, Options, Examples, Remarks, Stored results
                                      Also see: http://repec.sowi.unibe.ch/stata/texdoc
---------------------------------------------------------------------------------------

Title

    texdoc -- Create a LaTeX document including Stata output

Syntax

    Process a do-file containing texdoc commands

        texdoc do filename [arguments] [, do_options ]

    Commands to be used within the do-file

        texdoc init [docname] [, init_options]   initialize the LaTeX document;
                                                 (re)set default behavior

        /*tex ... tex*/                          add a block of text to the LaTeX
                                                 document

        /*** ... ***/                            synonym for /*tex ... tex*/

        texdoc substitute [from to ...] [, add]  substitutions to be applied within
                                                 /*tex tex*/ blocks

        texdoc write ... | texdoc _write ...     add a line of (interpreted) text to
                                                 the LaTeX document

        texdoc append filename [, append_opts]   add the contents of a file to the
                                                 LaTeX document

        texdoc stlog [name] [, stlog_options]    start a Stata output log to be
                                                 included in the LaTeX document

        texdoc stlog oom cmdline                 suppress output of cmdline and
                                                 insert an output-omitted tag

        texdoc stlog quietly cmdline             suppress output without inserting an
                                                 output-omitted tag

        texdoc stlog cnp                         insert a continued-on-next-page tag
                                                 in the Stata output log

        texdoc stlog close                       stop the Stata output log

        texdoc stlog [name] using dofile [, ...] include an output log from the
                                                 commands in dofile

        texdoc stlog [name] [, ...] : command    include the output from command

        texdoc local name definition             define and backup a local macro

        texdoc graph [name] [, graph_options]    include a graph

        texdoc close                             close the LaTeX document

        // texdoc exit                           let texdoc do exit the do-file

    Remove all texdoc commands from a do-file

        texdoc strip filename newname [, replace append ]


    do_options                 Description
    ---------------------------------------------------------------------------------
      [no]init[(docname)]      initialize the LaTeX document
      init_options             options to be passed through to texdoc init
      nostop                   do not stop execution if a command returns error (not
                                 recommended)
      cd                       process the do-file within its home directory
    ---------------------------------------------------------------------------------

    init_options               Description
    ---------------------------------------------------------------------------------
    Main
      replace                  allow overwriting an existing LaTeX document
      append                   append output to an existing LaTeX document
      force                    enforce initialization even though texdoc do is not
                                 running

    Log and graph options
      [no]logall               whether to log all Stata output; the default is
                                 nologall
      stlog_options            options to be passed through to texdoc stlog
      gropts(graph_options)    options to be passed through texdoc graph

    Filenames/paths
      [no]logdir[(path)]       where to store the Stata output log files
      grdir(path)              where to store the graph files
      [no]prefix[(prefix)]     prefix for the automatic names
      [no]stpath[(path)]       include-path used in the LaTeX document
    ---------------------------------------------------------------------------------

    append_options             Description
    ---------------------------------------------------------------------------------
      substitute(subst)        apply substitutions; subst is from to [from to ...]
    ---------------------------------------------------------------------------------

    stlog_options              Description
    ---------------------------------------------------------------------------------
    Main
      linesize(#)              set the line width to be used in the output log
                                 (number of characters)
      [no]do                   whether to run the Stata commands; default is do
      [no]log                  whether to create a log and include it in the LaTeX
                                 document; default is log
      [no]cmdlog               whether to display a copy of the commands instead of
                                 an output log; default is nocmdlog
      [no]verbatim             whether to use verbatim command log; default is
                                 noverbatim

    Contents
      [no]output               whether to suppresses command output in the log;
                                 default is output
      [no]matastrip            whether to strip Mata opening and ending commands from
                                 the log; default is nomatastrip
      [no]cmdstrip             whether to strip command lines from the log; default
                                 is nocmdstrip
      [no]lbstrip              whether to strip line break comments from the commands
                                 in the log; default is nolbstrip
      [no]gtstrip              whether to strip continuation symbols from the
                                 commands in the log; default is nogtstrip
      [no]ltrim                whether to remove white space on the left of commands;
                                 default is ltrim

    Highlighting
      alert(strlist)           enclose specified strings in \alert{}
      tag(matchlist)           apply custom tags to specified strings

    Technical
      [no]hardcode             whether to copy the log into the LaTeX document;
                                 default is nohardcode
      [no]keep                 whether to erase the external log file if hardcode is
                                 specified; default is keep
      [no]custom               whether to use custom code to include the log file in
                                 the LaTeX document; default is nocustom
      [no]certify              whether to compare results against previous version;
                                 default is nocertify
      nostop                   (texdoc stlog using only) do not stop execution if a
                                 command returns error
    ---------------------------------------------------------------------------------

    graph_options              Description
    ---------------------------------------------------------------------------------
    Main
      as(fileformats)          the output format(s); default is as(pdf)
      name(name)               name of graph window to be exported
      override_options         override conversion defaults; see help graph export

    Environment
      [no]center               whether to center the graph; default is center
      [no]figure[(args)]       whether to use the figure environment; default is
                                 nofigure
      caption(string)          provide a caption for the figure
      label(string)            provide a label for the figure
      cabove or cbelow         where to place the caption; default is cbelow

    Include command
      optagrs(args)            arguments passed through to \includegraphics (or
                                 \epsfig)
      [no]suffix               whether to type the file suffix in \includegraphics
                                 (or \epsfig)
      [no]epsfig               whether to use \epsfig instead of \includegraphics;
                                 default is noepsfig
      [no]custom               whether to use custom code to include graph in the
                                 LaTeX document; default is nocustom
    ---------------------------------------------------------------------------------


Description

    texdoc provides tools to create a LaTeX document from within Stata in a weaving
    fashion (on weaving with Stata also see Rising 2008). The basic procedure is to
    write a do-file including Stata commands and sections of LaTeX code and then
    process the do-file by texdoc do. texdoc do will create the LaTeX document,
    possibly including graphs and sections of Stata output. The LaTeX document can
    then be processed by a LaTeX compiler to produce the final document. texdoc do is
    similar to the regular do command; arguments, if specified, will be passed to the
    do-file as local macros; see [R] do.

    Within the do-file, use texdoc init docname to initialize the LaTeX document,
    where docname is the name of the LaTeX document (possibly including a path;
    default suffix ".tex" will be added to docname if no suffix is specified).
    Alternatively, if the do-file does not contain a texdoc init docname command,
    texdoc do will automatically initialize the LaTeX document in the folder of the
    do-file using basename.tex as name for the LaTeX document, where basename is the
    name of the do-file without suffix. Furthermore, note that texdoc init without
    docname can be used within the do-file to change settings after the LaTeX
    document has been initialized.

    Thereafter, use the /*tex tex*/ delimiter structure to include blocks of LaTeX
    code. A block may span multiple lines. The opening tag (/*tex) must be at the
    beginning of a line (save white space); the closing tag (tex*/) must be at the
    end of a line (save white space).  You may also type /*** ... ***/ instead of
    /*tex ... tex*/. Macros in LaTeX code provided within /*tex tex*/ or /*** ***/
    will not be expanded. You can, however, use the texdoc substitute command to
    define text substitutions that will be applied (see texdoc substitute under
    Remarks below; furthermore, also see the remark on texdoc local).

    A single line of LaTeX code can also be provided by the texdoc write command.
    Stata macros in a LaTeX line provided by texdoc write will be expanded before
    writing the line to the LaTeX document. texdoc write adds a new-line character at
    the end of the line. If you want to omit the new-line character, you can type
    texdoc _write. Furthermore, to copy text from an external file into the LaTeX
    document, you can use the texdoc append command.

    To create a section in the LaTeX document containing Stata output, use the texdoc
    stlog command. texdoc stlog writes the Stata output to a log file and includes
    appropriate code in the LaTeX document to display the contents of the file. The
    "stata" LaTeX package providing the "stlog" environment is required to display
    the output. To make the "stlog" environment available, add \usepackage{stata} in
    the preamble of the LaTeX document (after having downloaded the necessary Stata
    LaTeX files using sjlatex; see below). texdoc stlog creates an automatic name for
    the output file, but you can also specify a custom name typing texdoc stlog name
    (possibly including a relative path).

    Within a Stata output section texdoc stlog oom cmdline can be used to suppress
    the output of a specific command and add an output-omitted tag (\oom) in the
    Stata output file. Alternatively, to suppress output without adding an
    output-omitted tag, type texdoc stlog quietly cmdline. Furthermore, texdoc stlog
    cnp can be used to insert a continued-on-next-page tag (\cnp).

    texdoc stlog close marks the end of a Stata output section. To include the Stata
    output from an external do-file, use texdoc stlog using filename where filename
    is the name of the do-file. Furthermore, to include just the output of a single
    command (without input), you can type texdoc stlog : command. texdoc stlog close
    is not needed after the using-form or the colon-form of texdoc stlog.

    Instead of selecting the Stata output to be included in the LaTeX document using
    texdoc stlog, you can also specify the logall option with texdoc do or texdoc
    init. In this case, all output will be included in the LaTeX document.

    texdoc local can be used within or after a Stata output section to define a local
    macro that will be backed up on disk. This is useful if you want include specific
    results in your text and want to ensure that the results will be available in
    later runs when suppressing the Stata commands using the nodo option. The syntax
    of texdoc local is the same as the syntax of Stata's regular local command. Local
    macros defined by webdoc local will be expanded in subsequent /*tex tex*/ or /***
    ***/ blocks (up until the next texdoc stlog command). For further information,
    see texdoc local under Remarks below.

    texdoc graph can be used to export the current graph and include appropriate code
    in the LaTeX document to display graph. texdoc graph can be specified within a
    texdoc stlog section or directly after texdoc stlog close. If texdoc graph is
    specified within a texdoc stlog section, the graph is included in the LaTeX
    document before the Stata output; if texdoc graph is specified after texdoc stlog
    close, the graph is included after the Stata output (furthermore, if texdoc graph
    is used outside a texdoc stlog section while logall is on, the graph will be
    placed at the position in the output where the texdoc graph command occurs). The
    name of the texdoc stlog section is used to name the graph (possibly suffixed by
    a counter if the texdoc stlog section contains more than one texdoc graph
    command), unless a custom name is specified.

    texdoc close closes the LaTeX document. This is not strictly needed as texdoc do
    closes the document automatically if the do-file does not contain a texdoc close
    command. Furthermore, to exit a do-file before the end of the file, add a line
    containing // texdoc exit (without anything else on the same line).  texdoc do
    will only read the do-file up to this line.

    texdoc strip removes all texdoc commands and all /*tex tex*/ or /*** ***/ blocks
    from a do-file.

    To be able to compile a LaTeX document containing Stata output you need to copy
    the Stata LaTeX files to your system and include \usepackage{stata} in the
    preamble of your LaTeX document. To obtain the Stata LaTeX files, first install
    the sjlatex package typing

    . net install sjlatex, from(http://www.stata-journal.com/production)

    After that, use command sjlatex install to download the Stata LaTeX files; see
    help sjlatex. You may keep the files in the working directory of your LaTeX
    document or, alternatively, copy the files to the search tree of your LaTeX
    installation (consult the documentation of your LaTeX installation for
    information on the search tree; for example, in MacTeX, you may add the files to
    a subfolder in ~/Library/texmf/tex/latex).


Options

    Options for texdoc do
    Options for texdoc init
    Options for texdoc append
    Options for texdoc stlog
    Options for texdoc graph
    Options for texdoc strip


Options for texdoc do

    [no]init[(docname)] specifies whether and how to initialize the LaTeX document.
        If the processed do-file contains a command to initialize the LaTeX document
        (i.e. if the do-file contains texdoc init docname) or if the LaTeX document
        is already open (e.g. in a nested application of texdoc do), the default for
        texdoc do is not to initialize the LaTeX document. Otherwise, texdoc do will
        automatically initialize the LaTeX document in the folder of the do-file
        using basename.tex as name for the LaTeX document, where basename is the name
        of the do-file without suffix.  Use the init option to override these
        defaults: noinit will deactivate automatic initialization; init will enforce
        automatic initialization; init(docname) will enforce initialization using
        docname as name for the LaTeX document (docname may include an absolute or
        relative path; the base folder is the current working directory or the folder
        of the do-file, depending on whether option cd is specified; default suffix
        ".tex" will be added to docname if no suffix is specified).

    init_options are options to specify defaults to be passed through to texdoc init.
        See below.

    nostop allows continuing execution even if an error occurs. Use the nostop option
        if you want to make sure that texdoc do runs the do-file all the way to the
        end even if some of the commands return error.  Usage of this option is not
        recommended. Use the nostop option with texdoc stlog using if you want to log
        output from a command that returns error.

    cd changes the working directory to the directory of the specified do-file for
        processing the do-file and restores the current working directory after
        termination. The default is not to change the working directory.


Options for texdoc init

        +------+
    ----+ Main +---------------------------------------------------------------------

    replace allows overwriting an existing LaTeX document.

    append appends results to an existing LaTeX document.

    force causes texdoc init to initialize the LaTeX document even though texdoc do
        is not running. By default texdoc init has no effect if typed in Stata's
        command window or if included in a do-file that is not processed by texdoc
        do.  Specify force to enforce initialization in these cases. The LaTeX
        document will remain active until you type texdoc close. Note that texdoc has
        only limited functionality if texdoc do is not running (for example, /***
        ***/ blocks and // texdoc exit will be ignored and some of the options of
        texdoc stlog will not work). Specifying force is not recommended.

        +-----------------------+
    ----+ Log and graph options +----------------------------------------------------

    [no]logall specifies whether to include the output of all Stata commands in the
        LaTeX document. The default is nologall, that is, to include only the output
        selected by texdoc stlog. Specify logall if you want to log all output. When
        logall is specified, texdoc do will insert appropriate texdoc stlog and
        texdoc stlog close commands automatically at each /*tex tex*/ or /*** ***/
        block or texdoc command (but not at texdoc stlog oom and texdoc stlog cnp).
        Empty lines (or lines that only contain white space) at the beginning and end
        of each command section will be skipped.

    stlog_options are options to set the default behavior of texdoc stlog. See below.

    gropts(graph_options) specifies default options to be passed through to texdoc
        graph. See below. Updating gropts() in repeated calls to texdoc init will
        replace the option as a whole.

        +-----------------+
    ----+ Filenames/paths +----------------------------------------------------------

    [no]logdir[(path)] specifies where to store the Stata output log files. The
        default is nologdir, in which case the log files are stored in the same
        directory as the LaTeX document, using the name of the LaTeX document as a
        prefix for the names of the log files; also see the prefix() option. Option
        logdir without argument causes the log files to be stored in a subdirectory
        with the name of the LaTeX document. Option logdir(path) causes the log files
        to be stored in subdirectory path, where path is a relative path starting
        from the folder of the LaTeX document.

    grdir(path) specifies an alternative subdirectory to be used by texdoc graph for
        storing the graph files, where path is a relative path starting from the
        folder of the LaTeX document. The default is to store the graphs in the same
        directory as the log files.

    [no]prefix[(prefix)] specifies a prefix for the automatic names of the Stata
        output log files and graphs. The names are constructed as "prefix#", where #
        is a counter (i.e., 1, 2, 3, etc.). Option noprefix omits the prefix; option
        prefix without argument causes "basename_" to be used as prefix, where
        basename is the name of the LaTeX document (without path); option
        prefix(prefix) causes prefix to be used as prefix.  The default prefix is
        empty if logdir or logdir(path) is specified; otherwise the default prefix is
        equal to "basename_".  Furthermore, the prefix will be ignored if a custom
        name is provided when calling texdoc stlog. The suffix of the physical log
        files on disk is always ".log.tex".

    [no]stpath[(path)] specifies how the path for including log files and graphs in
        the LaTeX document is to be constructed (i.e. the path used in the \input{}
        statements etc.; stpath() has no effect on where the log files and graphs are
        stored in the file system). If stpath is specified without argument, then the
        path of the LaTeX document (to be precise, the path specified in docname when
        initializing the LaTeX document) is added to the include-path for log files
        and graphs. Alternatively, specify stpath(path) to add a custom path. The
        default is nostpath. Specifying stpath() might be necessary if the LaTeX
        document is itself an input to a master LaTeX file somewhere else in the file
        system.


Options for texdoc append

    substitute(subst) causes the specified substitutions to be applied before copying
        the file into the LaTeX document, where subst is

            from to [from to ...]

        All occurrences of from will be replaced by to. Include from and to in double
        quotes if they contain spaces. For example, to replace "@title" by "My Title"
        and "@author" by "My Name", you could type substitute(@title "My Title"
        @author "My Name").


Options for texdoc stlog

        +------+
    ----+ Main +---------------------------------------------------------------------

    linesize(#) sets the line width (number of characters) to be used in the output
        log. # must be an integer between between 40 and 255. The default is to use
        the current set linesize setting.

    [no]do specifies whether to run the Stata commands. The default is do, i.e. to
        run the commands. Type nodo to skip the commands and not write a new log
        file. nodo is useful if the Stata commands have been run before and did not
        change. For example, specify nodo if all Stata output sections are complete
        and you want to work on the text without having to re-run the Stata commands.
        nodo only works in non-interactive mode, that is, if the do-file is processed
        by texdoc do. Furthermore, note that the automatic names of Stata output
        sections change if the order of Stata output sections changes. That is, nodo
        should only be used as long as the order did not change or if fixed names
        were assigned to the Stata output sections. An exception is if nodo is used
        together with the cmdlog option (see below). In this case the log file will
        always be recreated (as running the commands is not necessary to recreate the
        log file).

    [no]log specifies whether the Stata output is to be logged and included in the
        LaTeX document. The default is log, i.e. to log and include the Stata output.
        If you type nolog, the commands will be run without logging. nolog does not
        appear to be particularly useful as you could simply include the
        corresponding Stata commands in the do-file without using texdoc stlog.
        However, nolog may be helpful in combination with the nodo option. It
        provides a way to include unlogged commands in the do-file that will not be
        executed if nodo is specified.

    [no]cmdlog specifies whether to print a plain copy of the commands instead of
        using a Stata output log. The default is nocmdlog, i.e. to include a Stata
        output log. If you type cmdlog then only a copy of the commands without
        output will be included (note that the commands will still be executed; add
        the nodo option if you want to skip running the commands). cmdlog is similar
        to nooutput. A difference is that nooutput prints ". " at the beginning of
        each command whereas cmdlog displays a plain copy of the commands.
        Furthermore, cmdlog can be combined with nodo to include a copy of the
        commands without executing the commands. cmdlog is not allowed with the
        colon-form of texdoc stlog.

    [no]verbatim specifies whether the command log will be processed by log texman.
        This is only relevant if cmdlog has been specified. The default is
        noverbatim, i.e. to processes the command log by log texman and use the
        "stlog" environment in LaTeX. If you type verbatim then log texman will be
        skipped and the "stverbatim" environment will be used. Unless hardcode is
        specified, the log file will be included in the LaTeX document using command
        \verbatiminput{}, which requires \usepackage{verbatim} in the preamble of the
        LaTeX document.

        +----------+
    ----+ Contents +-----------------------------------------------------------------

    [no]output specifies whether to suppress command output in the log. The default
        is output, i.e. to display the output. If nooutput is specified, set output
        inform is applied before running the commands and, after closing the log, set
        output proc is applied to turn output back on (set output). nooutput has no
        effect if cmdlog is specified. Furthermore, nooutput has no effect if
        specified with the using-form or the colon-form of texdoc stlog.

    [no]matastrip specifies whether to strip Mata opening and ending commands from
        the Stata output. The default is nomatastrip, i.e. to retain the Mata opening
        and ending commands. If you type matastrip, the mata or mata: command
        invoking Mata and the subsequent end command exiting Mata will be removed
        from the log. matastrip only has an effect if the Mata opening command is the
        first command in the output section.

    [no]cmdstrip specifies whether to strip command lines from the Stata output. The
        default is nocmdstrip, i.e. to retain the command lines. Specify cmdstrip to
        delete the command lines. Specifically, all lines starting with ". " (or ": "
        in Mata) and subsequent lines starting with "> " will be removed. cmdstrip
        has no effect if cmdlog is specified.

    [no]lbstrip specifies whether to strip line break comments from command lines in
        the Stata output. The default is nolbstrip, i.e. not to strip the line break
        comments. Specify lbstrip to delete the line break comments. Specifically, "
        ///..." at the end of command lines will be removed.

    [no]gtstrip specifies whether to strip continuation symbols from command lines in
        the Stata output. The default is nogtstrip, i.e. not to strip the
        continuation symbols. Specify gtstrip to delete the continuation symbols.
        Specifically, "> " at the beginning of command lines that were broken by a
        line break comment will be replaced by white space.

    [no]ltrim specifies whether to remove indentation of commands (i.e. whether to
        remove white space on the left of commands) before running the commands and
        creating the log. The default is ltrim, that is, to remove indentation. The
        amount of white space to be removed is determined by the minimum indentation
        in the block of commands. ltrim has no effect on commands called from an
        external do-file by texdoc stlog using.

        +--------------+
    ----+ Highlighting +-------------------------------------------------------------

    alert(strlist) adds the \alert{} command to all occurrences of the specified
        strings, where strlist is

            string [string ...]

        Enclose string in double quotes if it contains blanks; use compound double
        quotes if it contains double quotes.

    tag(matchlist) applies custom tags to all occurrences of the specified strings,
        where matchlist is

            strlist = begin end [ strlist = begin end ... ]

        and strlist is

            string [string ...]

        strlist specifies the strings to be tagged, begin specifies the start tag,
        end specifies the end tag. Enclose an element in double quotes if it contains
        blanks; use compound double quotes if the element contains double quotes.

        +-----------+
    ----+ Technical +----------------------------------------------------------------

    [no]hardcode specifies whether the Stata output is copied into the LaTeX
        document. The default is nohardcode, i.e. to include a link to the log file
        using an \input{} statement in the LaTeX document. If hardcode is specified,
        the log file will be copied directly into the LaTeX document.

    [no]keep specifies whether the external log file will be kept.  This is only
        relevant if hardcode has been specified. The default is keep, i.e. to keep
        the log file so that nodo can be applied later on. Type nokeep if you want to
        erase the external log file.

    [no]custom specifies whether to use custom code to include the log file in the
        LaTeX document. The default is nocustom, i.e. to use standard code to include
        the log. Specify custom if you want to skip the standard code and take care
        of including the log yourself.

    [no]certify specifies whether to compare the current results to the previous
        version of the log file (if a previous version exists). The default is
        nocertify. Specify certify if you want to confirm that the output did not
        change. In case of a difference, texdoc will stop execution and display an
        error message. certify has no effect if nolog or cmdlog is specified.

    nostop allows continuing execution even if an error occurs. Use the nostop option
        if you want to log output from a command that returns error. The nostop
        option is only allowed with texdoc stlog using.


Options for texdoc graph

        +------+
    ----+ Main +---------------------------------------------------------------------

    as(fileformats) sets the output format(s). The default is as(pdf). See help graph
        export for available formats. Multiple formats may be specified, e.g. as(pdf
        eps), in which case texdoc graph will create multiple graph files.

    name(name) specifies the name of the graph window to be exported. The default is
        to export the topmost graph.

    override_options are format-dependent options to modify how the graph is
        converted. See help graph export for details.

        +-------------+
    ----+ Environment +--------------------------------------------------------------

    [no]center specifies whether to center the graph horizontally in the LaTeX
        document. The default is center.

    [no]figure[(args)] specifies whether to include the graph in a (floating) figure
        environment. The default is nofigure. Specify figure(args) to provide
        arguments to be passed through to the figure environment (as in
        \begin{figure}[args]).

    caption(string) provides a caption for the figure. caption() implies figure
        (unless nofigure is specified).

    label(string) provides a cross-reference label for the figure. label() implies
        figure (unless nofigure is specified).

    cabove or cbelow specify whether the caption is printed above or below the
        figure. Only one of cabove and cbelow is allowed. cbelow is the default.

        +-----------------+
    ----+ Include command +----------------------------------------------------------

    optagrs(args) specifies optional arguments to be passed through to
        \includegraphics (as in \includegraphics[args]{filename}) or to \epsfig (as
        in \epsfig{file=filename,args}).

    [no]suffix specifies whether to type the file suffix in \includegraphics or
        \epsfig. If only one output format is specified in as(), the default is to
        type the file suffix. If multiple output formats are specified in as(), the
        default is to omit the suffix. If option suffix is specified with multiple
        output formats, the suffix is determined by the first output format.

    [no]epsfig specifies whether to use \epsfig instead of \includegraphics to
        include the graph in the LaTeX document. The default is noepsfig, i.e. to use
        \includegraphics. Option epsfig implies as(eps) (unless specified otherwise).

    [no]custom specifies whether to use custom code to include the graph in the LaTeX
        document. The default is nocustom, in which case texdoc graph writes code to
        the LaTeX document to include the graph. Specify custom if you want to skip
        the standard code and take care of including the graph yourself.


Options for texdoc strip

    replace allows overwriting an existing file.

    append appends results to an existing file.


Examples

    Basic example
    Graphs
    Output-omitted tag
    Further examples

        +---------------+
    ----+ Basic example +------------------------------------------------------------

    A typical do-file containing texdoc commands might look as follows:

        --- myexample.texdoc ---
        texdoc init myexample.tex, replace

        /***
        \documentclass{article}
        \usepackage{graphicx}
        \usepackage{stata}
        \begin{document}

        \section{Exercise 1}
        Open the 1978 Automobile Data and summarize the variables.

        ***/

        texdoc stlog
        sysuse auto
        summarize
        texdoc stlog close

        /***

        \section{Exercise 2}
        Run a regression of price on milage and weight.

        ***/

        texdoc stlog
        regress price mpg weight
        texdoc stlog close

        /***

        \end{document}
        ***/
        --- end of file ---

    To process the file, type

        . texdoc do myexample.texdoc
        
    This will create file "myexample.tex" and two Stata output log files,
    "myexample_1.log.tex" and "myexample_2.log.tex", in the same directory. The
    contents of "myexample.tex" will be:

        --- myexample.tex ---
        \documentclass{article}
        \usepackage{graphicx}
        \usepackage{stata}
        \begin{document}

        \section{Exercise 1}
        Open the 1978 Automobile Data and summarize the variables.

        \begin{stlog}\input{myexample_1.log.tex}\end{stlog}

        \section{Exercise 2}
        Run a regression of price on milage and weight.

        \begin{stlog}\input{myexample_2.log.tex}\end{stlog}

        \end{document}
        --- end of file ---

        +--------+
    ----+ Graphs +-------------------------------------------------------------------

    To include a graph along with the Stata output, you could add
    \usepackage{graphicx} to the preamble (as above) and type:

        /***
        \section{Exercise 3}
        Draw a scatter plot of price by milage.

        ***/

        texdoc stlog
        scatter price mpg
        texdoc stlog close
        texdoc graph

    This would create file "myexample_3.pdf" and insert the following code in the
    LaTeX document:

        \section{Exercise 3}
        Draw a scatter plot of price by milage.

        \begin{stlog}\input{myexample_3.log.tex}\end{stlog}
        \begin{center}
            \includegraphics{myexample_3}
        \end{center}

    If you only want to display the graph but not the log file, add the nolog option
    to texdoc stlog. Furthermore, to place the graph in a figure environment, you
    could type

        texdoc stlog, nolog
        scatter price mpg
        texdoc stlog close
        texdoc graph, figure caption(Scatter plot of price against mpg) label(figure1)

    which results in:

        \begin{figure}
            \centering
            \includegraphics{myexample_4}
            \caption{Scatter plot of price against mpg}
            \label{figure1}
        \end{figure}

    The figure option is not strictly required in the example since caption() and
    label() imply figure.

        +--------------------+
    ----+ Output-omitted tag +-------------------------------------------------------

    To suppress the output of a command in a Stata output section and add an "(output
    omitted)" message use the texdoc stlog oom command. Example:

        texdoc stlog
        sysuse auto
        texdoc stlog oom regress price mpg weight
        predict r, residuals
        summarize r
        texdoc stlog close

    "texdoc stlog oom " will be removed from the output and the results from regress
    will be replaced by "\oom", the LaTeX command from the "stata" package to create
    the "(output omitted)" message. You can also code

        texdoc stlog oom ///
        regress price mpg weight

    so that the full line width is available for the regress command. "texdoc stlog
    oom ///" and the line break will be removed from the output. To be precise texdoc
    stlog oom assumes the Stata command to start at the next non-blank character
    after oom that is not part of a comment; everything up to that point will be
    removed.

        +------------------+
    ----+ Further examples +---------------------------------------------------------

    For further examples see texdoc's website at 
    http://repec.sowi.unibe.ch/stata/texdoc, the working paper, or the Stata Journal
    article.


Remarks

    texdoc substitute
    texdoc local
    Special characters
    Limitations
    Global macros

        +-------------------+
    ----+ texdoc substitute +--------------------------------------------------------

    After the output document has been initialized, the texdoc substitute command can
    be used to define text substitutions that will be applied to all subsequent /*tex
    tex*/ or /*** ***/ blocks. For example, type

        texdoc substitute "some text" "SOME TEXT" "more text" "MORE TEXT"

    to replace all instances of "some text" by "SOME TEXT" and all instances of "more
    text" by "MORE TEXT". To change the substitution definitions in a later part of
    the document, specify texdoc substitute again with new definitions. To add
    definitions to the existing definitions, specify texdoc substitute with the add
    option. To deactivate the substitutions, specify texdoc substitute without
    arguments.

        +--------------+
    ----+ texdoc local +-------------------------------------------------------------

    The texdoc local command can be used to define local macros that will be backed
    up on disk. It may only be applied within or after a texdoc stlog section. The
    locals will be backed up in a library that has the same name as the Stata output
    section (using file suffix ".stloc"). Each output section has its own library, so
    that the names of the locals can be reused between sections. The syntax of texdoc
    local is the same as the syntax of Stata's regular local command; see help local.

    Use the texdoc local command if you want to include results from an output
    section in the text body. texdoc local provides a way to store the elements you
    want to include in your text so that they are still available in later runs when
    you suppress computations using the nodo option. The local macros defined by
    texdoc local will be expanded in subsequent /*tex tex*/ or /*** ***/ blocks up
    until the next texdoc stlog command. Alternatively, you may use texdoc write to
    write the locals to the output document (there is a slight difference between the
    two approaches: expansion in /*tex tex*/ and /*** ***/ blocks is based on the
    locals as stored in the library file; texdoc write uses the current values of the
    locals). For example, to cite the point estimate and standard error of a
    regression coefficient, you could type:

        texdoc stlog
        regress y x1 x2 ...
        texdoc stlog close
        texdoc local b = strofreal(_b[x1], "%9.3f")
        texdoc local se = strofreal(_se[x1], "%9.3f")

        /*** As can be seen in the output above, the estimate for the effect
        of x1 on y is equal to `b' (with a standard error of `se'). ***/

    Alternatively, you could also type:

        texdoc write As can be seen in the output above, the estimate for
        texdoc write the effect of x1 on y is equal to `b' (with a standard
        texdoc write error of `se').

        +--------------------+
    ----+ Special characters +-------------------------------------------------------

    The $ character is used for global macro expansion in Stata. If you use the
    texdoc write command to write LaTeX code containing $ math delimiters, type \$
    instead of $. For example, type

        . texdoc write This is an inline equation: \$y = x^2\$

    An alternative is to abandon $ and use \( and \) as math delimiters. That is,
    type

        . texdoc write This is an inline equation: \(y = x^2\)

    No such precautions are required if you use the /*tex tex*/ delimiter structure,
    since in this case an exact copy of the specified code is written to the LaTeX
    document.

        +-------------+
    ----+ Limitations +--------------------------------------------------------------

    texdoc tries to create missing subdirectories using Mata's mkdir() function.
    Usually, this only works if all intermediate directories leading to the target
    subdirectory already exist. If mkdir() fails, you will need to create the
    required directories manually prior to running texdoc.

    texdoc stlog cannot be nested. Furthermore, do not use texdoc do or texdoc init
    within a texdoc stlog section.

    When processing a do-file, texdoc do does not parse the contents of do-files that
    may be called from the main do-file using the do command. As a consequence, for
    example, /*tex tex*/ blocks in such a file will be ignored and some of the texdoc
    options will not work. However, you can use texdoc do to include such do-files
    (i.e. texdoc do can be nested).

    In general, texdoc commands should always start on a new line with texdoc being
    the first (non-comment) word on the line (for example, do not use quietly texdoc
    ... or similar).

    texdoc do only provides limited support for the semicolon command delimiter (see 
    #delimit). The semicolon command delimiter should work as expected as long as it
    is turned on and off between /*tex tex*/ blocks and between texdoc commands. Do
    not use semicolons to delimit texdoc commands.

        +---------------+
    ----+ Global macros +------------------------------------------------------------

    texdoc maintains a number of global macros for communication between texdoc
    commands. Do not change or erase these global macros while working with texdoc.

    Global macros maintained by texdoc do (will be cleared when texdoc do
    terminates):  TeXdoc_dofile, TeXdoc_do_snippets, TeXdoc_do_replace,
    TeXdoc_do_append, TeXdoc_do_logall, TeXdoc_do_linesize, TeXdoc_do_nodo,
    TeXdoc_do_nolog, TeXdoc_do_cmdlog, TeXdoc_do_verbatim, TeXdoc_do_nooutput,
    TeXdoc_do_matastrip, TeXdoc_do_cmdstrip, TeXdoc_do_lbstrip, TeXdoc_do_gtstrip,
    TeXdoc_do_noltrim, TeXdoc_do_alert, TeXdoc_do_tag, TeXdoc_do_hardcode,
    TeXdoc_do_nokeep, TeXdoc_do_custom, TeXdoc_do_certify, TeXdoc_do_gropts,
    TeXdoc_do_logdir, TeXdoc_do_logdir2, TeXdoc_do_grdir, TeXdoc_do_noprefix,
    TeXdoc_do_prefix, TeXdoc_do_prefix2, TeXdoc_do_stpath, TeXdoc_do_stpath2,

    Global macros maintained by texdoc init (will be cleared by texdoc close):
    TeXdoc_docname, TeXdoc_docname0, TeXdoc_basename, TeXdoc_path, TeXdoc_path0,
    TeXdoc_stcounter, TeXdoc_logall, TeXdoc_linesize, TeXdoc_nodo, TeXdoc_nolog,
    TeXdoc_cmdlog, TeXdoc_verbatim, TeXdoc_nooutput, TeXdoc_matastrip,
    TeXdoc_cmdstrip, TeXdoc_lbstrip, TeXdoc_gtstrip, TeXdoc_noltrim, TeXdoc_alert,
    TeXdoc_tag, TeXdoc_hardcode, TeXdoc_nokeep, TeXdoc_custom, TeXdoc_certify,
    TeXdoc_gropts, TeXdoc_logdir, TeXdoc_grdir, TeXdoc_prefix, TeXdoc_prefix0,
    TeXdoc_stpath

    Global macro maintained by texdoc substitute (will be cleared by texdoc close):
    TeXdoc_substitute

    Global macros maintained by texdoc stlog (will be cleared by texdoc close):
    TeXdoc_ststatus, TeXdoc_stname, TeXdoc_stname0, TeXdoc_stfilename,
    TeXdoc_stfilename0, TeXdoc_sttexname, TeXdoc_sttexname0, TeXdoc_stgrcounter,
    TeXdoc_stlinesize, TeXdoc_stlinesize0, TeXdoc_stnodo, TeXdoc_stnolog,
    TeXdoc_stcmdlog, TeXdoc_stverbatim, TeXdoc_stnooutput, TeXdoc_stmatastrip,
    TeXdoc_stcmdstrip, TeXdoc_stlbstrip, TeXdoc_stgtstrip, TeXdoc_stnoltrim,
    TeXdoc_stalert, TeXdoc_sttag, TeXdoc_sthardcode, TeXdoc_stnokeep,
    TeXdoc_stcustom, TeXdoc_stcertify

    Global macro maintained by texdoc local (will be cleared by texdoc stlog or
    texdoc close): TeXdoc_stloc

    In addition, texdoc do maintains an external Mata global called
    TeXdoc_do_snippets. Do not modify the contents of this external global. If the
    external global is deleted (e.g. because the processed do-file contains a clear
    all command), texdoc do automatically restores it. The external global will be
    removed when texdoc do terminates.


Stored results

    texdoc init clears s(), and texdoc close stores the following in s():

    Macros       
      s(docname)        name of LaTeX document (including absolute path)
      s(basename)       base name of LaTeX document (excluding path)
      s(path)           (absolute) path of LaTeX document
      s(logall)         logall or empty
      s(linesize)       specified line width or empty
      s(nodo)           nodo or empty
      s(nolog)          nolog or empty
      s(cmdlog)         cmdlog or empty
      s(verbatim)       verbatim or empty
      s(nooutput)       nooutput or empty
      s(matastrip)      matastrip or empty
      s(cmdstrip)       cmdstrip or empty
      s(lbstrip)        lbstrip or empty
      s(gtstrip)        gtstrip or empty
      s(noltrim)        noltrim or empty
      s(alert)          contents of alert() option
      s(tag)            contents of tag() option
      s(hardcode)       hardcode or empty
      s(nokeep)         nokeep or empty
      s(custom)         custom or empty
      s(certify)        certify or empty
      s(gropts)         default graph export options
      s(logdir)         subdirectory used for Stata log files
      s(grdir)          subdirectory used for graphs (if different from s(logdir))
      s(prefix)         prefix for automatic Stata log names
      s(stpath)         include-path to be used for Stata logs in LaTeX document

    texdoc stlog close stores the following in s():

    Macros       
      s(name)           name of the Stata output log, including logdir() path
      s(name0)          s(name) without logdir() path
      s(filename)       name of log file on disk (including absolute path and suffix)
      s(filename0)      s(filename) without suffix
      s(texname)        name of log file with include-path for use in LaTeX document
      s(texname0)       s(texname) without suffix
      s(linesize)       line width used for the output log
      s(indent)         size of indentation
      s(nodo)           nodo or empty
      s(nolog)          nolog or empty
      s(cmdlog)         cmdlog or empty
      s(verbatim)       verbatim or empty
      s(nooutput)       nooutput or empty
      s(matastrip)      matastrip or empty
      s(cmdstrip)       cmdstrip or empty
      s(lbstrip)        lbstrip or empty
      s(gtstrip)        gtstrip or empty
      s(noltrim)        noltrim or empty
      s(alert)          contents of alert() option
      s(tag)            contents of tag() option
      s(hardcode)       hardcode or empty
      s(nokeep)         nokeep or empty
      s(custom)         custom or empty
      s(certify)        certify or empty


References

    Rising, Bill (2008). Reproducible Research: Weaving with Stata. Italian Stata
        Users Group Meeting 2008. Available from 
        http://www.stata.com/meeting/italy08/rising_2008.pdf.


Author

    Ben Jann, University of Bern, ben.jann@soz.unibe.ch

    The append option has been suggested by Jorge Eduardo Pérez. Uli Kohler suggested
    the nostop and gtstrip options.

    Thanks for citing this software in one of the following ways:

        Jann, Ben (2016). Creating LaTeX documents from within Stata using texdoc.
        The Stata Journal 16(2): 245-263.

        Jann, Ben (2015). Creating LaTeX documents from within Stata using texdoc.
        University of Bern Social Sciences Working Papers No. 14. Available from 
        http://ideas.repec.org/p/bss/wpaper/14.html.

        Jann, B. (2009). texdoc: Stata module to create a LaTeX document including
        Stata output. Available from 
        http://ideas.repec.org/c/boc/bocode/s457021.html.


Also see

    Online:  help for file, log; sjlatex (if installed), webdoc (if installed)