Re: [PATCH] Better PODs

Ilya Zakharevich on Sat, 3 Mar 2001 01:32:40 -0500
[Date Prev] [Date Next] [Thread Prev] [Thread Next] [Date Index] [Thread Index]
Re: [PATCH] Better PODs
To: Developers Pari <pari-dev@list.cr.yp.to>
Subject: Re: [PATCH] Better PODs
From: Ilya Zakharevich <ilya@math.ohio-state.edu>
Date: Sat, 3 Mar 2001 01:32:40 -0500
In-reply-to: <20010228205026.A29132@math.ohio-state.edu>; from ilya@math.ohio-state.edu on Wed, Feb 28, 2001 at 08:50:26PM -0500
References: <20010228205026.A29132@math.ohio-state.edu>
On Wed, Feb 28, 2001 at 08:50:26PM -0500, Ilya Zakharevich wrote:
> I think this patch fixes 95% of remaining problems with quasi-parsing
> of TeX in PARI docs.  It also supports a new kind of output: "dumb
> POD".  [It looks like the "standard" pod2whatever converters are too
> dumb to support feature-rich POD.] 

Yet more of this...  More cleanup, and now produces manpages automatically.

Enjoy,
Ilya

--- ./doc/gphelp.in-as-sent	Sun Feb 11 03:37:38 2001
+++ ./doc/gphelp.in	Fri Mar  2 22:59:08 2001
@@ -35,7 +35,7 @@
 #
 #  -to_pod file		convert file to POD (should be the only args)
 #
-#  -to_dumbpod file	same, but without nested formating
+#  -to_dumb_pod file	same, but without nested formating
 #
 # Granted environment variables (override):
 #  GPTMPDIR: where temporary files will go (/tmp by default).
@@ -86,7 +86,7 @@ sub cleanexit {
 }
 
 sub help {
-  print "Usage: $0 [-k] [-detex] [-ch c1] [-cb c2] [-cu c3] keyword\n";
+  print "Usage: $0 [-k] [-detex] [-ch c1] [-cb c2] [-cu c3] [-to_[dumb_]pod] keyword\n";
   print "where c1,c2,c3 denote background, bold and underline color\n";
   exit(1);
 }
@@ -484,7 +484,7 @@ sub format_text
       @_ = split(/ /, $_);
       for (@_)
       {
-	s/\Q$tr{nbrk}/ /g; push(@w, $_);
+	s/\Q$tr{nbrk}/ /go; push(@w, $_);
 	s/\@\[\w+\]//g;    push(@l, length($_));
       }
     }
@@ -561,7 +561,7 @@ sub detex
 sub inittr {
   @ou = qw( dollar nbrk startbold endbold startcode endcode
 	    obr cbr uuml ouml agrave eacute
-	    startpodcode endpodcode startlink endlink
+	    startpodcode endpodcode startlink endlink startindex endindex
 	    startbcode endbcode startbi endbi startit endit
 	    startword endword startlword endlword pm empty gt lt podleader );
 
@@ -577,6 +577,8 @@ sub inittr {
 	  startlink => 'L<',
 	  endlink => '>',
 	  endcode => '>',
+	  startindex => 'X<',
+	  endindex => '>',
 	  obr => '{',
 	  cbr => '}',
 	  startpodcode => 'C<',
@@ -606,6 +608,43 @@ sub inittr {
 	  empty => 'Z<>',
 	  podleader => '=',
 	);
+  # How to emit in verbatim sessions:
+  %vr = ( dollar => '',
+	  ldollar => '$',	# literal dollar
+	  nbrk => ' ',
+	  startbold => '',
+	  endbold => '',
+	  startcode => '',
+	  startlink => '',
+	  endlink => '',
+	  endcode => '',
+	  startindex => '',
+	  endindex => '',	# XXX Need to remove the contents too...
+	  obr => '{',
+	  cbr => '}',
+	  startpodcode => '',
+	  endpodcode => '',
+	  startbcode => '',
+	  endbcode => '',
+	  startbi => '',
+	  endbi => '',
+	  startit => '',
+	  endit => '',
+	  startword => '',
+	  endword => '',
+	  startlword => '',
+	  endlword => '',
+	  pm => '+-',
+	  "gt" => '>',
+	  "lt" => '<',
+	  # This should better be put in Latin1...  Or Win1251?  ;-)
+	  ouml => '"o',
+	  uuml => '"u',
+	  eacute => '\'e',
+	  agrave => '`a',
+	  empty => '',
+	  podleader => '=',
+	);
 }
 
 sub indent_equally { my $in = shift; $in =~ s/^[ \t]*/    /mg; $in}
@@ -649,14 +688,14 @@ sub basic_subst
   s/\\(~|tilde)/~/g;
 
   s/\\(equiv)(?![a-zA-Z])/ = /g;
-  s/\\`a/$tr{agrave}/;
-  s/\\`{a}/$tr{agrave}/;
-  s/\\"o/$tr{ouml}/;
-  s/\\"{o}/$tr{ouml}/;
-  s/\\"u/$tr{uuml}/;
-  s/\\"{u}/$tr{uuml}/;
-  s/\\'e/$tr{eacute}/;
-  s/\\'{e}/$tr{eacute}/;
+  s/\\`a/$tr{agrave}/g;
+  s/\\`{a}/$tr{agrave}/g;
+  s/\\"o/$tr{ouml}/g;
+  s/\\"{o}/$tr{ouml}/g;
+  s/\\"u/$tr{uuml}/g;
+  s/\\"{u}/$tr{uuml}/g;
+  s/\\'e/$tr{eacute}/g;
+  s/\\'{e}/$tr{eacute}/g;
 
   s/(^|[^\\])%.*/$1/g;		        # comments
   s/\\vadjust\s*\{\s*\\penalty\s*\d+\s*\}//g;
@@ -664,6 +703,7 @@ sub basic_subst
   # We do not strip %\n, thus:
   s/\\kbd{\n\s*/\\kbd{/g;
   s/\$\\bf(\b|(?=[\d_]))\s*([^\$]+)\$/\$$tr{startbcode}$1$tr{endbcode}\$/g;
+  s/\$\s*\\,\s*\$//g;			# Do not make into $$
   s/\$/$tr{dollar}/g;		        # math mode
   s/\t/ /g; s/\\,//g; s/\\[ ;]/ /g;     # various spaces
   s/\\\///g;			# italic correction
@@ -690,7 +730,8 @@ sub basic_subst
   s/(\\string)?\\_/_/g;
   s/\\([#\$&%|])/$1/g;
   s/\\(hat(?![a-zA-Z])|\^)({\\?\s*})?/^/g;
-  s/ *\\pow(?![a-zA-z]) */^/g;
+  # Don't eat spaces after =head:
+  s/((^\Q$tr{podleader}\Ehead\d\s*)?) *\\pow(?![a-zA-z]) */$1^/gmo;
 
   s/\\neq?(?![a-zA-Z])/ != /g;
   s/\\enspace(?![a-zA-Z])/ /g;
@@ -784,7 +825,8 @@ sub basic_subst
   s/\\kbdsidx/\\sidx/g;
   s/\\sidx\{[^\}]*\}//g unless $to_pod;
   s/\\[a-zA-Z]*idx\{([^\}]*)\}/$1/g unless $to_pod;
-  s/\\(?:text|hbox)\s*\{ *(?:\\it\b\s*)?(([^{}]+(?=[{}])|\{[^{}]*\})*)\}/$1/g;
+  s/\\(?:text|hbox)\s*\{(\s*)\\it\b\s*(([^{}]+(?=[{}])|\{[^{}]*\})*)\}/$1$tr{startit}$2$tr{endit}/g;
+  s/\\(?:text|hbox)\s*\{(\s*)(?:\\rm\b\s*)?(([^{}]+(?=[{}])|\{[^{}]*\})*)\}/$1$2/g;
   s/\\(text|hbox)//g;
   s/^([ \t]+)\{ *\\(it|sl|bf|tt)\b/S<$1>{\\$2/gm;
   s/\{ *\\(it|sl) *(([^{}]+(?=[{}])|\{[^{}]*\})*)\}/$tr{startit}$2$tr{endit}/g;
@@ -831,6 +873,12 @@ sub presubst {
   push(@text, $_);
 }
 
+sub clean_basic {	# Remove all the (simple) meta-info
+  my $in = shift;
+  $in =~ s/\@\[(\w+)\]/$vr{$1}/g;
+  $in;
+}
+
 sub code_subst {
   my $in = shift;
   $in =~ s/\@dots\b/.../g;
@@ -838,7 +886,7 @@ sub code_subst {
   if ($in =~ /\@com(.*)/)
   {
     if ($to_pod) {
-      $in = $` . &basic_subst($1) . code_subst($');
+      $in = $` .    clean_basic(basic_subst($1)) . code_subst($');
     } else {
       $in = $` . $tr{endcode} . &basic_subst($1) . $tr{startcode} . code_subst($');
     }
@@ -846,7 +894,7 @@ sub code_subst {
   if ($in =~ /\@Ccom(.*)\*\//)
   {
     if ($to_pod) {
-      $in = $` .		&basic_subst($1) . "*/" . &code_subst($');
+      $in = $` .    clean_basic(basic_subst($1)) . "*/" . &code_subst($');
     } else {
       $in = $` . $tr{endcode} . &basic_subst($1) . $tr{startcode}
                                                  . "*/" . &code_subst($');
@@ -900,7 +948,7 @@ sub TeXprint_topod {
   # Try to guard \label/\sidx (removing possible '.')
 #  This somehow breaks index...
 #  s/(\\(?:section|subsec(?:ref|idx|op)?(unix)?)\s*{(?:(?:[^{}]+(?=[{}])|{[^{}]+})+)})\.?\s*\\(label|sidx)/$1\n\\$2/;
-  s/(\\(?:section|subsec(?:ref|idx|op)?)\s*{(?:(?:[^{}]+(?=[{}])|{[^{}]+})+)})\.?\s*\\(label|sidx)/$1\n\\$2/;
+  s/(\\(?:section|subsec(?:ref|idx|op)?)\s*{(?:(?:[^{}]+(?=[{}])|{[^{}]+})+)})\.?\s*\\(label|(kbd)?sidx)/$1\n\\$2/;
 
   # last if /\\subsec[\\{}ref]*[\\\${]$help[}\\\$]/o;
   s/\\chapter\s*{((?:[^{}]|\{[^{}]*\})*)}\s*/\n\n$tr{podleader}head1 NAME\n\nlibPARI - $1\n\n$tr{podleader}head1 DESCRIPTION\n\n/;
@@ -943,7 +991,8 @@ sub TeXprint_topod {
 
   s/'(\W)'/{\\tt '$1'}/g;
   s/(\\\w+)(\\hbox)/$1 $2/g;
-  s/\\hbox\s*\{(?:\\it\b\s*)?((?:\\[\{\}]|[^{}]|\{[^{}]*\})*)\}/$1/g;
+  s/\\hbox\s*\{(\s*)\\it\b\s*((?:\\[\{\}]|[^{}]|\{[^{}]*\})*)\}/$1$tr{startit}$2$tr{endit}/g;
+  s/\\hbox\s*\{(\s*)(?:\\rm\b\s*)?((?:\\[\{\}]|[^{}]|\{[^{}]*\})*)\}/$1$2/g;
 
   # substitute non-verbatim code
   $acc = '';
@@ -972,14 +1021,14 @@ sub TeXprint_topod {
   s/\$\$(.*?)\$\$\s*/\n\nS<  >$tr{startcode}$1$tr{endcode}\n\n/gs;
   s/\$([^\$]+)\$/$tr{startcode}$1$tr{endcode}/g;
 
-  s/\\s(?:ref|idx){\s*([^{}]*)}/"X<" . for_index($1) . ">"/ge; # 
-  s/\\(?:ref|idx){\s*([^{}]*)}/"X<" . for_index($1) . ">$1"/ge;
+  s/\\s(?:ref|idx){\s*([^{}]*)}/$tr{startindex} . for_index($1) . $tr{endindex}/ge;
+  s/\\(?:ref|idx){\s*([^{}]*)}/$tr{startindex} . for_index($1) . "$tr{endindex}$1"/ge;
 
 # Conflict between different versions of PARI and refcard:
 # s/\\(?:key|li)\s*{(.*)}\s*{(.+)}[ \t]*\n/\n\n=item C<$2>\n\n$1\n\n/msg;
 # s/\\(?:key|li)\s*{(.*)}\s*{}[ \t]*\n/\n\n=back\n\n$1\n\n=over\n\n/mgs;
 # s/\\(key|var)(?![a-zA-Z])\s*{(\w+)}/C<$2>/mg;
-  s/\\var\s*{X<(\w+)>(\w+)}/X<$1>$tr{startcode}$2$tr{endcode}/mg;
+  s/\\var\s*{\Q$tr{startindex}\E(\w+)\Q$tr{endindex}\E(\w+)}/$tr{startindex}$1$tr{endindex}$tr{startcode}$2$tr{endcode}/mgo;
   s/\\var\s*{f{}lag}/$tr{startcode}flag$tr{endcode}/mg;
 
   s/\\metax(?![a-zA-Z])\s*{(.*)}\s*{\s*(\w+)(?=C\<)(.*)}[ \t]*\n/\n\n=item C<L<$2>$3>\n\n$1\n\n/mg;
@@ -987,9 +1036,9 @@ sub TeXprint_topod {
   s/C\<\{\}=/C\<=/g;
   s/\\fl(?![a-zA-Z])/I<flag>/g;
   s/\\file(?![a-zA-Z])/F<file>/g;
-  s/\\(unix|emacs)\b\s*(\{?)(\s*\\(no)?indent)?\s*/X<\U$1>$2/g;
-  s/\A\\label\s*\{([\w:.-]*)\}([ \t]*\n\s*(?=[^\s=]))?/X<Label $1>/g;
-  s/\\label\s*\{([\w:.-]*)\}/X<Label $1>/g;
+  s/\\(unix|emacs)\b\s*(\{?)(\s*\\(no)?indent)?\s*/$tr{startindex}\U$1\E$tr{endindex}$2/g;
+  s/\A\\label\s*\{([\w:.-]*)\}([ \t]*\n\s*(?=[^\s=]))?/$tr{startindex}Label $1$tr{endindex}/g;
+  s/\\label\s*\{([\w:.-]*)\}/$tr{startindex}Label $1$tr{endindex}/g;
   s/\\secref\s*\{([\w:.-]*)\}/L<Label $1>/g;
   s/\\begin(double)?indentedkeys\s*/\n\n=over\n\n/g;
   s/\\end(double)?indentedkeys\s*/\n\n=back\n\n/g;
@@ -1001,12 +1050,14 @@ sub TeXprint_topod {
   s/{\\rm(?![a-zA-Z])\s*([^{}]*)}/$1/g;
   s/\\Z<>/\\/g;			# Optimize for readability
 
+  s/^((\Q$tr{startindex}\E[\w\s]+\Q$tr{endindex}\E)+)[ \t]+/$1/mgo;
+
   # Now replace the POD stuff
-  # Start with cosmetic stuff:
+  # Start with cosmetic stuff: C<> inside C<>
   $in_code = 0;
   s/(\@\[((start)|end)code\])/ ($3 ? $in_code++ : --$in_code) ? "" : $1 /ge;
 
-  if ($dumb_pod) {
+  if ($dumb_pod) {	# Many traslators do not grok embedded markup
     my @stack;
     s /(\@\[((start)|end)(\w+)\])/
       if ($3) {			# Start
@@ -1016,7 +1067,7 @@ sub TeXprint_topod {
 	pop @stack;
 	$1 . (@stack ? "\@[start$stack[-1]]" : '')
       }
-      /ge
+      /ge;
   }
   1 while s/\@\[start(\w+)\](\s*)\@\[end\1\]/$2/g;
 
@@ -1028,6 +1079,12 @@ sub TeXprint_topod {
   # Normalize the spacing
   s/\n{3,}/\n\n/;
   s/\A([ \t]*\n)+//;
+  if ($dumb_pod) {
+    # pod2man has problems with \n inside X<>; be careful to not create
+    # new paragraph breaks.  Assume that $tr{endindex} is one-char-long
+    s/(\nX<[^>]*)\n/$1 /g;
+    s/(X<[^>]*)\n/\n$1 /g;
+  }
   # Single label is not healthy...
   print "\n" if $last_glued and /\A=/; # POD markup needs a new paragraph
   $last_glued = s/((\A|\n\n)(X<[^<>]+>)+)[ \t]*\n\n/$1\n/;
@@ -1048,21 +1105,13 @@ sub color
 sub TeXprint
 {
   local($_) = $_[0];
-  s/\@\[obr\]/{/g;
-  s/\@\[cbr\]/}/g;
-  # This should better be put in Latin1...  Or Win1251?  ;-)
-  s/\@\[ouml\]/"o/g;
-  s/\@\[uuml\]/"u/g;
-  s/\@\[agrave\]/`a/g;
-  s/\@\[eacute\]/'e/g;
-  s/\@\[ldollar\]/\$/g;
   s/\@\[end(bold|code|bcode|bi|it)\]/\e[m$ch/g;
   s/\@\[start(bold|code|bcode|bi)\]/$cb\e[1m/g;
   s/\@\[startit\]/$cu\e[4m/g;
-  s/\@\[(dollar|empty|endl?word|endpodcode|startl?word|startpodcode)\]//g;
   s/\@\[pm\]/±/g;
   s/\\([\{\}])/$1/g;
-  s/\@\[nbrk\]/ /g; print "$_\n";
+  s/\@\[(\w+)\]/$vr{$1}/g;
+  print "$_\n";
 }
 
 sub to_pod {
--- ./config/DOC_Make.SH-pre Wed Feb 28 20:27:10 2001
+++ ./config/DOC_Make.SH	Fri Mar  2 23:14:54 2001
@@ -3,15 +3,20 @@
 #
 SHELL = $make_sh
 
-doc all: manual refcard tutorial
+doc all: manual refcard tutorial manpages
 docps: refcard.ps tutorial.ps users.ps ../INSTALL.ps
 docpdf: users.pdf tutorial.pdf refcard.pdf ../INSTALL.pdf
 manual: users.dvi
 tutorial: tutorial.dvi
 refcard: refcard.ps
+manpages: gp-refcard.1 gp-tutorial.1 gp-overview.1  gp-usage.1 \
+	pari-functions.3 pari-lowlevel.3 pari-lowlevel.3
+
 
 .SUFFIXES: .tex .ipf .pod .inf .dumbpod
 
+POD2MAN = pod2man --lax
+
 paricfg.tex: paricfg.tex.in
 	sed -e 's/@version@/2.2.0/'\
 	    -e 's!@includedir@!/usr/local/include/pari!'\
@@ -99,11 +104,13 @@ veryclean: clean
 .ipf.inf:
 	ipfc /INF $*.ipf
 
-# This is for testing:
+# This one is for testing:
 
 .pod.ipf:
 	pod2ipf $*.pod > tmp_ipf && mv tmp_ipf $*.ipf
 
+# This one is for real:
+
 pari.ipf:  refcard.pod tutorial.pod usersch1.pod usersch1.pod usersch2.pod usersch3.pod usersch4.pod usersch5.pod appa.pod appb.pod appc.pod
 	pod2ipf --title="PARI/GP Manual" --by-files --section-name="Getting started" --file=refcard.pod --file=tutorial.pod --section-name="Usser guide" --file=usersch1.pod --file=usersch1.pod --file=usersch2.pod --file=usersch3.pod --file=usersch4.pod --file=usersch5.pod --section-name=Appendices --file=appa.pod --file=appb.pod --file=appc.pod > tmp_ipf && mv tmp_ipf pari.ipf
 
@@ -114,4 +121,24 @@ pari.ipf:  refcard.pod tutorial.pod user
 .dumbpod.html:
 	pod2html --title="PARI/GP Manual $* Getting started" --file=$*.dumbpod > tmp_html && mv tmp_html $*.html
 
+gp-refcard.1: refcard.dumbpod
+	$(POD2MAN) refcard.dumbpod > tmp_man && mv tmp_man $@
+
+gp-tutorial.1: tutorial.dumbpod
+	$(POD2MAN) tutorial.dumbpod > tmp_man && mv tmp_man $@
+
+gp-overview.1: usersch1.dumbpod
+	$(POD2MAN) usersch1.dumbpod > tmp_man && mv tmp_man $@
+
+gp-usage.1: usersch1.dumbpod
+	$(POD2MAN) usersch2.dumbpod > tmp_man && mv tmp_man $@
+
+pari-functions.3: usersch1.dumbpod
+	$(POD2MAN) usersch3.dumbpod > tmp_man && mv tmp_man $@
+
+pari-programming.3: usersch1.dumbpod
+	$(POD2MAN) usersch4.dumbpod > tmp_man && mv tmp_man $@
+
+pari-lowlevel.3: usersch1.dumbpod
+	$(POD2MAN) usersch5.dumbpod > tmp_man && mv tmp_man $@
Prev by Date: [PATCH] Data dir at runtime
Next by Date: [PATCH] Name conflict
Previous by thread: [PATCH] Data dir at runtime
Next by thread: [PATCH] Name conflict
Index(es):
- Date
- Thread