[Tabfmt-cvs] tabfmt/doc tabfmt.texi,1.2,1.3

[Claudio J. <jo...@us...>]

Update of /cvsroot/tabfmt/tabfmt/doc
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv19625/doc

Modified Files:
	tabfmt.texi 
Log Message:
Many additions, particularly to the invocation node. Added another example. Added instructions how to obtain tabfmt via CVS.

Index: tabfmt.texi
===================================================================
RCS file: /cvsroot/tabfmt/tabfmt/doc/tabfmt.texi,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** tabfmt.texi	10 Jan 2006 16:34:30 -0000	1.2
--- tabfmt.texi	26 Jan 2006 21:19:54 -0000	1.3
***************
*** 18,29 ****
  under the terms of the GNU Free Documentation License, Version 1.1 or
  any later version published by the Free Software Foundation; with no
! Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
! and with the Back-Cover Texts as in (a) below.  A copy of the
! license is included in the section entitled ``GNU Free Documentation
! License.''
! 
! (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
! this GNU Manual, like GNU software.  Copies published by the Free
! Software Foundation raise funds for GNU development.''
  @end quotation
  @end copying
--- 18,24 ----
  under the terms of the GNU Free Documentation License, Version 1.1 or
  any later version published by the Free Software Foundation; with no
! Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.  A
! copy of the license is included in the section entitled ``GNU Free
! Documentation License.''
  @end quotation
  @end copying
***************
*** 73,94 ****
  lines into fields given a set of input field delimiters, and prints a
  table with constant-width columns to standard output or a specified
! file. Minimum and maximum field widths, left and right padding, as well
! as the characters used for filling, padding and delimiting the fields
! can be specified.
  
! This program is meant to integrate well with the standard UNIX utilities
! for text manipulation. It is specialised in a simple, everyday task
! which is usually too bothersome to implement in shell scripting. While
! tabfmt currently formats the table using plain text, extensions may
! include output in other formats such as HTML, LaTeX, Texinfo, or XML
! languages.
  
! The program was originally written for a GNU environment, but should
! build and run on a wide variety of platforms thanks to the GNU autotools
! and a portability library which is compiled and linked as needed
! (gnulib). It has been successfully built on GNU/Linux, FreeBSD and
! NetBSD. The program provides support for localisation using the GNU
! gettext package; a German language translation has been provided by the
! author. The package contains a preliminary test suite.
  
  @node Invoking tabfmt, Examples, Overview, Top
--- 68,80 ----
  lines into fields given a set of input field delimiters, and prints a
  table with constant-width columns to standard output or a specified
! file.
  
! Minimum and maximum field widths, left and right padding, as well as the
! characters used for filling, padding and delimiting the fields can be
! specified.
  
! This program is meant to integrate well with the standard @sc{UNIX}
! utilities for text manipulation. It is specialised in a simple, everyday
! task which is usually too bothersome to implement in shell scripting.
  
  @node Invoking tabfmt, Examples, Overview, Top
***************
*** 98,101 ****
--- 84,92 ----
  @cindex invoking @command{tabfmt}
  
+ @code{tabfmt} reads lines from one or more files, breaks the lines into
+ fields given a set of input field delimiters, and prints a table with
+ constant-width columns to standard output. Standard input is used for a
+ file name of @samp{-} or if no input files are given.
+ 
  The format for running the @code{tabfmt} program is:
  
***************
*** 104,156 ****
  @end example
  
! @code{tabfmt} supports the following options:
  
  @table @samp
! @item -w WLIST
! @itemx --widths=WLIST
! Use WLIST as field widths.
  
  @item -e
  @itemx --equal-width
! Use equal width for all fields.
  
! @item -f CHAR
! @itemx --filler=CHAR
! Use CHAR to fill fields [SPC].
  
! @item -a ALIST
! @itemx --align=ALIST
! Align fields according to LIST.
  
! @item -p LIST
! @itemx --padding=LIST
! Use LIST as padding [none].
  
! @item -l PLIST
! @itemx --left-padding=PLIST
! Use PLIST as left padding.
  
! @item -r PLIST
! @itemx --right-padding=PLIST
! Use PLIST as right padding.
  
! @item -P
! @itemx --padder=CHAR
! Use CHAR as padding character [SPC].
  
! @item -d
! @itemx --delimiter=DELIM
! Set of field delimiters [TAB,SPC].
  
! @item -D DELIM
! @itemx --output-delimiter=DELIM
! Output field delimiter [TAB].
  
! @item -o FILE
! @itemx --output=FILE
! Write output to FILE [stdout].
  
  @item --debug
! Print debugging information.
  
  @item -h
--- 95,243 ----
  @end example
  
! In the table which follows, the @var{width-list}, @var{padding-list} and
! @var{alignment-list} are comma-separated lists. Each list element refers
! to the corresponding field in the input. If the number of fields exceeds
! the number of list elements, the last element counts for all remaining
! fields.
! 
! The program accepts the following options:
  
  @table @samp
! @item -d @var{string}
! @itemx --delimiter=@var{string}
! @cindex backslash escapes
! @cindex environment variables, @env{IFS}
! Break the input lines into fields at any of the characters in
! @var{string}. By default, input fields are delimited by the characters
! in the @env{IFS} environment variable. If this environment variable is
! not set, @samp{TAB} and @samp{SPC} will be used as the default.
! 
! The following backslash-escaped characters are recognized:
! 
! @table @samp
! @item \a
! alert (@samp{BEL})
! @item \b
! backspace (@samp{BS})
! @item \f
! form feed (@samp{FF})
! @item \n
! new line (@samp{LF})
! @item \r
! carriage return (@samp{CR})
! @item \t
! horizontal tab (@samp{TAB})
! @item \v
! vertical tab (@samp{VT})
! @item \\
! backslash (@samp{\})
! @item \@var{nnn}
! the character whose @acronym{ASCII} code is @var{nnn} (octal); if
! @var{nnn} is not a valid octal number, its value is taken literally.
! @end table
! 
! The input delimiter does not appear in the output (see the description
! of @option{--output-delimiter} instead). If a sequence of input
! delimiters appears in the input, each pair of delimiters is taken to
! enclose an empty field.
! 
! @item -w @var{width-list}
! @itemx --widths=@var{width-list}
! @cindex lists
! @cindex ranges
! @cindex width
! Determine the minimum and maximum output width of each field. By
! default, the width of a field is determined by its widest entry in all
! lines.
! 
! Each element of @var{width-list} has one of the following forms:
! 
! @table @samp
! @item 
! An empty element poses no constraints on the width of a field. The width
! is determined by the widest entry occurring at this field in all lines.
! 
! @item @var{n}-
! Use at least @var{n} characters for this field. If an entry has less
! characters, the missing characters are filled with spaces, or the
! character specified with the option @option{--filler}.
! 
! @item -@var{n}
! Use at most @var{n} characters for this field. If an entry has more
! characters, the remaining characters are cut off.
! 
! @item @var{n}-@var{m}
! Use at least @var{n} and at most @var{m} characters for this field.
! 
! @item @var{n}
! Use exactly @var{n} characters for this field.
! 
! @end table
  
  @item -e
  @itemx --equal-width
! Use the same width for all fields. The width is determined by the widest
! entry in all fields.  If a minimum or maximum width is specified (see
! the description of @option{--widths}), all but the first element of
! @var{width-list} are ignored.
  
! @item -f @var{character}
! @itemx --filler=@var{character}
! If an entry has less characters than the field width, fill the missing
! characters with @var{character}; default is @samp{SPC}. The same
! backslash-escaped characters are recognized as for the option
! @option{--delimiter}.
  
! @item -a @var{alignment-list}
! @itemx --align=@var{alignment-list}
! Determine the alignment of each field. By default, all fields are
! left-aligned. Elements of @var{alignment-list} have the following form:
  
! @table @asis
! @item @samp{l} or @samp{L}
! Align the entry to the left of the field.
! @item @samp{r} or @samp{R}
! Align the entry to the right of the field.
! @item @samp{c} or @samp{C}
! Center the entry in the field.
! @end table
  
! @item -p @var{padding-list}
! @itemx --padding=@var{padding-list}
! Determine the number of padding characters of each field. By default,
! fields have no padding. The padding will appear both at the left and the
! right of the field. Note that the padding does not contribute to the
! field width.
  
! @item -l @var{padding-list}
! @itemx --left-padding=@var{padding-list}
! Determine the left padding of each field (see the description of
! @option{--padding}).
  
! @item -r @var{padding-list}
! @itemx --right-padding=@var{padding-list}
! Determine the right padding of each field (see the description of
! @option{--padding}).
  
! @item -P @var{character}
! @itemx --padder=@var{character}
! If a padding is specified for any field, fill it with @var{character};
! default is @samp{SPC} (see the description of @option{--padding}). The
! same backslash-escaped characters are recognized as for the option
! @option{--delimiter}.
  
! @item -D @var{character}
! @itemx --output-delimiter=@var{character}
! Separate the fields by @var{character} in the output; default is
! @samp{TAB}. The same backslash-escaped characters are recognized as for
! the option @option{--delimiter}.
  
! @item -o @var{file}
! @itemx --output=@var{file}
! Write the output to the file @var{file}. By default, the table is
! written to standard output.
  
  @item --debug
! Produce debugging information.
  
  @item -h
***************
*** 163,166 ****
--- 250,264 ----
  @end table
  
+ An exit status of zero indicates success, and a nonzero value indicates
+ failure.
+ 
+ Note that each line in the input can have a different number of fields;
+ in this case, the lines will also have different numbers of fields in
+ the output. In other words, no fields are added in the output.
+ 
+ If multiple files are specified, they will be treated as a single
+ dataset. In particular, the field widths are not computed per input
+ file; they are computed over the entire input.
+ 
  @node Examples, Reporting Bugs, Invoking tabfmt, Top
  @chapter Examples
***************
*** 169,200 ****
  @cindex example
  
! Here is an example of running @code{tabfmt}.
  
! Below is the output of the command @samp{tabfmt -d: /etc/passwd}:
  
  @example
! root       	x	0    	0    	root                 /root              	/bin/bash 
! daemon     	x	1    	1    	daemon               /usr/sbin          	/bin/sh   
! bin        	x	2    	2    	bin                  /bin               	/bin/sh   
! sys        	x	3    	3    	sys                  /dev               	/bin/sh   
! sync       	x	4    	65534	sync                 /bin               	/bin/sync 
! games      	x	5    	60   	games                /usr/games         	/bin/sh   
! man        	x	6    	12   	man                  /var/cache/man     	/bin/sh   
! lp         	x	7    	7    	lp                   /var/spool/lpd     	/bin/sh   
! mail       	x	8    	8    	mail                 /var/mail          	/bin/sh   
! news       	x	9    	9    	news                 /var/spool/news    	/bin/sh   
! uucp       	x	10   	10   	uucp                 /var/spool/uucp    	/bin/sh   
! proxy      	x	13   	13   	proxy                /bin               	/bin/sh   
! www-data   	x	33   	33   	www-data             /var/www           	/bin/sh   
! backup     	x	34   	34   	backup               /var/backups       	/bin/sh   
! list       	x	38   	38   	Mailing List Manager /var/list          	/bin/sh   
! irc        	x	39   	39   	ircd                 /var/run/ircd      	/bin/sh   
! nobody     	x	65534	65534	nobody               /nonexistent       	/bin/sh   
! Debian-exim	x	102  	102  	                     /var/spool/exim4   	/bin/false
! sshd       	x	100  	65534	                     /var/run/sshd      	/bin/false
! admin      	x	1000 	1000 	Administrator,,,     /home/admin        	/bin/bash 
! cj         	x	1001 	1001 	Claudio Jolowicz,,,  /home/cj           	/bin/bash 
  @end example
  
  @node Reporting Bugs, Copying This Manual, Examples, Top
  @chapter Reporting Bugs
--- 267,319 ----
  @cindex example
  
! @code{tabfmt} is particularly useful to convert various system
! configuration files to a more readable format.
  
! @example
! 
! @b{$} tabfmt /etc/mtab
! 
! /dev/hda1	/            	ext3  	rw                   	0	0
! /dev/hda2	/tmp         	ext3  	rw,nosuid,nodev      	0	0
! /dev/hda3	/var         	ext3  	rw,nosuid,nodev      	0	0
! /dev/hda4	/usr         	ext3  	rw,nodev             	0	0
! /dev/hda5	/home        	ext3  	rw,nosuid,nodev      	0	0
! proc     	/proc        	proc  	rw                   	0	0
! sysfs    	/sys         	sysfs 	rw                   	0	0
! devpts   	/dev/pts     	devpts	rw,gid=5,mode=620    	0	0
! tmpfs    	/dev/shm     	tmpfs 	rw                   	0	0
! usbfs    	/proc/bus/usb	usbfs 	rw                   	0	0
! tmpfs    	/dev         	tmpfs 	rw,size=10M,mode=0755	0	0
! 
! @end example
! 
! This example splits @file{/etc/mtab} (which contains space-separated
! data), and outputs a tab-delimited table with constant-width
! columns. (You will not find any tabs here if you are reading this manual
! in printed or HTML format.)
  
  @example
! 
! @b{$} awk -F: '( $7 == "/bin/false")' /etc/passwd |
! @b{>} tabfmt -d: -w,,,,15,,0 -D\| -p1
! 
!  Debian-exim | x | 102 | 102   |                 | /var/spool/exim4    |  
!  sshd        | x | 100 | 65534 |                 | /var/run/sshd       |  
!  messagebus  | x | 101 | 104   |                 | /var/run/dbus       |  
!  hal         | x | 105 | 105   | Hardware abstra | /var/run/hal        |  
!  identd      | x | 103 | 65534 |                 | /var/run/identd     |  
!  gdm         | x | 104 | 107   | Gnome Display M | /var/lib/gdm        |  
!  ntop        | x | 109 | 109   |                 | /var/lib/ntop       |  
!  scanlogd    | x | 107 | 65534 |                 | /usr/lib/scanlogd   |  
!  cups-pdf    | x | 108 | 65534 | Anonymous Samba | /var/spool/cups-pdf |  
! 
  @end example
  
+ This example first uses @code{awk} to extract from @file{/etc/passwd}
+ those accounts whose login shell is @file{/bin/false}. It then uses
+ @code{tabfmt} to produce a human-readable table, truncating user names
+ which exceed 20 characters in length, and omitting the login shell,
+ which we already know.
+ 
  @node Reporting Bugs, Copying This Manual, Examples, Top
  @chapter Reporting Bugs
***************
*** 203,216 ****
  @cindex Suggestions for Tabfmt, making
  @cindex Reporting bugs
! I welcome bug reports and suggestions for Tabfmt.  Please email them to
! @email{tabfmt-devel@@lists.sourceforge.net}.  You can get the latest version of Tabfmt
! from @uref{http://sourceforge.net/projects/tabfmt}.
  
  @cindex Checklist for bug reports
! For bug reports, please include enough information for the maintainers
  to reproduce the problem.  Generally speaking, that means:
  
  @itemize @bullet
! @item the version number of Tabfmt.
  @item hardware and operating system names and versions.
  @item the contents of any input files necessary to reproduce the bug.
--- 322,349 ----
  @cindex Suggestions for Tabfmt, making
  @cindex Reporting bugs
! Please send bug reports and suggestions for @code{tabfmt} to the
! following mailing list:
! 
! @indent @email{tabfmt-devel@@lists.sourceforge.net}.  
! 
! @noindent You can get the latest version of the program at the @code{tabfmt}
! homepage:
! 
! @indent @uref{http://tabfmt.sourceforge.net/} 
! 
! @noindent Alternatively, you can obtain the source code via @acronym{CVS} with the
! following command:
! 
! @example
! cvs -z3 -d:pserver:anonymous@@cvs.sourceforge.net:/cvsroot/tabfmt \
!   co -P tabfmt
! @end example
  
  @cindex Checklist for bug reports
! @noindent For bug reports, please include enough information for the maintainers
  to reproduce the problem.  Generally speaking, that means:
  
  @itemize @bullet
! @item the version number of @code{tabfmt}.
  @item hardware and operating system names and versions.
  @item the contents of any input files necessary to reproduce the bug.