source: git/doc/pl2doc.pl @ e3663f1

spielwiese
Last change on this file since e3663f1 was 013a76, checked in by Hans Schönemann <hannes@…>, 25 years ago
* hannes: new structure of the library chapter (doc2tex.pl general.doc pl2doc.pl reference.doc) git-svn-id: file:///usr/local/Singular/svn/trunk@3580 2c84dea3-7e68-4137-9b89-c4e89433aadc
  • Property mode set to 100755
File size: 11.8 KB
Line 
1#!/usr/local/bin/perl
2# $Id: pl2doc.pl,v 1.11 1999-09-02 14:24:48 Singular Exp $
3###################################################################
4#  Computer Algebra System SINGULAR
5#
6#  pl2doc.pl: utility to generate doc file out of pl for singular library
7#
8####
9$Usage = <<EOT;
10Usage: 
11$0 [-o out_file -db db_file -no_ex -no_fun -doc] library_perl_file.doc
12Convert library_perl_file.pl to library_perl_file.doc
13EOT
14
15###################################################################
16# parse command line options
17#
18while (@ARGV && $ARGV[0] =~ /^-/) 
19{
20  $_ = shift(@ARGV);
21  if (/^-o$/)    { $out_file = shift(@ARGV); next;}
22  if (/^-db$/) { $db_file = shift(@ARGV); next;}
23  if (/^-no_fun$/)    { $no_fun = 1;next;}
24  if (/^-doc$/)       { $doc = 1; next;}
25  if (/^-h(elp)?$/)   { print $Usage; exit;}
26 
27  die "Error: Unknown option: $_:$Usage\n";
28}
29
30
31###################################################################
32# Execute perl file
33#
34$pl_file = pop(@ARGV);
35die "Error: No perl file specified: $Usage\n" unless $pl_file;
36die "Error: Can't find perl file $pl_file: $Usage\n" unless -r $pl_file;
37require $pl_file;
38$lib = $library;
39$lib =~ s|.*/(.*)$|$1|;
40$lib =~ s|(.*)\.lib$|$1|;
41
42###################################################################
43# print  summary
44#
45unless ($out_file)
46{
47  ($out_file = $pl_file) =~ s/(.*)\..*$/$1/;
48  $out_file .= "_noFun" if ($no_fun);
49  $out_file .= ".doc";
50}
51open(LDOC, ">$out_file") || die"Error: can't open $out_file for writing: $!\n";
52print_doc_header(\*LDOC) if $doc;
53print LDOC "\@c ---content LibInfo---\n";
54print LDOC "\@c library version: $version\n";
55print LDOC "\@c library file: $library\n";
56print LDOC "\@cindex $lib.lib\n";
57print LDOC "\@cindex ${lib}_lib\n";
58undef @procs; # will be again defined by OutLibInfo
59$parsing = "info-string of lib $lib:";
60$ref = OutLibInfo(\*LDOC, $info, ! $no_fun);
61OutRef(\*LDOC, $ref) if $ref;
62print LDOC "\@c ---end content LibInfo---\n";
63
64###################################################################
65# print  summary
66#
67# print subsubsections for help of procs
68unless ($no_fun)
69{
70  if ($db_file)
71  {
72    $db_file = $1 if ($db_file =~ /(.*)\..*$/);
73    dbmopen(%CHECKSUMS, $db_file, oct(755)) ||
74      die "Error: can't open chksum data base $db_file";
75  }
76  # print help and example of each function
77  for ($i = 0; $i <= $#procs; $i++)
78  {
79    # print node and section heading
80    print LDOC "\n\@c ------------------- " . $procs[$i]." -------------\n";
81    print LDOC "\@node " . $procs[$i].",";
82    print LDOC " ".$procs[$i+1] if ($i < $#procs);
83    print LDOC ",";
84    print LDOC " ".$procs[$i-1] if ($i > 0);
85    print LDOC ", " . $lib ."_lib\n";
86    print LDOC "\@subsubsection " . $procs[$i] . "\n";
87    print LDOC "\@cindex ". $procs[$i] . "\n";
88    $CHECKSUMS{$procs[$i]} = $chksum{$procs[$i]} if ($db_file);
89    print LDOC "\@c ---content $procs[$i]---\n";
90    print LDOC "Procedure from library \@code{$lib.lib} (\@pxref{${lib}_lib}).\n\n";
91    if ($help{$procs[$i]} =~ /^\@/)
92    {
93      print LDOC $help{$procs[$i]};
94      $ref = '';
95    }
96    else
97    {
98      print LDOC "\@table \@asis\n";
99      $table_is_open = 1;
100      # print help
101      $parsing = "help-string of $lib:$procs[$i]:";
102      $ref = OutInfo(\*LDOC, $help{$procs[$i]});
103      print LDOC "\@end table\n";
104    }
105    # print example
106    if ($example{$procs[$i]} && 
107        ($ex = &CleanUpExample($lib, $example{$procs[$i]})))
108    {
109      print LDOC "\@strong{Example:}\n";
110      print LDOC "\@smallexample\n\@c example\n";
111      print LDOC $ex;
112      print LDOC "\n\@c example\n\@end smallexample\n";
113    }
114    OutRef(\*LDOC, $ref) if $ref;
115    print LDOC "\@c ---end content $procs[$i]---\n";
116  }
117  dbmclose(%CHECKSUMS);
118}
119
120#
121# und Tschuess
122#
123if ($doc)
124{
125 print LDOC <<EOT;
126\@c ----------------------------------------------------------
127\@node Index, , Singular libraries, Top
128\@chapter Index
129\@printindex cp
130
131\@bye
132EOT
133}
134 
135close(LDOC);
136if ($error)
137{
138  print STDERR "ERROR: $error\n";
139  exit(1);
140}
141exit(0);
142
143###########################################################################
144#
145# parse and print-out libinfo
146#
147sub OutLibInfo
148{
149  my ($FH, $info, $l_fun) = @_;
150  if ($info =~ /^\@/)
151  {
152    print $FH $info;
153    return;
154  }
155  print $FH "\@table \@asis\n";
156  $table_is_open = 1;
157 
158  my ($ref) = OutInfo($FH, $info, $l_fun);
159
160  print $FH "\@end table\n" if $table_is_open;
161  $table_is_open = 0;
162  return $ref;
163}
164
165sub OutInfo
166{
167  my ($FH, $info, $l_fun) = @_;
168  if ($info =~ /^\@/)
169  {
170    print $FH $info;
171    return;
172  }
173  $info =~ s/^\s*//;
174  $info =~ s/\s*$//;
175  $info .= "\n";
176
177  my ($item, $text, $line, $ref);
178  while ($info =~ m/(.*\n)/g)
179  {
180    $line = $1;
181    if ($1 =~ /^(\w.+?):(.*\n)/)
182    {
183      $ref .= OutInfoItem($FH, $item, $text, $l_fun) if $item && $text;
184      $item = $1;
185      $text = $2;
186    }
187    else
188    {
189      $text .= $line;
190    }
191  }
192  $ref .= OutInfoItem($FH, $item, $text, $l_fun) if $item && $text;
193  return $ref;
194}
195
196sub FormatInfoText
197{
198  my $length = shift;
199  my ($pline, $line, $text, $ptext, $special);
200  my ($in_format, $in_example, $in_texinfo);
201
202  $length = 0 unless $length;
203  $_ .= "\n";
204  $ptext = $_;
205  while ($ptext =~ /(.*)\n/g)
206  {
207    $pline = $line;
208    $line = $1;
209    # check whether we are in protected env
210    if ($in_format || $in_example || $in_texinfo)
211    {
212      # end protected env?
213      if ($line =~ /^\s*\@end (format|example|texinfo)\s*$/)
214      {
215        if ($in_format && $1 eq 'format')
216        {
217          $in_format = 0;
218          $text .= "$line\n";
219        }
220        elsif ($in_example && $1 eq 'example')
221        {
222          $in_example = 0;
223          $text .= "\@end smallexample\n";
224        }
225        elsif ($in_texinfo && $1 eq 'texinfo')
226        {
227          $in_texinfo = 0;
228          $text .= "\n";
229        }
230        else
231        {
232          $error = "While parsing $parsing: \@end $1 found without matching \@$1" unless $error;
233        }
234        next;
235      }
236      else
237      {
238        $text .= "$line\n";
239        next;
240      }
241    }
242    # look for @example, @format, @texinfo
243    if ($line =~ /^\s*\@(example|format|texinfo)\s*$/)
244    {
245      $special = 1;
246      if ($1 eq 'example')
247      {
248        $text .= "\@smallexample\n";
249        $in_example = 1;
250      }
251      elsif ($1 eq 'format')
252      {
253        $text .= "$line\n";
254        $in_format = 1;
255      }
256      else
257      {
258        $text .= "\n";
259        $in_texinfo = 1;
260      }
261      next;
262    }
263    if ($line =~ /([^\@]|^)\@(code|math){(.*?)}/)
264    {
265      my $l = $line;
266      $l =~ s/^\s*//;
267      $l =~ s/\s$//;
268      while ($l =~ /([^\@]|^)\@(code|math){(.*?)}/)
269      {
270        $text .= CleanAscii($`.$1);
271        $text .= "\@$2\{$3\}";
272        $l = $';
273      }
274      $special = 1;
275      $text .= CleanAscii($l) . "\n";
276      next;
277    }
278    # break line if
279    $text .= '@*' 
280      if ($line =~ /\w/ 
281          && $pline =~ /\w/      # line and prev line are not empty
282          && $line !~ /^\s*\@\*/ # line does not start with @*
283          && $pline !~ /\@\*\s*/ # prev line does not end with @*
284          && length($pline) + $length < 60 # prev line is shorter than 60 chars
285          && ! $special);        # prev line was not special line
286    $line =~ s/^\s*//;
287    $line =~ s/\s$//;
288    $special = 0;
289    $text .= CleanAscii($line) . "\n";
290  }
291  $_ = $text;
292  s/^\s*//;
293  s/\s*$//;
294  $_ .= "\n";
295  if ($in_format || $in_texinfo || $in_example)
296  {
297    $error = "While parsing $parsing: no matching \@end " .
298      ($in_format ? "format" : ($in_texinfo ? "texinfo" : "example" )) .
299        " found"
300          unless $error;
301  }
302}
303
304sub CleanAscii
305{
306  my $a = shift;
307  $a =~ s/(\@([^\*]|$))/\@$1/g; # escape @ signs, except @*, @{, @}
308  $a =~ s/{/\@{/g; # escape {}
309  $a =~ s/}/\@}/g;
310  $a =~ s/\t/ /g;
311  $a =~ s/ +/ /g;         
312  return $a;
313}
314
315sub OutInfoItem
316{
317  my ($FH, $item, $text, $l_fun) = @_;
318  local $parsing  = $parsing . uc($item);
319
320  $item = lc $item;
321  $item = ucfirst $item;
322
323  if ($item =~ /see also/i)
324  {
325    # return references
326    return $text;
327  }
328  elsif ($item =~ m/example/i)
329  {
330    # forget about example, since it comes explicitely
331    return '';
332  }
333  elsif ($item =~ m/procedure/i)
334  {
335    if ($l_fun && $table_is_open)
336    {
337      print $FH "\@end table\n\n";
338      $table_is_open = 0;
339    }
340    $text =~ s/^\s*//;
341    $text =~ s/\s*$//;
342    $text =~ s/.*$// if ($text=~/parameters.*brackets.*are.*optional.*$/);
343    $text .= "\n";
344   
345    my ($proc, $pargs, $pinfo, $line);
346    if ($l_fun)
347    {
348      print $FH "\@strong{$item:}\n\@menu\n";
349    }
350    else
351    {
352      print $FH "\@item \@strong{$item:}\n\@table \@asis\n";
353    }
354    while ($text =~ /(.*\n)/g)
355    {
356      $line = $1;
357      if ($1 =~ /^\s*(\w+)\((.*?)\)/)
358      {
359        OutProcInfo($FH, $proc, $procargs, $pinfo, $l_fun) if $proc && $pinfo;
360        $proc = $1;
361        $procargs = $2;
362        $pinfo = $';
363      }
364      else
365      {
366        $pinfo .= $line; 
367      }
368    }
369    OutProcInfo($FH, $proc, $procargs, $pinfo, $l_fun) if $proc && $pinfo;
370    print $FH ($l_fun ? "\@end menu\n" : "\@end table\n");
371    return '';
372  }
373  elsif ($item =~ m/keywords/i || m/keyphrases/i)
374  {
375    # index entries
376    return OutKeywords($FH, $text);
377  }
378 
379  if (! $table_is_open)
380  {
381    print $FH "\@table \@asis\n";
382    $table_is_open = 1;
383  }
384  print $FH '@item @strong{'. "$item:}\n";
385  # prepare text:
386  local $_ = $text;
387  if (($item =~ m/^library/i)  && m/\s*(\w*)\.lib/)
388  {
389    print $FH "$1.lib\n";
390    $text = $';
391    if ($text =~ /\w/)
392    {
393      print $FH '@item @strong{Purpose:'."}\n";
394      print $FH lc $text;
395    }
396  }
397  else
398  {
399    # just print the text
400    FormatInfoText(length($item) + 1);
401    print $FH "$_\n";
402  }
403  return '';
404}
405
406sub OutProcInfo
407{
408  my($FH, $proc, $procargs, $pinfo, $l_fun) = @_;
409  local $_ = $pinfo;
410  s/^[;\s]*//;
411  s/\n/ /g;
412  FormatInfoText();
413  if ($l_fun)
414  {
415    print $FH "* ${proc}:: $_";
416    push @procs, $proc;
417  }
418  else
419  {
420    print $FH "\@item \@code{$proc($procargs)}  ";
421    print $FH "\n\@cindex $proc\n$_";
422  }
423}
424
425sub OutRef
426{
427  my ($FH, $refs) = @_;
428  $refs =~ s/^\s*//;
429  $refs =~ s/\s*$//;
430  $refs =~ s/\n/,/g;
431  my @refs = split (/[,;\.]+/, $refs);
432  my $ref;
433  print $FH "\@c ref\n";
434  $ref = shift @refs;
435  print $FH "\@ref{$ref}";
436  for $ref (@refs)
437  {
438    $ref =~ s/^\s*//;
439    $ref =~ s/\s*$//;
440    print $FH ", \@ref{$ref}"  if ($ref =~ /\w/);
441  }
442  print $FH "\n\@c ref\n\n";
443
444}
445
446sub OutKeywords
447{
448  my ($FH, $kws) = @_;
449  for $kw (split (/;/, $kws))
450  {
451    $kw =~ s/^\s*(.*?)\s*$/$1/;
452    print $FH "\@cindex $kw\n";
453  }
454}
455
456sub CleanUpExample
457{
458  local($lib, $example) = @_;
459 
460  # find portion in {}
461  $example =~ s/^[^{]*{(.*)}[^}]*$/$1/s;
462
463  if ($example =~ /EXAMPLE: \(not executed\)/)
464  {
465    # erase first three lines
466    $example =~ s/^.*\n.*\n.*\n/\n/;
467    # erase enclosing " " in every line
468    $example =~ s/\n\s*"/\n/g;
469    $example =~  s/";\n/\n/g;
470  }
471  # erase EXAMPLE, echo and pause statements
472  $example =~ s/"EXAMPLE.*"[^;]*;//g;
473  $example .= "\n";
474  my ($mexample, $line);
475  while ($example =~ m/(.*)\n/g)
476  {
477    $line = $1;
478    $line =~ s|echo[^;]*;||g if $line !~ m|(.*)//(.*)echo[^;]*;|;
479    $line =~ s|pause\(.*?\)[^;]*;||g if $line !~ m|(.*)//(.*)pause\(.*?\)[^;]*;|;
480    $mexample .= "$line\n";
481  }
482  $example = $mexample;
483  $example = undef unless $example =~ /\w/;
484  # prepend LIB command
485  $example = "LIB \"$lib.lib\";\n".$example 
486    if ($example && $lib ne "standard");
487  # erase empty lines
488  $example =~ s/^\s*\n//g;
489  # erase spaces from beginning of lines
490  $example =~ s/\n\s*/\n/g;
491  $example =~ s/\s*$//g;
492  return $example;
493}
494
495sub print_doc_header
496{
497  my $fh = shift;
498  ($hlp_file = $out_file) =~ s/doc$/hlp/;
499  print $fh <<EOT;
500\\input texinfo   \@c -*-texinfo-*-
501\@c %**start of header
502\@setfilename $hlp_file
503\@settitle Formatted manual of $lib.lib
504\@paragraphindent 0
505\@c %**end of header
506
507\@ifinfo
508This file documents contains the formatted documentation of $library
509\@end ifinfo
510
511\@titlepage
512\@title Formatted manual of $library
513\@end titlepage
514
515\@node Top, , , (dir)
516
517\@ifnottex
518This file contains the formatted documentation of $library
519\@end ifnottex
520
521\@menu
522* Singular libraries::
523* Index::
524\@end menu
525
526\@node Singular libraries, Index,,Top
527\@comment node-name,next, previous, up
528\@chapter Singular libraries
529
530\@menu
531* ${lib}_lib:: 
532\@end menu
533 
534\@node ${lib}_lib,,,Singular libraries
535\@section ${lib}_lib
536
537\@example
538-------BEGIN OF PART WHICH IS INCLUDED IN MANUAL-----
539\@end example
540
541
542EOT
543}
Note: See TracBrowser for help on using the repository browser.