*! version 1.0 22feb2018 Dennis Lund Hansen dlh@dadlnet.dk

Title

svcom -- save command output and comments to log, without additonal logging noise

Syntax

svcom
logname
:
command
[, command_options headline(txt) notetxt(txt) nocommand noline duplicate permanent_options]

where:

logname is the reference name of the log, specified in log using "path\name", name(logname)

command is the command from which the output derives.

logname
logname only needs to be defined first time either
svcom or svtxt is used

Main
command_options options from the command in focus

headline(txt) displays txt and command as headline above output

notetxt(txt) displays txt as explanatory notes below output

nocommand turn off the inclusion of the command in headline

duplicate duplicates the command as a normal command in the main log-file right before the cleaned version

noline removes the line drawn before and after the output from svcom

Permanent options
nocommandpermanent(on/off) turns nocommand permantly on in the logfile until the off command is given

duplicatepermanent(on/off) turns duplicate permantly on in the logfile until the off command is given

nolinepermanent(on/off) turns noline permantly on in the logfile until the off command is given

by and bysort are not supported by svcom, but can be used as normally
with the command given after the colon.

Description

svcom is intended to make an output file or log file with a more readable and coherent content.

A stata log, if made for documentatation of the work process tends to be large and containing a huge amount of information
about the work-up process and a lot of intermediate information.

This can "disguise" the relevant results and make it tedious to find them, especially in large log files,
where there are a lot of data transformations between results.

Stata is generic, offering the possibility of using muliple logs
where one or more can be turned on/off with the log on - log off commands.
But this places redundant noice of logname and time in the log.
Even if the quietly command is used there will be some extra noise and a tedious amout of extra lines to be writen in the do-file.

Further, the use of log on - log off will erase the content of the r-class,
making it impossible to cite newly performede calcualtions by the use of the local result macro.
This can be handled by more lines of code saving the results in new local macros or the use of svcom.

svcom offers an easy, usable solution to this. Where the logfile can be distributede e.g.
among colleagues in a research group in easily readable form without noise.
This is achivede by a wrapper to normal stata commands, without the need for extra compiling and extra mark up.
Being simple to use, there are certain limitation in the command,
and it is not meant for e.g. writing complete manuscripts.
But can be used for less text burdend standard reports and internal documents
(including specified result output for manuscripts or retrievable reports from a
secure data area where a normal log would be at risk of unintentionally containing unallowed material).

Limits

Graphic output (e.g.: graph or hist), can be used with svcom
but the output is not incorporated in the logfile - just as standard in stata.
If graphic output has to be placed in the logfile consider graphlog,
markdoc or texdoc.

svcom can be used with display and smcl-directives,
but it is not recommend to write longe texts or to use commas,
as this will result in a syntax error,
svtxt is intended to complement svcom when there is a need for a large text output.

Options

Log

logname only needs to be specified the first time or if you change log.
The name is stored and reused. If you are using different logs to store results,
remember to specify logname every time you are changing log. Logname is
reused by both svcom and svtxt.

Main

headline(txt) displays the txt as headline above the output.
Accepts a variety of smcl-directives, including
for line breaks.

notetxt(txt) displays the txt as a note below the output.
Accepts a variety of smcl-directives, including
for line breaks

nocommmand prevents the display of the command in the headline.
Standard is to display the input command.
The combination of not specifying the heading and using the nocommand will be
a complete absence of text before the output.

duplicate one problem with svcom is that it will obscure the input of the command in focus a bit,
as it blends with the options for svcom. Turning on the duplicate option will
allow the command to be displayed and executed as normal,
right before the cleaned input that will be copied in the result log.

noline standard for svcom is to issue a line before the headline and after the notetext.
noline turns this function off.

Permanent options

nocommandpermanent(on/off) same functions as nocommand options above.
If the "on" option is given, command will not be showen in the headline,
until the "off" option is given again.
Default is "off", i.e. command is shown in the headline.

duplicatepermanent(on/off) same function as duplicate above,
turns on duplication mode, but works from the "on"
is specified until the "off" option is specified again. Default is "off", i.e.
not duplication command in the main logfile.

nolinepermanent(on/off) same function as duplicate above,
turns noline mode permanently on, until the "off" option is specified.
Default is "off" i.e. printing line before and after execution of svcom.

Examples

The basic use of svcom is illustrated in this example.
After the colon you type in the command as usual.

example do-file content

* Display of basic functionality in svcom
* In this display only one log is active
set more off

log using one-log.smcl, replace name(results)
log off results
sysuse auto, clear

svcom results : tab rep78

svcom : tab rep78 foreign, row

log close results
view one-log.smcl

* clearning up
rm one-log.smcl

(click to run)

The following example uses headlines and notes to explain the output.
The note and headline accept a variety of smcl commands,
including {break}, {it}
and {ul}.

example do-file content

* Adding text to the logfile
* In this display only one log is active
set more off

log using one-log.smcl, replace name(results)
log off results
sysuse auto, clear

svcom results : tab rep78, headline(First tabel) ///
note(This is a one-way table)

svcom : tab rep78 foreign, row ///
headline(Second table, including row-percentages) ///
notetxt(This is a two-way table, but still a bit meaningless. ///
Please note that the first and second table have short ///
horisontal lines before and after them)

svcom : tab rep78 foreign, row nocommand noline ///
headline(Third table, including row-percentages) ///
notetxt(The lines and the inclusion of the command in the headline ///
can be removed with the use of noline and nocommand)

svcom : proportion rep78, over(foreign) nocommand noline ///
headline(Use of proportion) ///
notetxt(the use of noline can make the output look more coherent, ///
but also a bit more confusing, if you are looking for something particular.)

log close results
view one-log.smcl

* clearning up
rm one-log.smcl

(click to run)

The permanent options work in the same way, only that they turn the option on
or off until the options are changed.

example do-file content

* Adding text to the logfile
* In this display, only one log is active
set more off

log using one-log.smcl, replace name(results)
log off results
sysuse auto, clear

svcom results : tab rep78, headline(First tabel) ///
note(This is a one-way table, made by the command tab rep78. ///
The command in the headline has been removed, ///
but the demarcation lines are still there.) ///
nocommandpermanent(on)

svcom : tab rep78 foreign, ///
headline(Second table) ///
notetxt(This is a two-way table, made by the command tab rep78 foreign. ///
Please note, there is no command in the headline ///
and no line before or after the output.) ///
nolinepermanent(on)

svcom : tab rep78 foreign, row ///
headline(Third table, including row-percentages) ///
notetxt(This table has still no command in the headline and no demarcation line)

svcom : tab foreign, plot ///
notetxt(if "headline()" is empty, this plain output will be the result)

svcom : proportion rep78, over(foreign) ///
headline(Use of proportion) ///
notetxt(Demarcation lines are back) ///
noline(off)

log close results
view one-log.smcl

* cleaning up
rm one-log.smcl

(click to run)

This last example reuses the former one, adding the duplicate option, and
showing both the unfiltered and the restricted log.
It also shows a possible use of the by prefix.

example do-file content

* Adding text to the logfile
* In this display there are two active logs
set more off

log using first-log.smcl, replace
log using second-log.smcl, replace name(results)
log off results
sysuse auto, clear

svcom results : tab rep78, headline(First tabel) ///
note(This is a one-way table, made by the command tab rep78. ///
The command in the headline has been removed, ///
but the demarcation lines are still there.) ///
nocommandpermanent(on) ///
duplicate

svcom : tab rep78 foreign, ///
headline(Second table) ///
notetxt(This is a two-way table, made by the command tab rep78 foreign. ///
Please note, there is no command in the headline ///
and no line before or after the output.) ///
nolinepermanent(on)

svcom : tab rep78 foreign, row ///
headline(Third table, including row-percentages) ///
notetxt(This table has still no command in the headline and no demarcation line)

svcom : tab foreign, plot ///
notetxt(if "headline()" is empty, then this plain output will be the result)

svcom : bysort foreign : tab rep78, plot ///
headline(Use of bysort in combination with svcom) ///
notetxt(Demarcation lines is back) ///
noline(off) ///
duplicate

log close _all
view first-log.smcl
view second-log.smcl

* clearning up
rm first-log.smcl
rm second-log.smcl

(click to run)

Acknowledgements

Thanks to Robert Picard for writing the rangerun_run.ado command and allowing the
reuse of it in the example do-files in this help-file and in the
help-file for svtxt.

Thanks to countless answeres, to me or other, on the statalist for providing indirect help
for this little project and other stata problems.

Thanks Nich Cox, Clyde Schecter and Jens Lauritsen for providing answers
directly relvant for this program.

Stored Scalars

In order to remember the permant options, svcom leaves behind up to four scalars containg
information about logname and settings.

Scalars

sv_lognavn_dvpd name of the log

scalar_nocommand_permanent informaton if nocommand is permanently on or off

scalar_noline_permanent information if noline is permantly on or off

scalar_duplicate_permanent information if duplicate is permanently on or off

Author

Dennis Lund Hansen
MD, PhD-fellow
Odense University Hospital,
Department of Haematology
dlh@dadlnet.dk