fix-roff-punct

   1 #! /usr/bin/perl -w
   2 use strict;
   3
   4 # fix-roff-punct: Fix up punctuation usage in automatically-generated
   5 # troff files (man pages).
   6
   7 # Authors:
   8 #   Peter Moulder <pmoulder@mail.csse.monash.edu.au>
   9 #
  10 # Copyright (C) 2004 Monash University
  11 #
  12 # Gnu GPL v2+:
  13 #
  14 #   This program is free software; you can redistribute it and/or
  15 #   modify it under the terms of the GNU General Public License as
  16 #   published by the Free Software Foundation; either version 2 of the
  17 #   License, or (at your option) any later version.
  18 #
  19 #   This program is distributed in the hope that it will be useful,
  20 #   but WITHOUT ANY WARRANTY; without even the implied warranty of
  21 #   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  22 #   General Public License for more details.
  23 #
  24 #   You should have received a copy of the GNU General Public License
  25 #   along with this program; if not, write to the Free Software
  26 #   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  27
  28
  29 # Background: Humans use a number of dash-like characters:
  30 #
  31 #   - ASCII hyphen/minus needed for command-line options and other computer
  32 #     input;
  33 #   - hyphen (`one-to-one');
  34 #   - en dash (`2000-2003');
  35 #   - em dash -- like this.  [Not currently handled.]
  36 #
  37 # Troff input spells them as \-, -, \[en], \[em] respectively.  (See the
  38 # groff_char.7 man page for a full list of such punctuation characters.)  If
  39 # you run `man' with your LC_CTYPE indicating a rich character set like unicode
  40 # (UTF-8 encoding), then it uses different output characters for each of the
  41 # above.
  42 #
  43 # In particular, if your man page source has plain `-' when giving an example
  44 # of a flag or command or other program input, then users won't be able to use
  45 # mouse copy&paste from the formatted man page.
  46
  47 # This script is something of a hack: it is only big enough to handle a few man
  48 # pages of interest (produced by pod2man).  You should manually check the
  49 # changes it makes.
  50
  51 # Approach: we handle each line a word at a time, and typically make the same
  52 # hyphen-vs-ASCII decision throughout the word.  We're a bit haphazard about
  53 # word-splitting, but it's hard to find an example of where we'd be hurt by
  54 # that, and by luck we would do the right thing for many gcc options like
  55 # `-fconstant-string-class=\fICLASS-NAME\fR' (where CLASS-NAME should use a
  56 # hyphen and the others should be ASCII hyphen-minus).
  57 #
  58 # Perl's /e (execute) flag for substitutions does just what we want
  59 # for preserving non-word bits while transforming "words".
  60 #
  61 # We don't currently handle special things like `apt-get' that look like
  62 # hyphenated english words but are actually program names.  In general the
  63 # problem is AI complete, e.g. `apt-gettable' could be either hyphen (gettable
  64 # by apt) or ASCII hyphen-minus (able to be processed by the `apt-get'
  65 # program).
  66 #
  67 # We don't currently take hints from font choice.  (E.g. text in CR font should
  68 # probably use ASCII hyphen-minus.)
  69 #
  70 # We currently only handle a couple troff requests and escapes (see groff.7).
  71
  72 sub frob ($);
  73
  74 my $yearRE = qr/(?:19[6-9]|20[013])[0-9]/;
  75
  76 sub frob ($) {
  77     my ($x) = @_;
  78
  79     # Consider splitting into two words.
  80     if ($x =~ m{\A(.*?)(\\(?:[&/,~:d]|f[BRI]|s-?[0-9]+))(.*)\z}) {
  81         my ($before, $s, $after) = ($1, $2, $3);
  82         return frob($before) . $s . frob($after);
  83     }
  84
  85     if ($x =~ m{\A(.*?)(\.+)\z}) {
  86         my $d = $2;
  87         return frob($1) . $d;
  88     }
  89
  90     # `32-bit', `5-page'.
  91     if ($x =~ m{\A[0-9]+-[a-z]+\z}) {
  92         return $x;
  93     }
  94
  95     # Year range: `(C) 1998-2003'.
  96     if ($x =~ m{\A$yearRE\\?-$yearRE\z}) {
  97         $x =~ s{\\?-}{\\[en]};
  98         return $x;
  99     }
 100
 101     # ISO date.
 102     if ($x =~ m{\A$yearRE-[01][0-9]-[0-3][0-9]\z}) {
 103         return $x;
 104     }
 105
 106     # Things likely to be computer input.
 107     if ($x =~ m{[0-9]|\.[a-zA-Z]|\A(?:[-/.]|\\-|\[.*\]\z)}) {
 108         $x =~ s/\\?-/\\-/g;
 109         return $x;
 110     }
 111
 112     $x =~ s/\\?-/-/g;
 113     return $x;
 114 }
 115
 116 while(<>) {
 117     if ($_ eq '.tr \(*W-|\(bv\*(Tr' . "\n") {
 118         # Get rid of pod2man's "helpful" munging of pipe symbol.
 119         next;
 120     }
 121
 122     # Leave ASCII apostrophe unchanged (i.e. \[aq]) for examples.
 123     if (/\A\\\&    /) {
 124         s/'/\\[aq]/g;   # `\[aq]' = "ascii quote"
 125     }
 126
 127     if (/\A\.IP /) {
 128         s/\\?-/\\-/g;
 129         s/\\s\\-1/\\s-1/g;
 130     }
 131     elsif (/\A\.IX /) {
 132         s/\\?-/-/g;
 133     }
 134     elsif (!/\A\. *(?:\\"|ds|if|ie)/) {
 135         # As an optimization, we process only words containing `-'.
 136         s{([.@/\\[:alnum:]]*-[-.@/\\[:alnum:]]*)}{frob($1)}ge;
 137     }
 138     print;
 139 }