Setup initial file structure
This commit is contained in:
351
Modules/ado/plus/s/sjlog.hlp
Normal file
351
Modules/ado/plus/s/sjlog.hlp
Normal file
@ -0,0 +1,351 @@
|
||||
{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}
|
||||
Reference in New Issue
Block a user