🚀 go-pugleaf

I include below a short perl script that converts the X FAQ into
texinfo format. Using makeinfo(1) you can create a "hypertext" Info
document that can be browsed in Emacs or with the "xinfo" tool. As a
bonus, the program creates an index of things that look like hostnames
or email addresses, which is about the best it can do automatically.
Lots of things look crummy (eg. examples and tables) but again, they
can't be converted automatically and I'm not going to do them by hand.
I'd be happy to work on a more machine-convenient version of the FAQ
though, if the maintainers are interested.

Anyway, here's the script. Go grab the latest FAQ from export and find
"makeinfo" if you don't have it (it's part of the emacs distribution
but is a standalone C program). Also get xinfo -- it'll change your life.

George

#!/usr/local/bin/perl
#
# xfaq2texinfo : Convert X FAQ to texinfo format
#
# George Ferguson, ferguson@cs.rochester.edu, 20 Jan 1992.
#
# Usage, assuming the list is in the file FAQ, with news headers removed:
#	% xfaq2texinfo <FAQ >xfaq.texinfo
# If you store your FAQ compressed, you can use
#	% zcat FAQ.Z | xfaq2texinfo >xfaq.texinfo
# In any case, you then need to convert to info format:
#	% makeinfo +fill-column 80 xfaq.texinfo
# The result will be files xfaq-info and xfaq-info-[1-5]. If you don't
# have makeinfo(1), you can try using "texinfo-format-buffer" within
# emacs. If you don't have emacs either, you're outta luck. You have
# to put the info files where emacs or xinfo can find them.
#
# The FAQ can be obtained from export.lcs.mit.edu in directory contrib.
#

# Print texinfo header
print "\\input texinfo\n";
print "@setfilename xfaq.info\n";
print "@settitle Frequently Asked Questions about X\n";
print "\n";
print "@node Top\n";
print "@top Frequently Asked Questions about X\n";
print "\n";

# To start, we're reading the header ($top) but not the main meny ($inmenu).
$top = 1;
$inmenu = 0;
$subject = 0;

# Now process each line
while (<>) {
    # if processing the header
    if ($top) {
	if (/^Subject:/) {				# Skip ugly first line
	    next;
	} elsif (/^ *([0-9]*)\)(.) TOPIC: (.*)$/) {	# TOPICs in main menu
	    if (!$inmenu) {
		print "@menu\n";
		$inmenu = 1;
	    }
	    $topic = $1;
	    print "* Topic $1::\t$2$3\n";
	} elsif (/^ *([0-9]*)\)(.) *(.*)$/) {		# Questions in submenus
	    $menus{$topic} .= "* Topic $1::\t$3$2\n";
	} elsif (/^-+$/) {
	    $top = 0;
	    next;
	} else {					# Text of top node
	    if ($inmenu) {
		print "* Host User and Newsgroup Index::\n";
		print "@end menu\n";
		$inmenu = 0;
	    }
	    &formatText;
	}
    } elsif (/^Subject: *([0-9]*)\)(.) TOPIC: (.*)$/) {	# TOPIC == chapter
	print "@node Topic $1\n";
	print "@chapter $2$3\n";
	print "\n";
	print "@menu\n";
	print "$menus{$1}";				# ...with submenu
	print "@end menu\n\n";
	next;
    } elsif (/^Subject: *([0-9]*)\)(.) *(.*)$/) {	# Question == section
	$subject = 1;
	print "@node Topic $1\n";
	print "@section $3$2\n";
    } elsif (/^-+$/) {					# Avoid .sig, etc.
	$subject = 0;
	next;
    } elsif ($subject) {				# Text of question
	&formatText;
    }
}

# Print texinfo trailer
print "@node Host User and Newsgroup Index\n";
print "@appendix Host User and Newsgroup Index\n";
print "\n";
print "@printindex fn\n";
print "\n";
print "@bye\n";

############################################################################

#
# For each line of text in the document, we generate an index entry for
# anything that looks like a hostname, email address, or newsgroup, as
# well as wrapping that thing in @w{@file{}}. This function is complicated
# by the fact that the index entries have to come on lines of their own,
# after the text that contains them.
#
# This function also escapes any characters with special meaning to
# texinfo. Note that the pattern for the first separator of an address
# (or hostname, etc.) can be a period, percent sign or at-sign. If it's
# and at-sign then it's already been doubled to escape it.
#
sub formatText {
    # convert special chars to texinfo escapes
    s/@/@@/g;
    s/\{/@{/g;
    s/\}/@}/g;
    s/ +$//g;
    # gather the index entries
    local($t) = $_;
    local($tt) = "";
    while ($t =~ /([-a-zA-Z0-9]{2,}((\.|@@|%|!)[-@a-zA-Z0-9]+){2,})/) {
	$t = $';
	$tt .= "@findex $1\n";
    }
    # make the substitutions in the original text string
    s/([-a-zA-Z0-9]{2,}((\.|@@|%|!)[a-zA-Z0-9]+){2,})/\@w{\@file{$1}}/g;
    # print the line of text
    print "$_";
    # print the index entries, if any
    print "$tt" if ($tt ne "");
}

__END__
-- 
George Ferguson			ARPA: ferguson@cs.rochester.edu
Dept. of Computer Science	UUCP: rutgers!rochester!ferguson
University of Rochester		VOX:  (716) 275-2527
Rochester  NY  14627-0226	FAX:  (716) 461-2018