contrib/groff_filenames/groff_filenames.5.man

   1 .TH GROFF_FILENAMES @MAN5EXT@ "@MDATE@" "groff @VERSION@"
   2 .SH NAME
   3 groff_filenames \- filename extensions for roff and groff
   4 .
   5 .\" ad l
   6 .\" ====================================================================
   7 .\" Legal Terms
   8 .\" ====================================================================
   9 .\"
  10 .\" Copyright (C) 2013-2018 Free Software Foundation, Inc.
  11 .\"
  12 .\" This file is part of groff, a free software project.  You can
  13 .\" redistribute it and/or modify it under the terms of the GNU General
  14 .\" Public License version 2 (GPL2) as published by the Free Software
  15 .\" Foundation (FSF).
  16 .\"
  17 .\" The license text can be found in the internet at
  18 .\" <http://www.gnu.org/licenses>.
  19 .
  20 .
  21 .\" ====================================================================
  22 .SH DESCRIPTION
  23 .\" ====================================================================
  24 .
  25 Since the evolution of
  26 .I roff
  27 in the 1970s, a whole bunch of filename extensions for
  28 .I roff
  29 files were used.
  30 .
  31 .
  32 .P
  33 The
  34 .I roff
  35 extensions refer to preprocessors or macro packages.
  36 .
  37 These extensions are fixed in all
  38 .IR Unix \-like
  39 operating systems.
  40 .
  41 .
  42 .P
  43 Later on,
  44 .B groff
  45 added some more extensions.
  46 .
  47 This
  48 .I man page
  49 is about these filename extensions.
  50 .
  51 .
  52 .\" ====================================================================
  53 .SH COMPRESSION OF ROFF FILES
  54 .\" ====================================================================
  55 .
  56 Each
  57 .I roff
  58 file can be optionally
  59 .IR compressed .
  60 .
  61 That means that the
  62 .I total filename
  63 ends with a
  64 .IR "compressor name" .
  65 .
  66 So the whole filename has the structure
  67 .IR <name> . <extension>[ . <compression>] .
  68 .
  69 .
  70 .P
  71 Best-known are the
  72 .I compressor extensions
  73 .BR .Z ,
  74 .BR .gz ,
  75 and
  76 .BR .bzip2 .
  77 .
  78 Relatively new is
  79 .BR .xz .
  80 .
  81 .
  82 .P
  83 From now on, we will ignore the
  84 .I compressions
  85 and only comment the structure
  86 .IB <name> . <extension>\fR.\fP
  87 .
  88 .
  89 .\" ====================================================================
  90 .SH MAN PAGES
  91 .\" ====================================================================
  92 .
  93 The
  94 .I Unix manual pages
  95 are widely called
  96 .IR "man pages" .
  97 .
  98 The
  99 .I man page
 100 style is the best known part of the
 101 .I roff
 102 language.
 103 .
 104 .
 105 .P
 106 The extensions for
 107 .I man
 108 should be better documented.
 109 .
 110 So this is documented here.
 111 .
 112 .
 113 .P
 114 Files written in the
 115 .I man
 116 language use the following extension:
 117 .BI *. <section>[<group>] \fR.\fP
 118 .
 119 .
 120 .\" ====================================================================
 121 .SS Man page Sections
 122 .\" ====================================================================
 123 .
 124 The traditional
 125 .I man page <section>
 126 is a digit from
 127 .B 1
 128 to
 129 .BR 8 .
 130 .
 131 .
 132 .TP
 133 .IB <name> .1
 134 .TQ
 135 .IB <name> .2
 136 .TQ
 137 .IB <name> .3
 138 .TQ
 139 .IB <name> .4
 140 .TQ
 141 .IB <name> .5
 142 .TQ
 143 .IB <name> .6
 144 .TQ
 145 .IB <name> .7
 146 .TQ
 147 .IB <name> .8
 148 Classic man page
 149 .IR sections .
 150 .
 151 .
 152 .P
 153 .\" NOTE: There was once a feeble attempt in this direction, but it
 154 .\" hasn't been true in any sense for a long time.
 155 .\"Linux added the section number
 156 .\".B 9
 157 .\"for kernel man pages.
 158 .\".
 159 .\".
 160 .\".TP
 161 .\".IB <name> .9
 162 .\".I Linux
 163 .\"kernel man pages
 164 .\".
 165 .\".
 166 .P
 167 In older commercial
 168 .I Unix
 169 systems, the 3 characters
 170 .BR l ,
 171 .BR n ,
 172 and
 173 .B o
 174 were also used as
 175 .I section
 176 names.
 177 .
 178 This is today
 179 .IR deprecated ,
 180 but there are still documents in this format.
 181 .
 182 .
 183 .TP
 184 .IB <name> .l
 185 .TQ
 186 .IB <name> .n
 187 .TQ
 188 .IB <name> .o
 189 .I Deprecated
 190 man page sections, which stood for \[lq]local\[rq], \[lq]new\[rq], and
 191 \[lq]old\[rq], respectively.
 192 .
 193 .
 194 .\" ====================================================================
 195 .SS Man page Group Extensions
 196 .\" ====================================================================
 197 .
 198 The
 199 .I <group>
 200 extension in
 201 .BI . <section>[<group>]
 202 is optional, but it can be any string of word characters.
 203 .
 204 Usually programmers use a group name that is already used, e.g.\&
 205 .B x
 206 for
 207 X Window System
 208 documents or
 209 .B tcl
 210 to refer to the
 211 .I Tcl
 212 programming language.
 213 .
 214 .
 215 .P
 216 Examples:
 217 .
 218 .
 219 .TP
 220 .B groff.1
 221 is the man page for
 222 .B groff
 223 in
 224 .I section
 225 .B 1
 226 without a
 227 .I group
 228 .
 229 .
 230 .TP
 231 .B xargs.1posix.gz
 232 is the man page for the program
 233 .B xargs
 234 in
 235 .I section
 236 .B 1
 237 and
 238 .I group
 239 .BR posix ;
 240 moreover it is
 241 .I compressed
 242 with
 243 .B gz
 244 .RB ( gzip ).
 245 .
 246 .
 247 .TP
 248 .B config.5ssl
 249 .I "OpenSSL CONF"
 250 library configuration files from
 251 .I section
 252 .B 5
 253 with
 254 .I group
 255 .BR ssl .
 256 .
 257 .
 258 .TP
 259 .B dpkg\-reconfigure.8cdebconf
 260 man page for the program
 261 .B dpkg\-reconfigure
 262 in
 263 .I section
 264 .B 8
 265 and
 266 .I group
 267 .BR cdebconf .
 268 .
 269 .
 270 .\" ====================================================================
 271 .SS Source of man pages
 272 .\" ====================================================================
 273 .
 274 There are 2
 275 .I roff
 276 languages for writing man pages:
 277 .B man
 278 and
 279 .BR mdoc .
 280 .
 281 .
 282 .P
 283 The names of these 2 styles are taken as
 284 .I extensions
 285 for the source code files of man pages in the
 286 .I groff
 287 package.
 288 .
 289 .
 290 .TP
 291 .IB <name> .man
 292 .I traditional
 293 Unix-like man page format within groff source files.
 294 .
 295 .
 296 .TP
 297 .IB <name> . n
 298 A temporary man page file produced from a
 299 .IB name .man
 300 man page by a run of
 301 .B make
 302 within the
 303 .B groff
 304 source package.
 305 .
 306 .
 307 .TP
 308 .IB <name> .mdoc
 309 Man page format in BSD.
 310 .
 311 .
 312 .TP
 313 .IB <name> .1b
 314 Man page format in
 315 .IR "heirloom roff ".
 316 .
 317 .
 318 .TP
 319 .IB <name> .mandoc
 320 Files using this extension recognize both man page formats in
 321 .B groff
 322 and other processors.
 323 .
 324 .
 325 .\" ====================================================================
 326 .SH TRADITIONAL TROFF EXTENSIONS
 327 .\" ====================================================================
 328 .
 329 .\" ====================================================================
 330 .SS Files Using Macro Packages
 331 .\" ====================================================================
 332 .
 333 The
 334 .I "classical roff"
 335 languages were interpreted by the traditional
 336 .B "troff"
 337 and
 338 .B "nroff"
 339 programs.
 340 .
 341 .
 342 .P
 343 There were several
 344 .I roff
 345 languages, each represented by a
 346 .IR "macro-package" .
 347 .
 348 Each of these provided a suitable file name
 349 .IR extension :
 350 .
 351 .
 352 .TP
 353 .IB <name> .me
 354 .I roff
 355 file using the
 356 .B me
 357 .IR "macro package" .
 358 .
 359 .
 360 .TP
 361 .IB <name> .mm
 362 .I roff
 363 file using the
 364 .B mm
 365 .I macro package
 366 .
 367 .
 368 .TP
 369 .IB <name> .ms
 370 .I roff
 371 file using the
 372 .B ms
 373 .I macro package
 374 .
 375 .
 376 .P
 377 All of these classical
 378 .I roff
 379 languages and their extensions are still very active in
 380 .BR groff .
 381 .
 382 .
 383 .\" ====================================================================
 384 .SS Source Code for Macro Packages (TMAC Files)
 385 .\" ====================================================================
 386 .
 387 In traditional
 388 .I roff
 389 the source code for the macro packages was stored in
 390 .I TMAC
 391 files.
 392 .
 393 Their file names have the form:
 394 .
 395 .
 396 .TP
 397 .BI tmac. <package> \fR,\fP
 398 .I <package>
 399 is the name of the macro package without the leading
 400 .B m
 401 character, which is reintegrated by the option
 402 .BR -m .
 403 .
 404 .
 405 .P
 406 For example,
 407 .B tmac.an
 408 is the source for the
 409 .B man
 410 macro package.
 411 .
 412 .
 413 .P
 414 In the
 415 .B groff
 416 source, more suitable file names were integrated, see later on.
 417 .
 418 .
 419 .\" ====================================================================
 420 .SS Preprocessors
 421 .\" ====================================================================
 422 .
 423 Moreover, the following
 424 .I preprocessors
 425 were used as filename extension:
 426 .
 427 .
 428 .TP
 429 .IB <name> .chem
 430 for the integration of chemical formulas
 431 .
 432 .
 433 .TP
 434 .IB <name> .eqn
 435 for the mathematical use of equations
 436 .
 437 .
 438 .TP
 439 .IB <name> .pic
 440 graphical tool
 441 .
 442 .
 443 .TP
 444 .IB <name> .tbl
 445 for tables with
 446 .I tbl
 447 .
 448 .
 449 .TP
 450 .IB <name> .ref
 451 for files using the
 452 .B prefer
 453 .I preprocessor
 454 .
 455 .
 456 .\" ====================================================================
 457 .SS Classical Roff Files
 458 .\" ====================================================================
 459 .
 460 .TP
 461 .IB <name> .t
 462 .TQ
 463 .IB <name> .tr
 464 for files using the
 465 .I roff
 466 language of any kind
 467 .
 468 .
 469 .\" ====================================================================
 470 .SH NEW GROFF EXTENSIONS
 471 .\" ====================================================================
 472 .
 473 .I "GNU roff"
 474 .B groff
 475 is the actual
 476 .I roff
 477 standard, both for classical
 478 .I roff
 479 and new extensions.
 480 .
 481 So even the used new extensions in the source code should be regarded
 482 as actual standard.
 483 .
 484 The following extensions are used instead of classical
 485 .B .t
 486 or
 487 .BR .tr :
 488 .
 489 .
 490 .TP
 491 .IB <name> .groff
 492 .TQ
 493 .IB <name> .roff
 494 general ending for files using the
 495 .I groff language
 496 .
 497 .
 498 .\" ====================================================================
 499 .SS Source Code for Macro Packages (TMAC Files)
 500 .\" ====================================================================
 501 .
 502 As the classical form
 503 .BI tmac. <package_without_m> \fR,\fP
 504 of the
 505 .I TMAC
 506 file names is quite strange,
 507 .
 508 .I groff
 509 added the following structures:
 510 .
 511 .
 512 .TP
 513 .IB <package_without_m> .tmac
 514 .TQ
 515 .BI m <package> .tmac
 516 .TQ
 517 .BI groff_m <package> .tmac
 518 .
 519 .
 520 .\" ====================================================================
 521 .SS Files Using new Macro Packages
 522 .\" ====================================================================
 523 .
 524 .I Groff
 525 uses the following new macro packages:
 526 .
 527 .
 528 .TP
 529 .IB <name> .mmse
 530 file with swedish
 531 .B mm
 532 .I macros
 533 for
 534 .B groff
 535 .
 536 .
 537 .TP
 538 .IB <name> .mom
 539 files written in the
 540 .I "groff macro package"
 541 .B mom
 542 .
 543 .
 544 .TP
 545 .IB <name> .www
 546 files written in
 547 .BR HTML -like
 548 .I groff
 549 .IR macros .
 550 .
 551 .
 552 .\" ====================================================================
 553 .SS Preprocessors and Postprocessors
 554 .\" ====================================================================
 555 .
 556 .TP
 557 .IB <name> .hdtbl
 558 Heidelberger tables, an alternative to the preprocessor
 559 .IR tbl .
 560 .
 561 See
 562 .BR groff_hdtbl (@MAN7EXT@).
 563 .
 564 .
 565 .TP
 566 .IB <name> .grap
 567 files written for the graphical
 568 .B grap
 569 processor.
 570 .
 571 .
 572 .TP
 573 .IB <name> .grn
 574 for including
 575 .BR gremlin (@MAN1EXT@),
 576 pictures, see
 577 .BR grn (@MAN1EXT@).
 578 .
 579 .
 580 .TP
 581 .IB <name> .pdfroff
 582 transform this file with
 583 .B pdfroff
 584 of the
 585 .I groff
 586 system
 587 .
 588 .
 589 .\" ====================================================================
 590 .SH AUTHORS
 591 .\" ====================================================================
 592 This document was written by
 593 .MT groff\-bernd.warken\-72@\:web.de
 594 Bernd Warken
 595 .ME .
 596 .
 597 .
 598 .\" ====================================================================
 599 .SH "SEE ALSO"
 600 .\" ====================================================================
 601 .
 602 .
 603 .TP
 604 History and future
 605 .BR roff (@MAN7EXT@),
 606 .BR man\-pages (@MAN7EXT@),
 607 .BR groff_diff (@MAN7EXT@),
 608 .BR groff (@MAN7EXT@)
 609 .
 610 .
 611 .TP
 612 .I Compression
 613 .BR uncompress (1posix),
 614 .BR gzip2 (@MAN1EXT@),
 615 .BR bzip2 (@MAN1EXT@),
 616 .BR xz (@MAN1EXT@)
 617 .
 618 .
 619 .P
 620 A man page of the naming form
 621 .IB name ( n )
 622 can be read in text mode by
 623 .RS
 624 .EX
 625 .BI man " n name"
 626 .EE
 627 .RE
 628 or in graphical mode (PDF) by
 629 .RS
 630 .EX
 631 .BI groffer " n name"
 632 .EE
 633 .RE
 634 .
 635 .
 636 .P
 637 .UR https://\:github.com/\:n\-t\-roff/\:heirloom\-doctools
 638 .I Gunnar Ritter's Heirloom roff project
 639 .UE .
 640 .
 641 You can get this package with the shell command:
 642 .RS
 643 .EX
 644 \(Do \fBgit clone https://github.com/n\-t\-roff/heirloom\-doctools\fP
 645 .EE
 646 .RE
 647 .
 648 .
 649 .\" ====================================================================
 650 .\" Emacs settings
 651 .\" ====================================================================
 652 .
 653 .\" Local Variables:
 654 .\" mode: nroff
 655 .\" End:
 656 .\" vim: set filetype=groff: