contrib/gperl/gperl.1.man

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