contrib/gperl/gperl.1.man

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