src/roff/grog/grog.1.man

   1 .TH GROG @MAN1EXT@ "@MDATE@" "groff @VERSION@"
   2 .SH NAME
   3 grog \- guess options for a following groff command
   4 .
   5 .\" grog.man -> grog.1 - man page for grog (section 1)
   6 .\" Source file position:  <groff_source_top>/src/roff/grog/grog.man
   7 .\" Installed position:    <prefix>/share/man/man1/grog.1
   8 .
   9 .\" TODO: This page needs a thorough edit by a native English speaker.
  10 .
  11 .\" ====================================================================
  12 .\" Legal Terms
  13 .\" ====================================================================
  14 .\"
  15 .\" Copyright (C) 1989-2018 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
  19 .\" of the GNU General Public License version 2 (GPL2) as published by
  20 .\" the 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
  24 .\" or FITNESS FOR A PARTICULAR PURPOSE.
  25 .\"
  26 .\" The text for GPL2 is available in the internet at
  27 .\" <http://www.gnu.org/licenses/gpl2.0.txt>.
  28 .
  29 .
  30 .\" ====================================================================
  31 .\" Characters
  32 .\" ====================================================================
  33 .
  34 .\" Ellipsis ...
  35 .ie t .ds EL \fS\N'188'\fP\"
  36 .el .ds EL \&.\|.\|.\&\"
  37 .\" called with \*(EL
  38 .
  39 .\" ====================================================================
  40 .SH SYNOPSIS
  41 .\" ====================================================================
  42 .
  43 .SY grog
  44 .OP \-C
  45 .OP \-T device
  46 .OP \-\-run
  47 .OP \-\-warnings
  48 .OP \-\-ligatures
  49 .RI [ groff-option
  50 \*(EL]
  51 .OP \-\-
  52 .RI [ filespec
  53 \*(EL]
  54 .YS
  55 .
  56 .SY grog
  57 .B \-h
  58 .SY grog
  59 .B \-\-help
  60 .YS
  61 .
  62 .SY grog
  63 .B \-v
  64 .SY grog
  65 .B \-\-version
  66 .YS
  67 .
  68 .
  69 .\" ====================================================================
  70 .SH DESCRIPTION
  71 .\" ====================================================================
  72 .
  73 .B grog
  74 reads the input (file names or standard input) and guesses which of
  75 the
  76 .BR groff (@MAN1EXT@)
  77 options are needed to perform the input with the
  78 .B groff
  79 program.
  80 .
  81 A suitable device is now always written as
  82 .BI \-T device
  83 including the groff default as
  84 .BR "\-T ps" .
  85 .
  86 .
  87 .P
  88 The corresponding
  89 .B groff
  90 command is usually displayed in standard output.
  91 .
  92 With the option
  93 .BR \-\-run ,
  94 the generated line is output into standard error and the generated
  95 .B groff
  96 command is run on the
  97 .IR "standard output" .
  98 .
  99 .BR groffer (@MAN1EXT@)
 100 relies on a perfectly running
 101 .BR groff (@MAN1EXT@).
 102 .
 103 .
 104 .\" ====================================================================
 105 .SH OPTIONS
 106 .\" ====================================================================
 107 .
 108 The option
 109 .B \-v
 110 or
 111 .B \-\-version
 112 prints information on the version number.
 113 .
 114 Also
 115 .B \-h
 116 or
 117 .B \-\-help
 118 prints usage information.
 119 .
 120 Both of these options automatically end the
 121 .B grog
 122 program.
 123 .
 124 Other options are thenignored, and no
 125 .B groff
 126 command line is generated.
 127 .
 128 .
 129 The following 3 options are the only
 130 .B grog
 131 options,
 132 .
 133 .TP
 134 .B \-C
 135 this option means enabling the
 136 .I groff
 137 compatibility mode, which is also transfered to the generated
 138 .B groff
 139 command line.
 140 .
 141 .TP
 142 .B \-\-ligatures
 143 this option forces to include the arguments
 144 .B \-P\-y \-PU
 145 within the generated
 146 .B groff
 147 command line.
 148 .
 149 .TP
 150 .B \-\-run
 151 with this option, the command line is output at standard error and
 152 then run on the computer.
 153 .
 154 .TP
 155 .B \-\-warnings
 156 with this option, some more warnings are output to standard error.
 157 .
 158 .
 159 .P
 160 All other specified short options (words starting with one minus
 161 character
 162 .BR \- )
 163 are interpreted as
 164 .B groff
 165 options or option clusters with or without argument.
 166 .
 167 No space is allowed between options and their argument.
 168 .
 169 Except from the
 170 .BI \-m arg
 171 options, all options will be passed on, i.e.\& they are included
 172 unchanged in the command for the output without effecting the work of
 173 .BR grog .
 174 .
 175 .
 176 .P
 177 A
 178 .I filespec
 179 argument can either be the name of an existing file or a single minus
 180 .B \-
 181 to mean standard input.
 182 .
 183 If no
 184 .I filespec
 185 is specified standard input is read automatically.
 186 .
 187 .
 188 .\" ====================================================================
 189 .SH DETAILS
 190 .\" ====================================================================
 191 .
 192 .B grog
 193 reads all
 194 .I filespec
 195 parameters as a whole.
 196 .
 197 It tries to guess which of the following
 198 .B groff
 199 options are required for running the input under
 200 .BR groff :
 201 .BR \-e ,
 202 .BR \-g ,
 203 .BR \-G ,
 204 .BR \-j ,
 205 .\" gideal is not implemented yet.
 206 .\" .BR \-J ,
 207 .BR \-p ,
 208 .BR \-R ,
 209 .BR \-s ,
 210 .B \-t
 211 (preprocessors); and
 212 .BR \-man ,
 213 .BR \-mdoc ,
 214 .BR \-mdoc\-old ,
 215 .BR \-me ,
 216 .BR \-mm ,
 217 .BR \-mom ,
 218 and
 219 .B \-ms
 220 (macro packages).
 221 .
 222 .
 223 .P
 224 The guessed
 225 .B groff
 226 command including those options and the found
 227 .I filespec
 228 parameters is put on the standard output.
 229 .
 230 .
 231 .P
 232 It is possible to specify arbitrary
 233 .B groff
 234 options on the command line.
 235 .
 236 These are passed on the output without change, except for the
 237 .BI \-m arg
 238 options.
 239 .
 240 .
 241 .P
 242 The
 243 .B groff
 244 program has trouble when the wrong
 245 .BI \-m arg
 246 option or several of these options are specified.
 247 .
 248 In these cases,
 249 .B grog
 250 will print an error message and exit with an error code.
 251 .
 252 It is better to specify no
 253 .BI \-m arg
 254 option.
 255 .
 256 Because such an option is only accepted and passed when
 257 .B grog
 258 does not find any of these options or the same option is found.
 259 .
 260 .
 261 .P
 262 If several different
 263 .BI \-m arg
 264 options are found by
 265 .B grog
 266 an error message is produced and the program is terminated with an
 267 error code.
 268 .
 269 But the output is written with the wrong options nevertheless.
 270 .
 271 .
 272 .P
 273 Remember that it is not necessary to determine a macro package.
 274 .
 275 A
 276 .I roff
 277 file can also be written in the
 278 .I groff
 279 language without any macro package.
 280 .
 281 .B grog
 282 will produce an output without an
 283 .BI \-m arg
 284 option.
 285 .
 286 .
 287 .P
 288 As
 289 .B groff
 290 also works with pure text files without any
 291 .I roff
 292 requests,
 293 .B grog
 294 cannot be used to identify a file to be a
 295 .I roff
 296 file.
 297 .
 298 .
 299 .P
 300 The
 301 .BR groffer  (@MAN1EXT@)
 302 program heavily depends on a working
 303 .BR grog .
 304 .
 305 .
 306 .\" ====================================================================
 307 .SH EXAMPLES
 308 .\" ====================================================================
 309 .
 310 Calling
 311 .RS
 312 .EX
 313 grog meintro.me
 314 .EE
 315 .RE
 316 results in
 317 .RS
 318 .EX
 319 groff \-me meintro.me
 320 .EE
 321 .RE
 322 .
 323 So
 324 .B grog
 325 recognized that the file
 326 .B meintro.me
 327 is written with the
 328 .B \-me
 329 macro package.
 330 .RE
 331 .
 332 .
 333 On the other hand,
 334 .RS
 335 .EX
 336 grog pic.ms
 337 .EE
 338 .RE
 339 .
 340 outputs
 341 .
 342 .RS
 343 .EX
 344 groff \-p \-t \-e \-ms pic.ms
 345 .EE
 346 .RE
 347 .
 348 Besides determining the macro package
 349 .BR \-ms ,
 350 .B grog
 351 recognized that the file
 352 .B pic.ms
 353 additionally needs
 354 .BR \-pte ,
 355 the combination of
 356 .B \-p
 357 for
 358 .IR pic ,
 359 .B \-t
 360 for
 361 .IR tbl ,
 362 and
 363 .B \-e
 364 for
 365 .IR eqn .
 366 .RE
 367 .
 368 .
 369 If both of the former example files are combined by the command
 370 .
 371 .RS
 372 .EX
 373 grog meintro.me pic.ms
 374 .EE
 375 .RE
 376 .
 377 an error message is sent to standard error because
 378 .B groff
 379 cannot work with two different macro packages:
 380 .
 381 .RS
 382 .ft CR
 383 grog: error: there are several macro packages: \-me \-ms
 384 .ft
 385 .RE
 386 .
 387 Additionally the corresponding output with the wrong options is printed
 388 to standard output:
 389 .
 390 .RS
 391 .EX
 392 groff \-pte \-me \-ms meintro.me pic.ms
 393 .EE
 394 .RE
 395 .
 396 But the program is terminated with an error code.
 397 .
 398 .
 399 The call of
 400 .
 401 .RS
 402 .EX
 403 grog \-ksS \-Tdvi grnexmpl.g
 404 .EE
 405 .RE
 406 .
 407 contains several
 408 .B groff
 409 options that are just passed on the output without any interface to
 410 .BR grog .
 411 These are the option cluster
 412 .B \-ksS
 413 consisting of
 414 .BR \-k ,
 415 .BR \-s ,
 416 and
 417 .BR \-S ;
 418 and the option
 419 .B \-T
 420 with argument
 421 .BR dvi .
 422 The output is
 423 .
 424 .RS
 425 .EX
 426 groff \-k \-s \-S \-Tdvi grnexmpl.g
 427 .EE
 428 .RE
 429 .
 430 so no additional option was added by
 431 .BR grog .
 432 As no option
 433 .BI \-m arg
 434 was found by
 435 .B grog
 436 this file does not use a macro package.
 437 .
 438 .
 439 .\" ====================================================================
 440 .SH AUTHORS
 441 .\" ====================================================================
 442 .B grog
 443 was originally written by James Clark.
 444 .
 445 The current Perl implementation was written by
 446 .MT groff\-bernd.warken\-72@\:web.de
 447 Bernd Warken
 448 .ME
 449 with contributions from Ralph Corderoy,
 450 and is maintained by
 451 .MT wl@\:gnu.org
 452 Werner Lemberg
 453 .ME .
 454 .
 455 .
 456 .\" ====================================================================
 457 .SH "SEE ALSO"
 458 .\" ====================================================================
 459 .
 460 .BR groff (@MAN1EXT@),
 461 .BR groffer (@MAN1EXT@)
 462 .
 463 .
 464 .\" ====================================================================
 465 .\" Emacs settings
 466 .\" ====================================================================
 467 .
 468 .\" Local Variables:
 469 .\" mode: nroff
 470 .\" End:
 471 .\" vim: set filetype=groff: