From 2d126da890e3f8a788fb11113e45deeef4aa7c3a Mon Sep 17 00:00:00 2001 From: wlemb Date: Wed, 17 Jul 2002 04:55:45 +0000 Subject: * contrib/pic2graph/pic2graph.*: Use convert(1). * contrib/eqn2graph/eqn2graph.*: Minor fixes. * tmac/groff_trace.man: New file. * tmac/Makefile.sub: Updated. * NEWS: Updated. * src/roff/groff/groff.man: Add some cross references. * src/roff/troff/input.cc (substring_request): Add warnings for string indices out of range. * font/devdvi/generate/ec.map: Fix typo (`(l' -> `/l'). * font/devdvi/*EC: Regenerated. * man/groff_char.man: Updated and extended. * src/roff/troff/input.cc (length_macro): Renamed to... (length_request): This. Move call of `tok.next()' to the very end, otherwise the register value hasn't been updated yet. (init_input_requests): Updated. * src/roff/troff/input.cc (substring_macro): Renamed to... (substring_request): This. (init_input_requests): Updated. * src/roff/troff/request.h: Updated. * src/roff/grog/grog.sh: Fix typo. * win32-diffs: Updated. Handle `papersize' keyword properly in DESC. * src/libs/libgroff/font.cc (font::scan_papersize): Fix argument type. Updated all callers. * src/libs/libgroff/paper.cc: Add four more paper formats used by grolj4. * src/include/paper.h: Updated. * src/devices/grolbp/lbp.cc: Remove unnecessary semicolons. Other minor C syntax fixes. (papersize, paperlength, paperwidth): Renamed to `user_*'. (lbp_printer): Add `papersize', `paperlength', and `paperwidth' members. (lbp_printer::lbp_printer): Pass three arguments. Set paper dimensions properly. (make_printer, main): Updated. (handle_unknown_desc_command): Fix error messages. (main): Handle papersize keyword in DESC properly. * src/devices/grolj4/lj4.cc (paper_size): Renamed to `user_paper_size'. (lbp_printer::lbp_printer): Pass an argument. Set paper_size properly. (handle_unknown_desc_command): Removed. (make_printer, main): Updated. * src/devices/grolj4/grolj4.man: Minor documentation fix. * man/groff_font.man, NEWS: Updated. --- tmac/groff_trace.man | 546 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 546 insertions(+) create mode 100644 tmac/groff_trace.man (limited to 'tmac/groff_trace.man') diff --git a/tmac/groff_trace.man b/tmac/groff_trace.man new file mode 100644 index 00000000..f7f1ae87 --- /dev/null +++ b/tmac/groff_trace.man @@ -0,0 +1,546 @@ +. +.TH GROFF_TRACE @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@" +.SH NAME +groff_trace \- groff macro package trace.tmac +.SH SYNOPSIS +.\" The .SH was moved to this place to make `apropos' happy. +. +. +.\" -------------------------------------------------------------------- +.\" Legalize +.\" -------------------------------------------------------------------- +. +.ig +groff_trace.7 + +File position: /tmac/groff_trace.man + +Last update: 14 July 2002 + +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2002 Free Software Foundation, Inc. +written by Bernd Warken + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this .ig-section and AUTHOR, with no +Front-Cover Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +.. +. +.\" -------------------------------------------------------------------- +.\" Setup +.\" -------------------------------------------------------------------- +. +.mso www.tmac +. +.if n \{\ +. mso tty-char.tmac +. ftr CR R +. ftr CI I +. ftr CB B +.\} +. +.ds Ellipsis .\|.\|.\&\" +. +.\" Global static variables for inter-macro communication +.rr @+Example_font +. +.\" -------------------------------------------------------------------- +.\" setup for the macro definitions below +.\" +.\" naming: namespace:category_macro.variable_name (experimental) +. +.\" -------------------------------------------------------------------- +.\" configuration of prompt for `.Shell_cmd'* macros +.ds trace:Shell_cmd.prompt_text sh#\" prompt for shell commands +.ds trace:Shell_cmd+.prompt_text >\" prompt on continuation lines +.ds trace:Shell_cmd_base.prompt_font I\" font for prompts +. +.\" automatically determine setup from the configuration above +.als @f trace:Shell_cmd_base.prompt_font\" +.als @t trace:Shell_cmd.prompt_text\" +.als @t+ trace:Shell_cmd+.prompt_text\" +.ds trace:Shell_cmd.prompt \f[\*[@f]]\*[@t]\f[]\" needed +.ds trace:Shell_cmd+.prompt \f[\*[@f]]\*[@t+]\f[]\" needed +.nr @w \w'\*[trace:Shell_cmd.prompt]'\" +.nr @w+ \w'\*[trace:Shell_cmd+.prompt]'\" +.ft \*[@f] +.\" Full prompt width is maximum of texts plus 1m +.nr trace:Shell_cmd_base.prompt_width (\n[@w]>?\n[@w+]+1m)\" needed +.ft +.rm @f +.rm @f+ +.rm @t +.rm @t+ +.rr @w +.rr @w+ +. +.\"-------------------------------------------------------------------- +.\" Ignore all arguments like a comment, even after a .eo call. +.de c +.. +.c -------------------------------------------------------------------- +.de BIR +. ie (\\n[.$] < 3) \ +. BI \\$@ +. el \{\ +. ds @tmp@ \fB\\$1\f[]\fI\\$2\f[] +. shift 2 +. Text \\*[@tmp@]\fR\\$*\f[] +. rm @tmp@ +. \} +.. +.c -------------------------------------------------------------------- +.c .Env_var ( []) +.c +.c Display an environment variable, with optional punctuation. +.c +.de Env_var +. nh +. SM +. Text \f[CB]\\$1\f[]\\$2 +. hy +.. +.c -------------------------------------------------------------------- +.c .Error (...) +.c +.c Print error message to terminal and abort. +.c +.de Error +. tm \\$* +. ab +.. +.c -------------------------------------------------------------------- +.de Example +. if r@+Example_font \ +. Error previous .Example was not terminated by a ./Example +. nr @+Example_font \\n[.f] +. nh +. nf +.c RS \\n[trace:Shell_cmd_base.prompt_width]u +. ft CR +.. +.c -------------------------------------------------------------------- +.de /Example +. if !r@+Example_font \ +. Error no previous call to .Example +. ft \\n[@+Example_font] +.c RE +. fi +. hy +. rr @+Example_font +.. +.c -------------------------------------------------------------------- +.de Macdef +. if (\\n[.$] <= 0) \ +. Error \\$0 needs at least one argument. +. ds @s .\f[B]\\$1\f[]\" +. shift +. if (\\n[.$] > 0) \ +. as @s \~\f[I]\\$*\f[]\" +. IP \\*[@s] +. rm @s +.. +.c -------------------------------------------------------------------- +.de Macdef+ +. br +. ns +. Macdef \\$@ +.. +.c -------------------------------------------------------------------- +.c .Shell_cmd ( [] ...) +.c +.c A shell command line; display args alternating in fonts CR and CI. +.c +.c Examples: +.c .Shell_cmd "groffer --dpi 100 file" +.c result: `sh# groffer --dpi 100 file' +.c with 'sh#' in font I, the rest in CR +.c +.c .Shell_cmd groffer\~--dpi\~100\~file +.c result: the same as above +.c +.c .Shell_cmd "groffer --dpi=" value " file" +.c result: sh# groffer --dpi=value file +.c with `groffer --dpi=' and `file' in CR; `value' in CI +.c +.c .Shell_cmd groffer\~--dpi= value \~file +.c result: the same as the previous example +.c +.de Shell_cmd +. trace:Shell_cmd_base "\*[trace:Shell_cmd.prompt]" \\$@ +.. +.c -------------------------------------------------------------------- +.c .Shell_cmd+ ( [] ...) +.c +.c A continuation line for .Shell_cmd. +.c +.de Shell_cmd+ +. trace:Shell_cmd_base "\*[trace:Shell_cmd+.prompt]" \\$@ +.. +.c -------------------------------------------------------------------- +.c .Shell_cmd_base ( [ [] ...]) +.c +.c A shell command line; display args alternating in fonts CR and CI. +.c Internal, do not use directly. +.c +.c Globals: read-only register @.Shell_cmd_width +.c +.de trace:Shell_cmd_base +. if (\\n[.$] <= 0) \ +. return +. nr @+font \\n[.f]\" +. ds @prompt \\$1\" +. ft CR +. c gap between prompt and command +. nr @+gap \\n[trace:Shell_cmd_base.prompt_width]-\\w'\\*[@prompt]'\" +. ds @res \\*[@prompt]\h'\\n[@+gap]u'\" +. shift +. ds @cf CR\" +. while (\\n[.$] > 0) \{\ +. as @res \\f[\\*[@cf]]\\$1\" +. shift +. ie '\\*[@cf]'CR' \ +. ds @cf I\" +. el \ +. ds @cf CR\" +. \} +. br +. ad l +. nh +. nf +. Text \\*[@res]\" +. fi +. hy +. ad +. br +. ft \\n[@+font] +. rr @+font +. rr @+gap +. rm @cf +. rm @res +.. +.c -------------------------------------------------------------------- +.c .Text (...) +.c +.c Treat the arguments as text, no matter how they look. +.c +.de Text +. if (\\n[.$] == 0) \ +. return +. nop \)\\$*\) +.. +.c -------------------------------------------------------------------- +.c .Topic ([]) +.c +.c A bulleted paragraph. +.c +.de Topic +. ie (\\n[.$] = 0) \ +. .ds @indent 2m\" +. el \ +. .ds @indent \\$1\" +. TP \\*[@indent] +. Text \[bu] +. rm @indent +.. +.c -------------------------------------------------------------------- +.c .TP+ () +.c +.c Continuation line for .TP header. +.c +.de TP+ +. br +. ns +. TP \\$1 +.. +.c -------------------------------------------------------------------- +.de 'char +. ds @tmp@ `\f(CR\\$1\f[]' +. shift +. Text \\*[@tmp@]\\$* +. rm @tmp@ +.. +.c -------------------------------------------------------------------- +.de option +. ds @tmp@ \f(CB\\$1\f[] +. shift 1 +. Text \\*[@tmp@]\\$* +. rm @tmp@ +.. +.c -------------------------------------------------------------------- +.de argument +. ds @tmp@ \f(CI\\$1\f[] +. shift 1 +. Text \\*[@tmp@]\\$* +. rm @tmp@ +.. +.c -------------------------------------------------------------------- +.de request +. ds @tmp@ \f(CB\\$1\f[] +. shift 1 +. Text .\\*[@tmp@]\\$* +. rm @tmp@ +.. +.c -------------------------------------------------------------------- +.de escape +. ds @tmp@ \f[CB]\\$1\f[] +. shift 1 +. Text \[rs]\\*[@tmp@]\\$* +. rm @tmp@ +.. +. +. +.\" -------------------------------------------------------------------- +.\" SH SYNOPSIS +.\" -------------------------------------------------------------------- +. +.B groff -m trace +.RI [ options\*[Ellipsis] ] +.RI [ files\*[Ellipsis] ] +. +. +.P +Elements in brackets denote optional arguments, and the ellipsis means +that there can be any number of arguments of this kind. +. +. +.\" -------------------------------------------------------------------- +.SH DESCRIPTION +.\" -------------------------------------------------------------------- +. +The +.I trace +macro package of +.BR groff (@MAN1EXT@) +can be a valuable tool for debugging documents written in the roff +formatting language. +. +A call stack trace is protocolled on standard error, that means, a +diagnostic message is emitted on entering and exiting of a macro call. +. +This greatly eases to track down an error in some macro. +. +. +.P +This tracing process is activated by specifying the groff or troff +command line option +.BR "-m\~trace" . +This works also with the +.BR groffer (@MAN1EXT@) +viewer program. +. +A finer control can be obtained by including the macro file within the +document by the groff macro call +.BR ".mso\~trace.tmac" . +Only macros that are defined after this line are traced. +. +. +.P +If some other macro package should be traced as well it must be specified +after +.BR "-m\~trace" +on the command line. +. +. +.P +The macro file +.B trace.tmac +is unusual because it does not contain any macros to be called by a +user. +. +Instead, the existing macro definition and appending facilities are +modified such that they display diagnostic messages. +. +. +.\" -------------------------------------------------------------------- +.SH EXAMPLES +.\" -------------------------------------------------------------------- +. +.P +In the following examples, a roff fragment is fed into groff via +standard input. +. +As we are only interested in the diagnostic messages (standard error) +on the terminal, the normal formatted output (standard output) is +redirected into the nirvana device +.IR /dev/null . +The resulting diagnostic messages are displayed directly below the +corresponding example. +. +. +.\" -------------------------------------------------------------------- +.SS "Command line option" +. +.P +.Shell_cmd "echo '." +.Shell_cmd+ ".de test_macro" +.Shell_cmd+ ".." +.Shell_cmd+ ".test_macro" +.Shell_cmd+ ".test_macro some dummy arguments" +.Shell_cmd+ "' | groff -m trace >/dev/null" +.P +.Example +*** de trace enter: test_macro +*** trace exit: test_macro +*** de trace enter: test_macro "some" "dummy" "arguments" +*** trace exit: test_macro "some" "dummy" "arguments" +./Example +. +.P +The entry and the exit of each macro call is displayed on the terminal +(standard output) \[em] together with the arguments (if any). +. +. +.\" -------------------------------------------------------------------- +.SS "Nested macro calls" +. +.P +.Shell_cmd "echo '." +.Shell_cmd+ ".de child" +.Shell_cmd+ ".." +.Shell_cmd+ ".de parent" +.Shell_cmd+ ".child" +.Shell_cmd+ ".." +.Shell_cmd+ ".parent" +.Shell_cmd+ "' | groff -m trace >/dev/null" +.P +.Example +*** de trace enter: parent +*** de trace enter: child +*** trace exit: child +*** trace exit: parent +./Example +. +.P +This shows that macro calls can be nested. +. +This powerful feature can help to tack down quite complex call stacks. +. +. +.\" -------------------------------------------------------------------- +.SS "Activating with .mso" +. +.Shell_cmd "echo '." +.Shell_cmd+ ".de before" +.Shell_cmd+ .. +.Shell_cmd+ ".mso trace.tmac" +.Shell_cmd+ ".de after" +.Shell_cmd+ .. +.Shell_cmd+ .before +.Shell_cmd+ .after +.Shell_cmd+ .before +.Shell_cmd+ "' | groff >/dev/null" +.P +.Example +*** de trace enter: after +*** trace exit: after +./Example +. +.P +Here, the tracing is activated within the document, not by a command +line option. +. +As tracing was not active when macro +.I before +was defined, no call of this macro is protocolled; on the other hand, +the macro +.I after +is fully protocolled. +. +. +.\" -------------------------------------------------------------------- +.SH FILES +.\" -------------------------------------------------------------------- +. +The +.I trace +macros are kept in the file +.B trace.tmac +located in the +.IR "tmac directory" ; +see +.BR groff_tmac (@MAN5EXT@) +for details. +. +. +.\" -------------------------------------------------------------------- +.SH ENVIRONMENT +.\" -------------------------------------------------------------------- +. +.TP +.Env_var $GROFF_TMAC_PATH +A colon-separated list of additional tmac directories in which to +search for macro files; see +.BR groff_tmac (@MAN5EXT@) +for details. +. +. +.\" -------------------------------------------------------------------- +.SH AUTHOR +.\" -------------------------------------------------------------------- +. +Copyright (C) 2002 Free Software Foundation, Inc. +. +.P +This document is distributed under the terms of the FDL (GNU Free +Documentation License) version 1.1 or later. +. +You should have received a copy of the FDL on your system, it is also +available on-line at the +.URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" . +. +.P +This document is part of +.IR groff , +the GNU roff distribution. +. +It was written by +.MTO bwarken@mayn.de "Bernd Warken". +. +. +.\" -------------------------------------------------------------------- +.SH "SEE ALSO" +.\" -------------------------------------------------------------------- +. +.TP +.BR groff (@MAN1EXT@) +An overview of the groff system. +. +. +.TP +.BR troff (@MAN1EXT@) +For details on option +.BR -m . +. +. +.TP +.BR groffer (@MAN1EXT@) +A viewer program for all kinds of roff documents. +. +. +.TP +.BR groff_tmac (@MAN5EXT@) +A general description of groff macro packages. +. +. +.TP +.BR groff (@MAN7EXT@) +A short reference for the groff formatting language. +. +. +.P +A complete reference for all parts of the groff system is found in the +groff +.BR info (1) +file. +. +. +.\" Local Variables: +.\" mode: nroff +.\" End: -- cgit v1.2.1