ROSALI-SIM/Modules/ado/plus/s/sjlog.hlp

{smcl}
{* *! version 1.0.0  20dec2005}{...}
{cmd:help sjlog}{...}
{right:also see:  {help sjlatex}}
{hline}

{title:Title}

{pstd}
{hi:sjlog} {hline 2} Creating and managing logs for Stata Journal articles


{title:Syntax}

{phang2}
{cmd:sjlog} {it:subcmd} ...


{title:Opening and closing logs}

{phang2}
{cmd:sjlog} {cmd:using} {it:filename}
	[,
	{cmd:append} | {cmd: replace}
	]

{phang2}
{cmd:sjlog} {cmd:close}
	[,
	{cmd:noclean}
	{cmd:no}{cmdab:log:file}
	{cmd:replace}
	{cmd:book}
	]


{title:Logging the results of a do-file}

{phang2}
{cmd:sjlog} {cmd:do} {it:filename}
	[,
	{cmd:clear}
	{cmd:replace}
	{cmd:book}
	{cmd:nostop}
	{cmdab:sav:ing:(}{it:basename}{cmd:)}
	]


{title:Utilities}

{pstd}
Removing unwanted lines from a log.

{phang2}
{cmd:sjlog} {cmd:clean} {it:filename}
	[,
	{cmd:log} |
	{cmd:logclose} |
	{cmd:sjlog} |
	{cmd:sjlogdo}
	]


{pstd}
Copy a file to be included in an Stata Journal article.

{phang2}
{cmd:sjlog} {cmd:type} {it:filename}
	[,
	{cmd:replace}
	{cmd:find}
	{cmd:path(}{it:path}{cmd:)}
	{cmdab:log:file}
	{cmdab:smcl:file}
	]


{pstd}
Split a file name into three parts.

{phang2}
{cmd:sjlog} {cmdab:base:name} {it:filename}
	[,
	{cmdab:d:isplay}
	]


{pstd}
Note that filenames containing spaces should be enclosed in quotes.


{title:Description}

{pstd}
{cmd:sjlog} is a tool for Stata users who are writing documents that contain
Stata output.  It was written to help authors of the Stata Journal.

{phang}
{cmd:sjlog} {cmd:using}/{cmd:close} open and close log files similar to the
log command, see help {help log}.

{phang}
{cmd:sjlog} {cmd:do} logs the output generated by the specified do-file.

{phang}
{cmd:sjlog} {cmd:clean} removes lines of text from {cmd:smcl} files.  This
subcommand was added to facilitate the removal of the header and footer
generated by the {cmd:log} command, as well as the command that closed the
log.

{phang}
{cmd:sjlog} {cmd:type} makes a copy of a file with some substitutions to make
the file is suitable for inclusion in a TeX or LaTeX document.

{phang}
This subroutine facilitates the inclusion of do-files and ado-files in Stata
Journal articles without having to manually maintain duplicate copies of the
same file.

{phang}
{cmd:sjlog} {cmd:type} can also be used to copy {cmd:smcl} files to a format
suitable for inclusion in a TeX or LaTeX document provided you also have
stata.sty, a LaTeX package written for the Stata Journal.  For more
information about LaTeX packages written for the Stata Journal, see help
{help sjlatex}.

{phang}
{cmd:sjlog} {cmd:basename} is something of a combination of the UNIX commands
{bf:basename} and {bf:dirname}.  It simply splits the specified file into
three distinct parts:

{pmore}
1. the directory path (e.g. {cmd:/work/}, {cmd:C:\work\}){break}
2. the suffix (e.g. {cmd:.do}, {cmd:.log}, {cmd:.smcl}){break}
3. the basename (what is left over from 1 and 2)

{phang}
The {cmd:display} option causes {cmd:sjlog} {cmd:basename} to display the
results.


{title:Options for {cmd:sjlog} {cmd:using}/{cmd:close}/{cmd:do}}

{phang}
{cmd:append} ({cmd:sjlog} {cmd:using} only) allows the output to be appended
onto the end of an already existing file.  See the {cmd:append} option in help
{help log}.

{phang}
{cmd:replace} (for all {cmd:sjlog} subroutines) indicates that exiting
{it:filename} (with a {cmd:.smcl}, {cmd:.log}, or {cmd:.log.tex} suffix) will
be overwritten.

{phang}
{cmd:noclean} ({cmd:sjlog} {cmd:close} only) prevents {cmd:sjlog} from
"cleaning" the {cmd:smcl} log before generating the plain text and TeX
version.

{phang}
{cmd:clear} ({cmd:sjlog} {cmd:do} only) causes {cmd:sjlog} to run
"{cmd}program drop _all{reset}" prior to running "{cmd:do} {it:filename}".

{phang}
{cmd:book} ({cmd:sjlog} {cmd:close}/{cmd:do} only) causes {cmd:sjlog} to use
special escape characters in the generated TeX file.  This option is no longer
necessary, but was added to facilitate maintenance of legacy documents that
used the LaTeX listings environment to display Stata logs.

{phang}
{cmd:nostop} ({cmd:sjlog} {cmd:do} only) allows the do-file to continue
executing even if an error occurs.

{phang}
{cmd:saving(}{it:basename}{cmd:)} ({cmd:sjlog} {cmd:do} only) allows for the
logs to be saved to {it:basename}.smcl, {it:basename}.log, and
{it:basename}.log.tex, instead of using the 'basename' of the do-file.


{title:Options for {cmd:sjlog} {cmd:clean}}

{phang}
{cmd:log} (default) indicates that {it:filename} was created by {cmd:log}
{cmd:using} and {cmd:log} {cmd:close}.  This results in the removal of the log
header and footer created by the {cmd:log} command (if they exist), as well as
the removal of the last executed command (and the preceding blank) if it is:

{pmore2}
{cmd}. log close{reset}

{phang}
{cmd:logclose} indicates that {it:filename} was created by {cmd:log}
{cmd:using} and {cmd:logclose}.  This results in the removal of the log
header and footer created by the {cmd:log} command (if they exist), as well as
the removal of the last executed command (and the preceding blank) if it is:

{pmore2}
{cmd}. logclose{reset}

{phang}
{cmd:sjlog} indicates that {it:filename} was created by {cmd:sjlog}
{cmd:using} and {cmd:sjlog} {cmd:close}.  This results in the removal of the
last executed command (and the preceding blank) if it is:

{pmore2}
{cmd}. sjlog close{reset}

{phang}
{cmd:sjlogdo} indicates that {it:filename} was created by {cmd:sjlog}
{cmd:do}.  This results in the removal of the last line of output (and the
preceding blank) if it is:

{pmore2}
{cmd}end of do-file{reset}


{title:Options for {cmd:sjlog} {cmd:type}}

{phang}
{cmd:find} indicates that {it:filename} is somewhere on the ado path.  This
option requires the {cmd:findfile} command introduced in Stata 8, see help
{help findfile}.

{phang}
{cmd:path()} specifies the path over which {cmd:findfile} is to search, see
the {cmd:path()} option description in help {help findfile}.

{phang}
{cmd:logfile} specifies that a plain text file also be created.

{phang}
{cmd:smclfile} specifies that a SMCL file also be created.


{title:Details: generating logs}

{pstd}
The logged output will be saved in three formats:

{phang}
1. The plain text log will have a {cmd:.log} suffix.
{break}
2. The smcl log will be saved with a {cmd:.smcl} suffix.
{break}
3. The TeX log will have a {cmd:.log.tex} suffix.

{pstd}
The TeX log utilizes some tailored TeX macros defined in stata.sty, a LaTeX
package designed for the Stata Journal.

{pstd}
Logs can be generated in one of two ways:

{phang}
(1) {cmd:sjlog} {cmd:using} {it:filename} turns Stata's logging on, and saves
the output to {it:filename}.

{pmore2}
It is recommended that {it:filename} not have a suffix; in any case, an
appropriate suffix will be supplied according to the above list.

{phang2}
{cmd:sjlog} {cmd:close} closes the current log.

{phang}
(2) {cmd:sjlog} {cmd:do} {it:filename} is almost exactly like running the
following commands:

{pmore2}
{cmd}
. sjlog using {it:filename}
{break}
. do {it:filename}.do
{break}
. sjlog close
{reset}

{phang}
where {it:filename} is the base name (having no suffix) of a Stata do-file,
except the command "{cmd}do {it:filename}.do{reset}" is removed from the log.

{pstd}
When you begin logging, {cmd:sjlog} will first close the current log (if there
is one) before opening a new log with the given options.  Also the {help more}
and {help trace} settings are turned off.


{title:Details: copying files}

{pstd}
{cmd:sjlog} {cmd:type} is almost exactly like running the following commands:

{pmore2}
{cmd}
. sjlog using {it:filename}.tex
{break}
. type {it:filename}
{break}
. sjlog close
{reset}

{title:Saved results}

{pstd}
{cmd:sjlog} {cmd:close} saves in {cmd:r()}:

        Macros
            {cmd:r(fn)}     name of the TeX log


{pstd}
{cmd:sjlog} {cmd:clean} saves in {cmd:r()}:

        Macros
            {cmd:r(fn)}     {it:filename}
            {cmd:r(fnbak)}  {it:filename}.bak, backup copy of {it:filename}


{pstd}
{cmd:sjlog} {cmd:type} saves in {cmd:r()}:

        Macros
            {cmd:r(fn)}     {it:filename}.tex, copy of {it:filename}


{pstd}
{cmd:sjlog} {cmd:basename} saves in {cmd:r()}:

        Macros
            {cmd:r(fn)}    {it:filename}
            {cmd:r(dir)}    directory path of {it:filename}
            {cmd:r(base)}   basename of {it:filename}
            {cmd:r(ext)}    extension suffix of {it:filename}


{title:Also see}

{psee}
Manual:
{hi:[R] log},
{hi:[P] program},
{hi:[P] smcl},
{hi:[R] translate}

{p 4 13 2}
Online:
{help log},
{help program},
{help smcl},
{help translate}
{p_end}