contrib/groff/src/roff/grog/grog.man

   1 .TH GROG @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
   2 .
   3 .\" --------------------------------------------------------------------
   4 .\" Legalize
   5 .\" --------------------------------------------------------------------
   6 .
   7 .ig
   8 grog.1 - man page for grog (section 1)
   9
  10 Source file position:  <groff_source_top>/src/roff/grog/grog.man
  11 Installed position:    $prefix/share/man/man1/grog.1
  12
  13 Last Update: 5 Jan 2009
  14 ..
  15 .de co
  16 Copyright (C) 1989-2000, 2001, 2002, 2003, 2006, 2007, 2009
  17 Free Software Foundation, Inc.
  18 .
  19 Written by James Clark.
  20 Maintained by
  21 .MT wl@gnu.org
  22 Werner Lemberg
  23 .ME .
  24 Rewritten and put under GPL by Bernd Warken.
  25 .
  26 .P
  27 This file is part of
  28 .IR grog ,
  29 which is part of
  30 .IR groff ,
  31 a free software project.
  32 .
  33 You can redistribute it and/or modify it under the terms of the
  34 .nh
  35 .B "GNU General Public License"
  36 .hy
  37 (\f[CR]GPL\f[]) as published by the
  38 .nh
  39 .BR "Free Software Foundation" ,
  40 .hy
  41 either version\~2, or (at your option) any later version.
  42 .
  43 .P
  44 You should have received a copy of the \f[CR]GNU General Public
  45 License\f[] along with
  46 .IR groff ,
  47 see the files \%\f[CB]COPYING\f[] and \%\f[CB]LICENSE\f[] in the top
  48 directory of the
  49 .I groff
  50 source package.
  51 .
  52 Or read the
  53 .I man\~page
  54 .BR gpl (1).
  55 You can also write to the
  56 .nh
  57 .B "Free Software Foundation, 51 Franklin St - Fifth Floor, Boston,"
  58 .BR "MA 02110-1301, USA" .
  59 .hy
  60 ..
  61 .
  62 .
  63 .\" --------------------------------------------------------------------
  64 .\" Local macros
  65 .de FN
  66 .I \\$1
  67 ..
  68 .
  69 .
  70 .\" --------------------------------------------------------------------
  71 .SH NAME
  72 .
  73 grog \- guess options for groff command
  74 .
  75 .
  76 .\" --------------------------------------------------------------------
  77 .SH SYNOPSIS
  78 .
  79 .SY grog
  80 .OP \-C
  81 .RI [ \%groff\-option\~ .\|.\|.\&]
  82 .OP \-\-
  83 .RI [ \%filespec\~ .\|.\|.]
  84 .
  85 .SY grog
  86 .B \-h
  87 |
  88 .B \-\-help
  89 .
  90 .SY grog
  91 .B \-v
  92 |
  93 .B \-\-version
  94 .YS
  95 .
  96 .
  97 .\" --------------------------------------------------------------------
  98 .SH DESCRIPTION
  99 .
 100 .B grog
 101 reads the input (file names or standard input) and guesses which of
 102 the
 103 .BR groff  (@MAN1EXT@)
 104 options are needed to perform the input with the
 105 .B groff
 106 program.
 107 .
 108 The corresponding
 109 .B groff
 110 command is output.
 111 .
 112 .
 113 .\" --------------------------------------------------------------------
 114 .SH OPTIONS
 115 .
 116 The only
 117 .B grog
 118 options recognized are
 119 .B \-C
 120 (which is also passed on) to enable compatibility mode;
 121 .B \-v
 122 and
 123 .B \-\-version
 124 print information on the version number; and
 125 .B \-h
 126 and
 127 .B \-\-help
 128 print usage information.
 129 .
 130 .BR \-v ,
 131 .BR \-\-version ,
 132 .BR \-h ,
 133 and
 134 .B \-\-help
 135 stop the program directly without printing a
 136 .B groff
 137 command to standard output.
 138 .
 139 .
 140 .P
 141 All other specified short options (words starting with one minus
 142 character
 143 .BR \- )
 144 are interpreted as
 145 .B groff
 146 options or option clusters with or without argument.
 147 .
 148 No space is allowed between options and their argument.
 149 .
 150 Except from the
 151 .BI \-m arg
 152 options, all options will be passed on, i.e. they are included
 153 unchanged in the command for the output without effecting the work of
 154 .BR grog .
 155 .
 156 .
 157 .P
 158 A
 159 .I filespec
 160 argument can either be the name of an existing file or a single minus
 161 .B \-
 162 to mean standard input.
 163 .
 164 If no
 165 .I filespec
 166 is specified standard input is read automatically.
 167 .
 168 .
 169 .\" --------------------------------------------------------------------
 170 .SH DETAILS
 171 .
 172 .B grog
 173 reads all
 174 .I filespec
 175 parameters as a whole.
 176 .
 177 It tries to guess which of the following
 178 .B groff
 179 options are required for running the input under
 180 .BR groff :
 181 .BR \-e ,
 182 .BR \-man ,
 183 .BR \-me ,
 184 .BR \-mm ,
 185 .BR \-mom ,
 186 .BR \-ms ,
 187 .BR \-mdoc,
 188 .BR \-mdoc-old,
 189 .BR \-p ,
 190 .BR \-R ,
 191 .BR \-g ,
 192 .BR \-G ,
 193 .BR \-s ,
 194 and
 195 .BR \-t .
 196 The guessed
 197 .B groff
 198 command including those options and the found
 199 .I filespec
 200 parameters is put on the standard output.
 201 .
 202 .
 203 .P
 204 It is possible to specify arbitrary
 205 .B groff
 206 options on the command line.
 207 .
 208 These are passed on the output without change, except for the
 209 .BI \-m arg
 210 options.
 211 .
 212 .
 213 .P
 214 The
 215 .B groff
 216 program has trouble when the wrong
 217 .BI \-m arg
 218 option or several of these options are specified.
 219 .
 220 In these cases,
 221 .B grog
 222 will print an error message and exit with an error code.
 223 .
 224 It is better to specify no
 225 .BI \-m arg
 226 option.
 227 .
 228 Because such an option is only accepted and passed when
 229 .B grog
 230 does not find any of these options or the same option is found.
 231 .
 232 .
 233 .P
 234 If several different
 235 .BI \-m arg
 236 options are found by
 237 .B grog
 238 an error message is produced and the program is terminated with an
 239 error code.
 240 .
 241 But the output is written with the wrong options nevertheless.
 242 .
 243 .
 244 .P
 245 Remember that it is not necessary to determine a macro package.
 246 .
 247 A
 248 .I roff
 249 file can also be written in the
 250 .I groff
 251 language without any macro package.
 252 .
 253 .B grog
 254 will produce an output without an
 255 .BI \-m arg
 256 option.
 257 .
 258 .
 259 .P
 260 As
 261 .B groff
 262 also works with pure text files without any
 263 .I roff
 264 requests,
 265 .B grog
 266 cannot be used to identify a file to be a
 267 .I roff
 268 file.
 269 .
 270 .
 271 .P
 272 The
 273 .BR groffer  (@MAN1EXT@)
 274 program heavily depends on a working
 275 .BR grog .
 276 .
 277 .
 278 .P
 279 The
 280 .B grog
 281 source contains two files written in different programming languages:
 282 .
 283 .ft CB
 284 grog.pl
 285 .ft R
 286 is the
 287 .I Perl
 288 version, while
 289 .ft CB
 290 grog.sh
 291 .ft R
 292 is a shell script using
 293 BR awk (1).
 294 During the run of
 295 .BR make (1),
 296 it is determined whether the system contains a suitable version of
 297 .BR perl (1).
 298 If so,
 299 .ft CB
 300 grog.pl
 301 .ft R
 302 is transformed into
 303 .BR grog ;
 304 otherwise
 305 .ft CB
 306 grog.sh
 307 .ft R
 308 is used instead.
 309 .
 310 .
 311 .\" --------------------------------------------------------------------
 312 .SH EXAMPLES
 313 .
 314 .IP \(bu
 315 Calling
 316 .
 317 .RS
 318 .IP
 319 .EX
 320 grog meintro.me
 321 .EE
 322 .RE
 323 .
 324 .IP
 325 results in
 326 .
 327 .RS
 328 .IP
 329 .EX
 330 groff \-me meintro.me
 331 .EE
 332 .RE
 333 .
 334 .IP
 335 So
 336 .B grog
 337 recognized that the file
 338 .FN meintro.me
 339 is written with the
 340 .B \-me
 341 macro package.
 342 .RE
 343 .
 344 .
 345 .IP \(bu
 346 On the other hand,
 347 .
 348 .RS
 349 .IP
 350 .EX
 351 grog pic.ms
 352 .EE
 353 .RE
 354 .
 355 .IP
 356 outputs
 357 .
 358 .RS
 359 .IP
 360 .EX
 361 groff \-pte \-ms pic.ms
 362 .EE
 363 .RE
 364 .
 365 .IP
 366 Besides determining the macro package
 367 .BR \-ms ,
 368 .B grog
 369 recognized that the file
 370 .FN pic.ms
 371 additionally needs
 372 .BR \-pte ,
 373 the combination of
 374 .B \-p
 375 for
 376 .IR pic ,
 377 .B \-t
 378 for
 379 .IR tbl ,
 380 and
 381 .B \-e
 382 for
 383 .IR eqn .
 384 .RE
 385 .
 386 .
 387 .IP \(bu
 388 If both files are combined by the command
 389 .
 390 .RS
 391 .IP
 392 .EX
 393 grog meintro.me pic.ms
 394 .EE
 395 .RE
 396 .
 397 .IP
 398 an error message is sent to standard error because
 399 .B groff
 400 cannot work with two different macro packages:
 401 .
 402 .RS
 403 .IP
 404 .ft CR
 405 grog: error: there are several macro packages: -me -ms
 406 .ft
 407 .RE
 408 .
 409 .IP
 410 Additionally the corresponding output with the wrong options is printed
 411 to standard output:
 412 .
 413 .RS
 414 .IP
 415 .EX
 416 groff -pte -me -ms meintro.me pic.ms
 417 .EE
 418 .RE
 419 .
 420 .IP
 421 But the program is terminated with an error code.
 422 .
 423 .
 424 .IP \(bu
 425 The call of
 426 .
 427 .RS
 428 .IP
 429 .EX
 430 grog \-ksS \-Tdvi grnexmpl.g
 431 .EE
 432 .RE
 433 .
 434 .IP
 435 contains several
 436 .B groff
 437 options that are just passed on the output without any interface to
 438 .BR grog .
 439 These are the option cluster
 440 .B \-ksS
 441 consisting of
 442 .BR \-k ,
 443 .BR \-s ,
 444 and
 445 .BR \-S ;
 446 and the option
 447 .B \-T
 448 with argument
 449 .BR dvi .
 450 The output is
 451 .
 452 .RS
 453 .IP
 454 .EX
 455 groff \-ksS \-Tdvi grnexmpl.g
 456 .EE
 457 .RE
 458 .
 459 .IP
 460 so no additional option was added by
 461 .BR grog .
 462 As no option
 463 .BI \-m arg
 464 was found by
 465 .B grog
 466 this file does not use a macro package.
 467 .
 468 .
 469 .IP \(bu
 470 .B grog
 471 can also handle files using the
 472 .I chem
 473 language.
 474 .
 475 The example
 476 .
 477 .RS
 478 .IP
 479 .EX
 480 grog chAh_brackets.chem
 481 .EE
 482 .RE
 483 .
 484 .IP
 485 outputs
 486 .
 487 .RS
 488 .IP
 489 .EX
 490 chem chAh_brackets.chem | groff \-pe
 491 .EE
 492 .RE
 493 .
 494 .IP
 495 So
 496 .B chem
 497 is run first and
 498 .B groff
 499 is appended.
 500 .
 501 The option
 502 .B \-p
 503 for
 504 .B pic
 505 is implied automatically by
 506 .BR chem .
 507 Additionally, the file uses
 508 .I eqn
 509 with
 510 .BR \-e .
 511 .
 512 .
 513 .\" --------------------------------------------------------------------
 514 .SH "SEE ALSO"
 515 .
 516 .BR groff (@MAN1EXT@),
 517 .BR @g@troff (@MAN1EXT@),
 518 .BR @g@tbl (@MAN1EXT@),
 519 .BR @g@pic (@MAN1EXT@),
 520 .BR @g@eqn (@MAN1EXT@),
 521 .BR @g@refer (@MAN1EXT@),
 522 .BR @g@grn (@MAN1EXT@),
 523 .BR grap (1),
 524 .BR @g@soelim (@MAN1EXT@),
 525 .BR groff_me (@MAN7EXT@),
 526 .BR groff_ms (@MAN7EXT@),
 527 .BR groff_mm (@MAN7EXT@),
 528 .BR groff_mom (@MAN7EXT@),
 529 .BR groff_man (@MAN7EXT@),
 530 .BR groffer (@MAN1EXT@)
 531 .
 532 .
 533 .\" --------------------------------------------------------------------
 534 .SH "COPYING"
 535 .
 536 .co
 537 .
 538 .
 539 .\" --------------------------------------------------------------------
 540 .\" Emacs settings
 541 .\" --------------------------------------------------------------------
 542 .
 543 .\" Local Variables:
 544 .\" mode: nroff
 545 .\" End: