*! version 1.0 30 Apr 2018

Title

svtxt -- save text, chapter and sections to log, without additonal logging noise

Syntax

svtxt
logname [, underline line chapter section]
:
text

where:

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

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

Main
underline underlines the text.

line prints a demarcation line before and after the text.

chapter places a numbered chapter marker in the logfile.
The input text will be the chapter name.

section places a numbered section marker in the logfile.
The input text will be the section name.

svtxt does not support by.

Description

svtxt is intented for making dynamic texts and
longer notes for output stored with the svcom.

svtxt is closely related to svcom, and it works in the same way,
although only on text.
It stores text in a rigorously maintained logfile without the need for
log on - log off commands, and especially without the extra text
those commands will produce on there own, if not embeded in quietly{ ... }

svtxt can also utillise its capabillity to store text
to part the logfile in sections and chapters.

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,
then remember to specify logname every time you are changing log. Logname is
reused by both svcom and svtxt.

Main

underline Underlines the text in the output. The same effect can be achieved by using
{ul:} or the {ul on} - {ul off}.
Using the underline option can sometimes be faster.

line places a demarcation line before and after the output text,
just as seen with svcom. With svtxt the default is no line.

chapter places a consecutive numbered chapter mark in the logfile.
Probably most interesting in long logfiles
or with major shifts in the focus of analysis within the same logfile.
In case you prefer the chapter named in your own language, it can easily be changed in the ado.

section places a consecutively numbered section mark in the logfile.
The number includes both the chapter number and the section number.
In case section is used before first chapter, then a warning is issued,
and the section is numbered only with the consecutive section number.
The warning is not included in the restricted logfile,
but is printet in the result window and
recorded in an ordinary running log - see third example.

Examples

The basic use of svtxt is examplified below.

example do-file content

* Display of basic functionality of svtxt
* 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
tab foreign
display "The above command and this text will not show in the log"

svtxt results : "Only this short text and .... "

svtxt , underline: "this slightly longer text will appear in the log"

svtxt , line: "The demarcation line can sometimes find a use."

svtxt : Quotations marks are not nessecary ///
and it is possible to write longer pragraphs.

log close results

view one-log.smcl

* cleaning up
rm one-log.smcl

(click to run)

svtxt can be used to create a 'dynamic text' in the logfil.

example do-file content

* Display of dynamic text functionality of svtxt
* 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

svtxt results : Even if a calculation is not shown in the logfile, ///
you can still cite the values.

sum price
svtxt results : Like the mean of summarized price is calculated to `r(mean)'
svtxt :But the high numbers of digtets can be a problem.

* There is one annoyance in the use of svtxt.
* As the text has to be embeded in quotation marks,
* the normal syntax of display format macro "text" does not work.
* Normally you would probably do something like this:

sum price
return list
display %5.1f `r(mean)'

* With svtxt you can either store the result first in a local macro,
* and there include information about precession.
* Or you can use strofreal().

sum price
local price_mean: display %5.1f `r(mean)'

svtxt : Now the mean on `price_mean' is more readable, ///
when the local macro is preajusted.

sum price
svtxt : Instead of local macros you can use the strofreal()-function ///
- e.g. strofreal(`r(mean)',"%4.1f") = `=strofreal(`r(mean)',"%3.1f")'

log close results
view one-log.smcl

* cleaning up
rm one-log.smcl

(click to run)

Example of the chapter and section function is shown here below.
This example requires that svcom is installed.

example do-file content

* Display of chapter and section capabillities of svtxt
* In this display only one log is active
set more off
capture scalar drop sv_chapnum_dvpd
capture scalar drop sv_secnum_dvpd
capture scalar drop sv_chapnumcopy_dvpd

log using main-log.smcl, replace
sysuse auto, clear

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

svtxt results, section : First section - a table

svcom : tab foreign, note(A one-way table) nocommand noline

svtxt : Sorry I forgot to define the chapter first.

svtxt ,chapter: First chapter - AUTO data set

svtxt : This chapter will only draw information from the auto data set.

svtxt ,s: About prices

svcom: tabstat price, by(foreign) s(mean) ///
head(mean price for foreign and domestic cars) ///
noline

svtxt : More text about this section.

svtxt, s: About repair

svcom: tab rep78 foreign, row ///
head(Distribution of repair record between foreign and domestic cars) ///
noline nocommand

svtxt ,c : The bplong dataset

sysuse bplong, clear

svtxt: This chapter concerns fictional blood pressure.

svcom : bysort when agegrp: tabstat bp, by(sex) s(mean p25 p75) ///
headline(Blood pressure before and after treatment) ///
noline nocommand ///
note(Blood pressure for men and women before and after treatment in each age group)

svtxt: Hopefully this gives some idea about how svcom and svtxt work.

log close _all
view main-log.smcl
view one-log.smcl

* cleaning up
rm one-log.smcl
rm main-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 svcom.

Thanks to countless answeres, to me or others, on the statalist for providing indirect help
for this little projekt and other stataproblems.

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

Stored Scalars

Scalars

sv_lognavn_dvpd name of the log

sv_chapnum_dvpd scalar to store current chapter number

sv_secnum_dvpd scalar to store current section number

sv_chapnumcopy_dvpd scalar, deriviat of chapnum,
is used when first chapter is not defined.

Author

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