*! help file for version 2.5 of lineno2.ado by Mead Over 21Jul2022

help for lineno2Version 2.5 21Jul2022

Title

lineno2 -- Number the lines of any ASCII or text file,
such as a Stata log file, smcl file, do file or ado file and optionally
also generate a PDF file.

Syntax

lineno2
using
filename
,
saving(newfilename)
[options]

Options

main options

filename The name of the source file. Specify the full name of the file
including its path and extension. Stata file extensions include,
for example, ".smcl", ".log", ".txt", ".do" or ".ado".

saving(newfilename) Provide the name of the new version of filename
to be created by lineno2 with line numbers.
Specify the full name of the new file including its path and extension.
The user should typically specify newfilename to be different from
the file's original name but with the same file extension. A required option.

start(integer) Start line numbering with this integer.
Can be negative. Default is to start line numbering at 1.

dofile Attempt to retain the functionality of a Stata -do- file or
-ado- file by bracketing the line number with /* and */. Numbered file may
require additional editing before it runs.

replace If newfilename already exists, replace it.

PDF options

pdf Create and save a PDF file as well as the file
specified in option saving(newfilename). The PDF file
will have the same name as the newfilename, but with a
-pdf- extension.

color Reproduce the colors from the source file in the created PDF file.

fontsize(real) Specify the size of the font used in the PDF file. The default is fontsize(7).

lmargin(real) Specify the size of the left margin used in the PDF file. The default is lmargin(0.5).

rmargin(real) Specify the size of the right margin used in the PDF file. The default is rmargin(0.5).

tmargin(real) Specify the size of the top margin used in the PDF file. The default is tmargin(0.5).

bmargin(real) Specify the size of the bottom margin used in the PDF file. The default is bmargin(0.5).

landscape Generate the PDF file in landscape rather than portrait orientation. The default is portrait orientation.

headertext(string) Specify the header text to appear on the top of each page of the PDF file. The default is no header text.

logo(on|off) Specify whether the Stata logo appears on the PDF file. The default is logo(on).

len(real) Specify the maximum length of the path-filename for the PDF file in characters. The default is len(79).

Text options

txt Create and save a text version of the log file as well as the file
specified in option saving(newfilename). The text file
will have the same name as the newfilename, but with a
-txt- extension.

log The option log has the same effect as the option txt
but, in Stata 16.1 and prior, removes Stata's logo from the beginning
of the file and starts each line in the first rather than the sixth column.
The text file will have the same name as the newfilename,
but with a -txt- extension.

Description

This program lineno2 adds line numbers to Stata -log- files, -do- files,
-ado- files
or to any text file. The Stata files with added line numbers typically retain their functionality.

Remarks

Line numbers are
useful to allow collaborating researchers to reference parts of a long
Stata log file, do file or ado file. As Nick Cox pointed out in the Statalist
in which he posted his code for lineno, many text editors
including Stata's own doedit display line numbers.
But in versions up to and including Stata 16.1,
neither Stata's log command nor its view command offers a
line-numbering option. Stata's translate command can number the lines
of a Stata log file when it converts it to a text or PDF file. But some
users may prefer line numbers within Stata's viewer. lineno2
serves this purpose.

This program builds on Cox's code to number the lines of any text (or ASCII) file,
including Stata's two types of log files. It will be useful to users who
appreciate the advantages of Stata's formatted log files stored in the
smcl format, the default log format. After creating and closing
a log file, the user can issue the lineno2 command to process it
so that the processed file can be viewed with line numbers by Stata's viewer.

Line numbers might also be useful at the beginning of each line
of a Stata do or ado file if they do not prevent it from working.
With the dofile option, this program embeds the line numbers
in Stata's /* # */ comment brackets. For most lines of
a do or ado file, this procedure will protect the code's functionality,
but some editing of the processed file may be required.

Hint: While lineno2 processes most smcl files without
problems, the smcl formatted output of some Stata commands can fool
lineno2. For example, lineno2 sometimes distorts tables
such as those produced by the command hausman. And lineno2
adds extra line numbers to the output
of Stata's margins command. (For the margins command,
this annoyance can be avoided by including
vsquish among the margins options.)

Warning: With the replace option, lineno2 is willing to
overwrite the target output file, including for example the user's original -do- or -log- file.
However, since the file produced by lineno2 might be unsatisfactory,
the user is advised to specify a filename in option saving(newfilename)
which is different from, and therefore does not overwrite, the source file.

The pdf option simply executes Stata's translate command on
the newly created file with numbered lines, using the default options
fontsize(7), lmargin(0.5), rmargin(0.5), ltmargin(0.5) and bmargin(0.5).
Change the font size or margins by specifying these options in the lineno2 command line.
Specify the color option
to preserve a smcl file's colors in the PDF file. If the PDF
file fails to save or is saved to the wrong locaton, try specifying the len(real) option
with a larger number of characters than the default of 79.

The txt and log options invoke translate to
produce text versions of the SMCL file, saving the user from making an additional call to translate.

The landscape option is only relevant when pdf is specified.
This option improves readability of the PDF file when
Stata output is wider than 80 columns.

Example 1: Produce a SMCL formatted log file with line numbers

. preserve

Open a Stata log file using the smcl format.

. log using autosmcllog, smcl replace

. sysuse auto, clear

. describe

< output omitted >

. * Now run a regression

. regress price mpg headroom weight i.foreign i.rep78

< output omitted >

. log close

Here's the file just created in -smcl- format.

. dir autosmcllog*.*
5.7k 5/20/21 16:00 autosmcllog.smcl

Use -lineno2- to process the just-created log file.

. lineno2 using autosmcllog.smcl, saving(autosmcllog_w_line_nmbrs.smcl) replace

Now we have both the plain and the numbered log files in smcl format.
Adding line numbers
to the smcl file increases its size by about 25% in this case.

. dir autosmcllog*.*
5.7k 5/20/21 16:00 autosmcllog.smcl
7.4k 5/20/21 16:06 autosmcllog_w_line_nmbrs.smcl

Use Stata's viewer to view the original log file and the newly created
version of the log file with line numbers.

. view autosmcllog.smcl
. view autosmcllog_w_line_nmbrs.smcl

Example 2: Produce a PDF version of the log file with line numbers

Execute -lineno2- again on the original log file, this time adding the
pdf option. With this option -lineno2- produces two additional files,
one named autosmcllog_w_line_nmbrs.smcl and one named
autosmcllog_w_line_nmbrs.pdf.

. lineno2 using autosmcllog.smcl, saving(autosmcllog_w_line_nmbrs.smcl) pdf color replace

Now we have both the plain and the numbered log files in smcl format,
plus the PDF file. The
line-numbered PDF file occupies 15 times more space than the line-numbered
smcl file. With the color option, the colors in the smcl file
are reproduced in the PDF file

. dir autosmcllog*.*
5.7k 5/20/21 16:00 autosmcllog.smcl
117.7k 5/20/21 16:14 autosmcllog_w_line_nmbrs.pdf
7.4k 5/20/21 16:14 autosmcllog_w_line_nmbrs.smcl

Use your computer's PDF viewer to view the PDF file.
Then clean up by erasing all three log files.

. erase autosmcllog.smcl

. erase autosmcllog_w_line_nmbrs.smcl

. erase autosmcllog_w_line_nmbrs.pdf

. restore

Authors

Mead Over,
Center for Global Development, Washington, DC 20036 USA. Email:
MOver@CGDev.Org if you observe any
problems.

Reference

This program is an enhanced version of Nick Cox's lineno ado file
published
November 18, 2011 on Stata's forum.