{smcl}
{* 24may2004}{...}
{hline}
help for {hi:listp}
{hline}

{title:List values of variables with page breaks}

{p 8 14 2}
{cmdab:listp}
[{it:varlist}]
{cmd:, pagebreak()}
[{it:options}]

{p 4 4 2}
where {it:options} are

{p 8 12 2}
Options affecting style of list:{break}
	{cmdab:t:able} [{cmd:clean}]
{break}
	{cmdab:d:isplay}

{p 8 12 2}
Other options:{break}
	[{cmdab:c:ompress} | {cmdab:noc:ompress}]
	{cmdab:ab:breviate:(}{it:#}{cmd:)}
{break}
	{cmdab:subvar:name}
{break}
	{cmdab:noo:bs}
	{cmdab:abs:olute}
{break}
	{cmdab:div:ider}
	{cmdab:sep:arator:(}{it:#}{cmd:)}
	{cmd:sepby(}{it:varlist}{cmd:)}
{break}
	{cmdab:str:ing:(}{it:#}{cmd:)}
	{cmdab:notr:im}
{break}
	{cmdab:nol:abel}
	{cmd:nodotz}
{break}
	{cmdab:line:size:(}{it:#}{cmd:)}

{p 4 4 2}
The page break ASCII character 12 might not work for all printers.

{p 4 4 2}
{it:varlist} may contain time-series operators; see help {help varlist}.


{title:Description}

{p 4 4 2}
{cmd:listp} displays the values of variables for a specified number of observations and adds a page break after the observations have been displayed.  If no {it:varlist} is specified, the values of all the variables are specified.

{p 4 4 2}
{cmd:listp} can produce two styles of output.  The first, called
{cmd:table} format, looks like this,

	{cmd}. listp make-rep78, pagebreak(4) table
	{txt}
	     {c TLC}{hline 15}{c -}{hline 7}{c -}{hline 5}{c -}{hline 7}{c TRC}
	     {c |} {res}make            price   mpg   rep78 {txt}{c |}
	     {c LT}{hline 15}{c -}{hline 7}{c -}{hline 5}{c -}{hline 7}{c RT}
	  1. {c |} {res}AMC Concord     4,099    22       3 {txt}{c |}
	  2. {c |} {res}AMC Pacer       4,749    17       3 {txt}{c |}
	  3. {c |} {res}AMC Spirit      3,799    22       . {txt}{c |}
	  4. {c |} {res}Buick Century   4,816    20       3 {txt}{c |}
	     {c BLC}{hline 15}{c -}{hline 7}{c -}{hline 5}{c -}{hline 7}{c BRC}

{p 4 4 2}
and the second, called {cmd:display} format, looks like this:

	{cmd}. listp, pagebreak(2) display

	     {txt}{c TLC}{hline 13}{c TT}{hline 7}{c TT}{hline 5}{c TT}{hline 8}{c TT}{hline 11}{c TT}{hline 8}{c TRC}
	  1. {c |} make        {c |} price {c |} mpg {c |} rep78  {c |} headroom  {c |} trunk  {c |}
	     {c |} {res}AMC Concord {txt}{c |} {res}4,099 {txt}{c |} {res} 22 {txt}{c |} {res}    3  {txt}{c |} {res}     2.5  {txt}{c |} {res}   11  {txt}{c |}
	     {c LT}{hline 8}{c TT}{hline 4}{c BT}{hline 3}{c TT}{hline 3}{c BT}{hline 2}{c TT}{hline 2}{c BT}{hline 7}{c TT}{c BT}{hline 9}{c TT}{hline 1}{c BT}{hline 8}{c RT}
	     {c |} weight {c |} length {c |} turn {c |} displa~t {c |} gear_r~o {c |}  foreign {c |}
	     {c |} {res} 2,930 {txt}{c |} {res}   186 {txt}{c |} {res}  40 {txt}{c |} {res}     121 {txt}{c |} {res}    3.58 {txt}{c |} {res}Domestic {txt}{c |}
	     {c BLC}{hline 8}{c BT}{hline 8}{c BT}{hline 6}{c BT}{hline 10}{c BT}{hline 10}{c BT}{hline 10}{c BRC}

	     {c TLC}{hline 13}{c TT}{hline 7}{c TT}{hline 5}{c TT}{hline 8}{c TT}{hline 11}{c TT}{hline 8}{c TRC}
	  2. {c |} make        {c |} price {c |} mpg {c |} rep78  {c |} headroom  {c |} trunk  {c |}
	     {c |} {res}AMC Pacer   {txt}{c |} {res}4,749 {txt}{c |} {res} 17 {txt}{c |} {res}    3  {txt}{c |} {res}     3.0  {txt}{c |} {res}   11  {txt}{c |}
	     {c LT}{hline 8}{c TT}{hline 4}{c BT}{hline 3}{c TT}{hline 3}{c BT}{hline 2}{c TT}{hline 2}{c BT}{hline 7}{c TT}{c BT}{hline 9}{c TT}{hline 1}{c BT}{hline 8}{c RT}
	     {c |} weight {c |} length {c |} turn {c |} displa~t {c |} gear_r~o {c |}  foreign {c |}
	     {c |} {res} 3,350 {txt}{c |} {res}   173 {txt}{c |} {res}  40 {txt}{c |} {res}     258 {txt}{c |} {res}    2.53 {txt}{c |} {res}Domestic {txt}{c |}
	     {c BLC}{hline 8}{c BT}{hline 8}{c BT}{hline 6}{c BT}{hline 10}{c BT}{hline 10}{c BT}{hline 10}{c BRC}

{p 4 4 2}
{cmd:listp} respects linesize.  That is, if you resize the Results window (in
windowed versions of Stata) before running {cmd:listp}, it will take advantage
of the available horizontal space.  (Stata for Unix(console) users can instead
use the {help linesize:set linesize} command to take advantage of this
feature.)

{p 4 4 2}
{cmd:listp} might not display all of a large string.  You have 2 choices.  You
can specify the {cmd:clean} option which makes a different, less attractive
listing, or you can change your linesize to larger as discussed above.


{title:Options}

{p 4 8 2}
{cmd:pagebreak()} is not optional.  {cmd:pagebreak(#)} specifies the number of observations 
{cmd:listp} will display before the page break character is issued.  For example, {cmd:pagebreak(10)} would specify that a page break character be displayed every 10 observations.

{p 4 8 2}
{cmd:display} and {cmd:table} determine the style of output.  By default,
    {cmd:listp} determines which to use for itself based on the width of your
    screen and the {cmd:linesize()} option, if you specify it.

{p 8 8 2}
    {cmd:display} forces display format.

{p 8 8 2}
    {cmd:table} forces table format.
    Forcing table format when {cmd:listp} would have chosen otherwise
    generally produces impossible-to-read output because of the linewraps.
    However, if you are {help log:logging output} in SMCL format and
    plan later to print the output on wide paper, specifying {cmd:table}
    can be a reasonable thing to do.

{p 4 8 2}
{cmd:clean} is a better alternative to {cmd:table} when you want to force
    table format and your goal is to produce more readable output on the
    screen.  {cmd:clean} implies {cmd:table} and it removes all dividing and
    separating lines, which is what makes wrapped table output nearly
    impossible to read.

{p 4 8 2}
{cmd:compress} and {cmd:nocompress} change the width of the columns in both
    table and display formats.  By default, {cmd:listp} examines the data
    and decides on the width to allocate to each variable based on what
    will actually be needed.  For instance, a variable might be a string
    with a %18s format and yet, the longest string be only 12 characters long.
    Or a numeric variable might have a %9.0g format and yet, given the values
    actually present, the widest number needs only 4 columns.

{p 8 8 2}
    {cmd:nocompress} prevents {cmd:listp} from examining the data.  Widths will
    be set according to the {help format:display format} of each variable.
    Output generally looks better when {cmd:nocompress} is not specified,
    but for very large datasets (say 1,000,000 observations or more),
    {cmd:nocompress} can speed execution of {cmd:listp}.

{p 8 8 2}
    {cmd:compress} will allow listp to engage in a little more compression
    than it otherwise would.  Among the things that determine the widths of
    the columns, the variable names also play a role.  Left to itself,
    {cmd:listp} will never abbreviate variable names to fewer than 8
    characters.  {cmd:compress} tells {cmd:listp} that it will be okay to
    abbreviate variable names to fewer characters than that.

{p 4 8 2}
{cmd:abbreviate(}{it:#}{cmd:)} is an alternative to {cmd:compress}.  It allows
    you to specify the minimum abbreviation of variable names to be considered.
    {cmd:abbreviate()} will also allow you to specify larger as well as
    smaller values, so you could specify {cmd:abbreviate(16)} if you never
    wanted variables abbreviated to less than 16 characters.

{p 4 8 2}
{cmd:subvarname} is a programmer's option.  If a variable has the
    {help char:characteristic} {it:var}{cmd:[varname]} set, then the contents
    of that characteristic will be used in place of the variable's name in the
    headers.

{p 4 8 2}
    {cmd:noobs} suppresses the listing of the observation numbers.

{p 4 8 2}
{cmd:absolute} plays a role only when {cmd:listp} is prefixed with {cmd:by}
    {it:varlist}{cmd::}.  Observation numbers are displayed, but rather than
    displaying the observation numbers within each by group, the overall
    observation numbers are used.  E.g., if the first group had 4 observations
    and the second 2, by default the observations would be numbered 1, 2, 3,
    4 and 1, 2.  If {cmd:absolute} is specified, the observations will be
    numbered 1, 2, 3, 4 and 5, 6.

{p 4 8 2}
{cmd:divider}, {cmd:separator(}{it:#}{cmd:)}, and
{cmd:sepby(}{it:varlist}{cmd:)} specify how dividers and separator lines
should be displayed.  These three options play a role only in table format;
otherwise, they are ignored.

{p 8 8 2}
    {cmd:divider} specifies that divider lines should be drawn between
    columns.  The default is {cmd:nodivider}.

{p 8 8 2}
    {cmd:separator(}{it:#}{cmd:)} and {cmd:sepby(}{it:varlist}{cmd:)} indicate
    when separator lines should be drawn between rows and are alternatives.

{p 8 8 2}
    {cmd:separator(}{it:#}{cmd:)} specifies a line should be drawn every
    {it:#} observations; the default is {cmd:separator(5)}.  You may specify
    {cmd:separator(0)} to suppress separators altogether.

{p 8 8 2}
    {cmd:sepby(}{it:varlist}{cmd:)} specifies instead that a separator line
    should be drawn whenever any of the variables in
    {cmd:sepby(}{it:varlist}{cmd:)} change their values; up to 10 variables
    may be specified.  Usual usage would involve making sure the data were
    sorted on {cmd:sepby(}{it:varlist}{cmd:)} before issuing the {cmd:listp}
    command, but this is not required.  It is not even required that the
    variables in {cmd:sepby(}{it:varlist}{cmd:)} be among the variables being
    listed.

{p 4 8 2}
{cmd:string(}{it:#}{cmd:)} and {cmd:notrim} affect how string variables are
    listed.

{p 8 8 2}
    {cmd:string(}{it:#}{cmd:)} says that string variables are to be
    truncated to {it:#} characters in the output.  Any value that is
    truncated will be appended with ".." to indicate the truncation.
    {cmd:string()} is useful in displaying just a part of long strings.

{p 8 8 2}
    The default is to trim strings at the width implied by the widest
    possible column given your screen width (or {cmd:linesize()}, if you
    specified that).  {cmd:notrim} specifies that strings are not be trimmed.
    {cmd:notrim} implies {cmd:clean} (see above) and, in fact, is exactly
    equivalent to the {cmd:clean} option, so which you specify makes no
    difference.

{p 4 8 2}
{cmd:nolabel} causes the numeric codes rather than label values to be
displayed.

{p 4 8 2}
{cmd:nodotz} is a programmer's option.  It specifies that numerical values
    equal to .z should be listed as a field of blanks rather than .z.

{p 4 8 2}
{cmd:linesize(}{it:#}{cmd:)} specifies the width of the page that should be
    used for determining whether table or display format be used and for
    formatting the resulting table.  Specifying a value of {cmd:linesize()}
    wider than your screen width can produce truly ugly output on the screen,
    but that output can nevertheless be useful if you are logging output and
    later plan to print the log on a wide printer.

{p 4 8 2}
{cmd:pagenumber} places "Page #" before each page break.

{title:Examples}

    {cmd:. listp, pagebreak(100)}
    {cmd:. listp mpg weight, pagebreak(15) pagenumber}

{title:Also see}

    Manual:  {hi:[R] list}

{p 4 13 2}
Online:  help for
{help list},
{help edit},
{help display},
{help table}