contrib/gperl/gperl.man

   1 .TH GPERL @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
   2 .SH NAME
   3 gperl \- groff preprocessor for Perl parts in roff files
   4 .
   5 .\" The .SH was moved to this place in order to appease `apropos'.
   6 .
   7 .\" --------------------------------------------------------------------
   8 .\" Legalese
   9 .\" --------------------------------------------------------------------
  10 .
  11 .de au
  12 This file was written by
  13 .MT groff-bernd.warken-72@web.de
  14 Bernd Warken
  15 .ME .
  16 ..
  17 .
  18 .de co
  19 Copyright \[co] 2014 Free Software Foundation, Inc.
  20 .
  21 .P
  22 This file is part of
  23 .IR \%gperl ,
  24 which is part of
  25 .IR \%groff ,
  26 a free software project.
  27 .
  28 You can redistribute it and/or modify it under the terms of the
  29 .nh
  30 .B "GNU General Public License"
  31 .hy
  32 as published by the
  33 .nh
  34 .BR "Free Software Foundation" ,
  35 .hy
  36 version\~2.
  37 .
  38 .P
  39 The license text is available in the internet at
  40 .UR http://www.gnu.org/licenses/gpl-2.0.html
  41 .UE .
  42 ..
  43 .
  44 .\" --------------------------------------------------------------------
  45 .\" Characters
  46 .\" --------------------------------------------------------------------
  47 .
  48 .\" Ellipsis ...
  49 .ie t .ds EL \fS\N'188'\fP
  50 .el .ds EL \&.\|.\|.\&\
  51 .\" called with \*(EL
  52 .
  53 .\" Bullet
  54 .ie t .ds BU \[bu]
  55 .el .ds BU *
  56 .\" used in `.IP \*(BU 2m' (former .Topic)
  57 .
  58 .
  59 .\" --------------------------------------------------------------------
  60 .SH "SYNOPSIS"
  61 .\" --------------------------------------------------------------------
  62 .
  63 .SY gperl
  64 .OP \-
  65 .OP \-\-
  66 .OP \& "\%filespec \*(EL"
  67 .YS
  68 .
  69 .BR "gperl -h" | --help
  70 .br
  71 .BR "gperl -v" | --version
  72 .
  73 .
  74 .\" --------------------------------------------------------------------
  75 .SH DESCRIPTION
  76 .\" --------------------------------------------------------------------
  77 .
  78 This is a preprocesor for
  79 .BR \%groff (@MAN1EXT@).
  80 .
  81 It allows to add
  82 .BR perl (7)
  83 code into
  84 .BR groff (7)
  85 files.
  86 .
  87 The result of a
  88 .I Perl part
  89 can be stored in groff
  90 .I strings
  91 or
  92 .I numerical registers
  93 based on the arguments at a final line of a
  94 .IR "Perl part" .
  95 .
  96 .
  97 .\" --------------------------------------------------------------------
  98 .SH "OPTIONS"
  99 .\" --------------------------------------------------------------------
 100 .
 101 So far, there are only
 102 .I filespec
 103 or
 104 .I breaking
 105 options.
 106 .
 107 .
 108 .P
 109 .I filespec
 110 are file names or the minus character
 111 .B \-
 112 character for standard input.
 113 .
 114 As usual, the argument
 115 .B \-\-
 116 can be used in order to let all fowllowing arguments mean file names,
 117 even if the names begin with a minus character
 118 .BR \- .
 119 .
 120 .
 121 .P
 122 An option is
 123 .IR breaking ,
 124 when the program just writes the information that was asked for and
 125 then stops.
 126 .
 127 All other arguments will be ignored by that.
 128 .
 129 These
 130 .I breaking
 131 options are heree
 132 .
 133 .TP
 134 .B -h\~\fR|\fB\~--help
 135 Print help information with a short explanation of options to
 136 standard output.
 137 .
 138 .
 139 .TP
 140 .B -v\~\fR|\fB\~--version
 141 Print version information to standard output.
 142 .
 143 .
 144 .\" --------------------------------------------------------------------
 145 .SH "PERL PARTS"
 146 .\" --------------------------------------------------------------------
 147 .
 148 .I Perl
 149 parts in
 150 .I groff files
 151 are enclosed by two
 152 .B .Perl
 153 requests with different arguments, a
 154 .I starting
 155 and an
 156 .I ending
 157 command.
 158 .
 159 .
 160 .\" --------------------------------------------------------------------
 161 .SS "Starting Perl Mode"
 162 .\" --------------------------------------------------------------------
 163 .
 164 The starting
 165 .I Perl request
 166 can either be without arguments, or by a request that has the term
 167 .B start
 168 as its only argument.
 169 .RS
 170 .IP \*(BU 2m
 171 .B \&.Perl
 172 .IP \*(BU 2m
 173 .B \&.Perl start
 174 .RE
 175 .
 176 .
 177 .\" --------------------------------------------------------------------
 178 .SS "Ending Perl Mode without Storage"
 179 .\" --------------------------------------------------------------------
 180 .
 181 A
 182 .B .Perl
 183 command line with an argument different from
 184 .B start
 185 finishes a running
 186 .IR "Perl part" .
 187 .
 188 Of course, it would be reasonable to add the argument
 189 .BR stop ;
 190 that's possible, but not necessary.
 191 .
 192 .RS
 193 .IP \*(BU 2m
 194 .B \&.Perl stop
 195 .IP \*(BU 2m
 196 .BI \&.Perl " other_than_start"
 197 .RE
 198 .
 199 The argument
 200 .I other_than_start
 201 can additionally be used as a
 202 .I groff
 203 string variable name for storage \[em] see next section.
 204 .
 205 .
 206 .\" --------------------------------------------------------------------
 207 .SS "Ending Perl Mode with Storage"
 208 .\" --------------------------------------------------------------------
 209 .
 210 A useful feature of
 211 .B gperl
 212 is to store one or more results from the
 213 .IR "Perl mode" .
 214 .
 215 .
 216 .P
 217 The output of a
 218 .I Perl part
 219 can be got with backticks
 220 .BR `...` .
 221 .
 222 .
 223 .P
 224 This program collects all printing to STDOUT (normal standard output)
 225 by the Perl
 226 .B print
 227 program.
 228 .
 229 This pseudo-printing output can have several lines, due to printed
 230 line breaks with
 231 .BR \[rs]n .
 232 .
 233 By that, the output of a Perl run should be stored into a Perl array,
 234 with a single line for each array member.
 235 .
 236 .
 237 .P
 238 This Perl array output can be stored by
 239 .B gperl
 240 in either
 241 .TP
 242 .I groff strings
 243 by creating a groff command
 244 .B .ds
 245 .
 246 .TP
 247 .I groff number register
 248 by creating a groff command
 249 .B .rn
 250 .
 251 .
 252 .P
 253 The storage modes can be determined by arguments of a final stopping
 254 .B .Perl
 255 command.
 256 .
 257 Each argument
 258 .B .ds
 259 changes the mode into
 260 .I groff string
 261 and
 262 .B .nr
 263 changes the mode into
 264 .I groff number register
 265 for all following output parts.
 266 .
 267 .
 268 .P
 269 By default, all output is saved as strings, so
 270 .B .ds
 271 is not really needed before the first
 272 .B .nr
 273 command.
 274 .
 275 That suits to
 276 .BR \%groff (@MAN7EXT@),
 277 because every output can be saved as
 278 .I groff
 279 string, but the number registers can be very restrictive.
 280 .
 281 .
 282 .P
 283 In
 284 .IR "string mode" ,
 285 .B gperl
 286 generates a
 287 .I groff string
 288 storage line
 289 .RS
 290 .EX
 291 \&\fB.ds \fIvar_name content
 292 .EE
 293 .RE
 294 .
 295 In
 296 .I number register mode
 297 the following groff command is generated
 298 .RS
 299 .EX
 300 \&\fB.nr \fIvar_name content
 301 .EE
 302 .RE
 303 .
 304 .
 305 .P
 306 We present argument collections in the following.
 307 .
 308 You can add as first argument for all
 309 .BR stop .
 310 .
 311 We omit this additional element.
 312 .
 313 .
 314 .P
 315 .TP
 316 .BI ".Perl .ds " var_name
 317 This will store 1 output line into the groff string named
 318 .I var_name
 319 by the automatically created command
 320 .RS
 321 .RS
 322 .EX
 323 .BI .ds " var_name output"
 324 .EE
 325 .RE
 326 .RE
 327 .
 328 .
 329 .TP
 330 .BI .Perl " var_name"
 331 If
 332 .I var_name
 333 is different from
 334 .B start
 335 this is equivalent to the former command, because the string mode is
 336 string with
 337 .B .ds
 338 command.
 339 default.
 340 .
 341 .
 342 .TP
 343 .BI .Perl " var_name1 var_name2"
 344 This will store 2 output lines into groff string names
 345 .I var_name1
 346 and
 347 .IR var_name2 ,
 348 because the default mode
 349 .B .ds
 350 is active, such that no
 351 .B .ds
 352 argument is needed.
 353 .
 354 Of course, this is equivalent to
 355 .RS
 356 .RS
 357 .EX
 358 .BI ".Perl .ds " "var_name1 var_name2"
 359 .EE
 360 .RE
 361 and
 362 .RS
 363 .EX
 364 .BI ".Perl .ds " "var_name1 " ".ds" " var_name2"
 365 .EE
 366 .RE
 367 .RE
 368 .
 369 .
 370 .TP
 371 .BI ".Perl .nr" " var_name1 varname2"
 372 stores both variables as number register variables.
 373 .
 374 .B gperl
 375 generates
 376 .RS
 377 .EX
 378 .BI .nr " var_name1 output_line1"
 379 .BI .nr " var_name2 output_line2"
 380 .EE
 381 .RE
 382 .
 383 .
 384 .TP
 385 .BI ".Perl .nr " var_name1 " .ds " var_name2
 386 stores the 1st argument as
 387 .I number register
 388 and the second as
 389 .I string
 390 by
 391 .RS
 392 .EX
 393 .BI .nr " var_name1 output_line1"
 394 .BI .ds " var_name2 output_line2"
 395 .EE
 396 .RE
 397 .
 398 .
 399 .\" --------------------------------------------------------------------
 400 .SS "Printing towards STDERR is without Storage"
 401 .\" --------------------------------------------------------------------
 402 .
 403 The printing towards
 404 .IR STDERR ,
 405 (standard error) works as usual.
 406 .
 407 All error information goes to the real normal
 408 .IR "standard error" ,
 409 without other automatical storage.
 410 .
 411 .
 412 .\" --------------------------------------------------------------------
 413 .SH "EXAMPLES"
 414 .\" --------------------------------------------------------------------
 415 .
 416 A possible
 417 .I Perl part
 418 in a
 419 .I roff file
 420 could look like that:
 421 .RS
 422 .EX
 423 before
 424 \&.Perl start
 425 my $result = 'some data';
 426 print $result;
 427 \&.Perl stop .ds string_var
 428 after
 429 .EE
 430 .RE
 431 .
 432 .
 433 .P
 434 This stores the result
 435 .B \[rq]some data\[rq]
 436 into the
 437 .I roff string
 438 called
 439 .BR string_var ,
 440 such that the following line is printed:
 441 .RS
 442 .EX
 443 \&.ds string_var some data
 444 .EE
 445 .RE
 446 by
 447 .B gperl
 448 as food for the coming
 449 .B groff
 450 run.
 451 .
 452 .
 453 .P
 454 A
 455 .I Perl part
 456 with several outputs is:
 457 .RS
 458 .EX
 459 \&.Perl start
 460 print \[rq]first\[rs]n\[rq];
 461 print \[rq]second line\[rs]n\[rq];
 462 print \[rq]3\[rs]n\[rq];
 463 \&.Perl var1 var2 .nr var3
 464 .EE
 465 .RE
 466 .
 467 This stores 3 printed lines into 3
 468 .I groff
 469 strings.
 470 .BR var1 , var2 , var3 .
 471 .
 472 So the following
 473 .I groff
 474 command lines are created:
 475 .RS
 476 .EX
 477 \&.ds var1 first
 478 \&.ds var2 second line
 479 \&.nr var3 3
 480 .EE
 481 .RE
 482 .
 483 .
 484 .\" --------------------------------------------------------------------
 485 .SH "SEE ALSO"
 486 .\" --------------------------------------------------------------------
 487 .
 488 .P
 489 Man\-pages related to
 490 .I groff
 491 are
 492 .BR \%groff (@MAN1EXT@),
 493 .BR \%groff (@MAN7EXT@),
 494 .BR \%grog (@MAN1EXT@),
 495 and
 496 .BR \%groffer (@MAN1EXT@).
 497 .
 498 .
 499 .P
 500 Documents related to
 501 .I Perl
 502 are
 503 .BR \%perl (@MAN1EXT@),
 504 .BR \%perl (@MAN7EXT@).
 505 .
 506 .
 507 .\" --------------------------------------------------------------------
 508 .SH "COPYING"
 509 .\" --------------------------------------------------------------------
 510 .co
 511 .\" --------------------------------------------------------------------
 512 .SH "AUTHORS"
 513 .\" --------------------------------------------------------------------
 514 .au
 515 .
 516 .
 517 .\" --------------------------------------------------------------------
 518 .\" Emacs settings
 519 .\" --------------------------------------------------------------------
 520 .
 521 .\" Local Variables:
 522 .\" mode: nroff
 523 .\" End: