src/roff/grog/grog.man

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