docs/devel/build-eplugin-manual.pl

   1 #!/usr/bin/perl
   2
   3 #
   4 # API reference
   5 #
   6
   7 %byref = ( 'e-popup.xml' =>
   8            { 'files' => [ 'e-popup.h', 'e-popup.c' ],
   9              'module' => 'e-util' },
  10
  11            'e-menu.xml' =>
  12            { 'files' => [ 'e-menu.h', 'e-menu.c' ],
  13              'module' => 'e-util' },
  14
  15            'e-event.xml' =>
  16            { 'files' => [ 'e-event.h', 'e-event.c' ],
  17              'module' => 'e-util' },
  18
  19            'e-config.xml' =>
  20            { 'files' => [ 'e-config.h', 'e-config.c' ],
  21              'module' => 'e-util' },
  22
  23            'e-plugin.xml' =>
  24            { 'files' => [ 'e-plugin.h', 'e-plugin.c' ],
  25              'module' => 'e-util' },
  26
  27            'e-import.xml' =>
  28            { 'files' => [ 'e-import.h', 'e-import.c' ],
  29              'module' => 'e-util' },
  30
  31            'em-popup.xml' =>
  32            { 'files' => [ 'em-popup.h', 'em-popup.c' ],
  33              'module' => 'mail' },
  34
  35            'em-format.xml' =>
  36            { 'files' => [ 'em-format-hook.h' , 'em-format-hook.c',
  37                           'em-format.h', 'em-format.c',
  38                           'em-format-html.h', 'em-format-html.c' ],
  39              'module' => 'mail' },
  40            );
  41
  42 foreach $out (keys %byref) {
  43     print "file $out\n";
  44     %data = %{$byref{$out}};
  45     @files = @{$data{'files'}};
  46     $module = $data{'module'};
  47     $files = "";
  48     foreach $file (@files) {
  49         $files .= " ../../".$module."/".$file;
  50     }
  51     system("kernel-doc -docbook $files > $out");
  52 }
  53
  54 #
  55 # Event reference
  56 #
  57
  58 # %events = ( 'em-events.xml' =>
  59 #           { 'files' => [ 'em-folder-view.c', 'em-composer-utils.c', 'mail-folder-cache.c' ],
  60 #             'module' => 'mail' },
  61 #           );
  62
  63 # foreach $out (keys %events) {
  64 #     print "generating events doc $out\n";
  65 #     %data = %{$events{$out}};
  66 #     @files = @{$data{'files'}};
  67 #     $module = $data{'module'};
  68 #     open OUT,">$out";
  69 #     foreach $file (@files) {
  70 #       open IN,"<../../$module/$file";
  71 #       while (<IN>) {
  72 #           if (m/\@Event: (.*)/) {
  73 #               $title = $1;
  74 #               $name = $1;
  75 #               $target = "";
  76 #               while (<IN>) {
  77 #                   if (m/\@Title: (.*)/) {
  78 #                       $title = $1;
  79 #                   } elsif (m/\@Target: (.*)/) {
  80 #                       $target = $1;
  81 #                   } elsif (m/\* (.*)/) {
  82 #                       $desc.= $1."\n";
  83 #                   }
  84 #                   last if (m/\*\//);
  85 #               }
  86 #               if ($target eq "") {
  87 #                   print "Warning: No target defined for event $name ($title)\n";
  88 #               }
  89 #               print OUT <<END;
  90 #       <sect2>
  91 #         <title>$title</title>
  92 #         <informaltable>
  93 #           <tgroup cols="2">
  94 #             <colspec colnum="1" colname="field" colwidth="1*"/>
  95 #             <colspec colnum="2" colname="value" colwidth="4*"/>
  96 #             <tbody valign="top">
  97 #               <row>
  98 #                 <entry>Name</entry>
  99 #                 <entry><constant>$name</constant></entry>
 100 #               </row>
 101 #               <row>
 102 #                 <entry>Target</entry>
 103 #                 <entry>
 104 #                   <link
 105 #                     linkend="$module-hooks-event-$target">$target</link>
 106 #                 </entry>
 107 #               </row>
 108 #               <row>
 109 #                 <entry>Description</entry>
 110 #                 <entry>
 111 #                 <simpara>
 112 #                 $desc
 113 #                 </simpara>
 114 #                 </entry>
 115 #               </row>
 116 #             </tbody>
 117 #           </tgroup>
 118 #         </informaltable>
 119 #       </sect2>
 120 # END
 121 #           }
 122 #       }
 123 #       close IN;
 124 #     }
 125 #     close OUT;
 126 # }
 127
 128 #
 129 # Generic table builder, still experimental.
 130 #
 131
 132 sub buildxml {
 133     my $type = $_[0];
 134     my $out = $_[1];
 135     my %data = %{$_[2]};
 136     my @files, $module;
 137     my $line;
 138
 139     print "generating doc $out for $type\n";
 140     @files = @{$data{'files'}};
 141     $module = $data{'module'};
 142     open OUT,">$out";
 143     foreach $file (@files) {
 144         my $line = 0;
 145
 146         open IN,"<../../$module/$file" || die ("Cannot open \"$module/$file\"");
 147         while (<IN>) {
 148             if (m/\/\*\* \@$type: (.*)/) {
 149                 my $key = "";
 150                 my $val = "";
 151                 my $desc = 0;
 152                 my $title = $1;
 153                 my %blob = { };
 154                 my @blobs = ();
 155
 156                 while (<IN>) {
 157                     $line++;
 158                     if (m/\@(.*): (.*)/) {
 159                         if ($val ne "") {
 160                             $blob{$key} = $val;
 161                         }
 162                         $key = $1;
 163                         $val = $2;
 164                         push @blobs, $key;
 165                     } elsif (m/\* (.+)/) {
 166                         $val .= $1."\n";
 167                     } else {
 168                         if ($desc == 0) {
 169                             if ($val ne "") {
 170                                 $blob{$key} = $val;
 171                             }
 172                             $val = "";
 173                             $key = "";
 174                         } else {
 175                             $val .= "\n";
 176                         }
 177                         if (m/\*\s*$/) {
 178                             $desc = 1;
 179                         }
 180                     }
 181                     last if (m/\*\//);
 182                 }
 183                 print OUT<<END;
 184         <sect2>
 185           <title>$title</title>
 186 END
 187                 if ($val ne "") {
 188                     $val =~ s/[\n]+$//gos;
 189                     $val =~ s/\n\n/\<\/simpara\>\n\<simpara\>/g;
 190                     print OUT "<simpara>$val</simpara>\n";
 191                 }
 192                 print OUT <<END;
 193           <informaltable>
 194             <tgroup cols="2">
 195               <colspec colnum="1" colname="field" colwidth="1*"/>
 196               <colspec colnum="2" colname="value" colwidth="4*"/>
 197               <tbody valign="top">
 198 END
 199
 200                 foreach $key (@blobs) {
 201                     print OUT <<END;
 202                 <row>
 203                   <entry>$key</entry>
 204                   <entry>$blob{$key}</entry>
 205                 </row>
 206 END
 207 }
 208                 print OUT <<END;
 209                 <row>
 210                   <entry>Defined</entry>
 211                   <entry>$module/$file:$line</entry>
 212                 </row>
 213               </tbody>
 214             </tgroup>
 215           </informaltable>
 216         </sect2>
 217 END
 218             }
 219             $line++;
 220         }
 221         close IN;
 222     }
 223     close OUT;
 224 }
 225
 226
 227 %hooks = ( 'es-hooks.xml' =>
 228             { 'type' => 'HookClass',
 229               'files' => [ 'es-menu.c', 'es-event.c' ],
 230               'module' => 'shell' },
 231            'es-menus.xml' =>
 232             { 'type' => 'HookPoint',
 233               'files' => [ 'e-shell-window.c' ],
 234               'module' => 'shell' },
 235            'es-importers.xml' =>
 236             { 'type' => 'HookClass',
 237               'files' => [ 'e-import.c' ],
 238               'module' => 'e-util' },
 239            'es-events.xml' =>
 240             { 'type' => 'Event',
 241               'files' => [ 'e-shell.c' ],
 242               'module' => 'shell' },
 243            'em-events.xml' =>
 244             { 'type' => 'Event',
 245               'files' => [ 'em-folder-view.c', 'em-composer-utils.c', 'mail-folder-cache.c' ],
 246               'module' => 'mail' },
 247            'em-popups.xml' =>
 248             { 'type' => 'HookPoint-EMPopup',
 249               'files' => [ 'em-folder-tree.c', 'em-folder-view.c', 'em-format-html-display.c', '../composer/e-msg-composer-attachment-bar.c' ],
 250               'module' => 'mail' },
 251            'ecal-popups.xml' =>
 252             { 'type' => 'HookPoint-ECalPopup',
 253               'files' => [ 'gui/e-calendar-view.c', 'gui/calendar-component.c', 'gui/e-calendar-view.c', 'gui/tasks-component.c' ],
 254               'module' => 'calendar' },
 255            'em-configs.xml' =>
 256             { 'type' => 'HookPoint-EMConfig',
 257               'files' => [ 'em-mailer-prefs.c', 'em-account-editor.c', 'em-folder-properties.c', 'em-composer-prefs.c' ],
 258               'module' => 'mail' },
 259            'em-menus.xml' =>
 260             { 'type' => 'HookPoint-EMMenu',
 261               'files' => [ 'em-folder-browser.c', 'em-message-browser.c' ],
 262               'module' => 'mail' },
 263             );
 264
 265 foreach $out (keys %hooks) {
 266     %data = %{$hooks{$out}};
 267
 268     &buildxml($data{'type'}, $out, \%data);
 269 }
 270
 271 # this works on my system; you need the docbook-xsl-stylesheets package and xsltproc
 272 system("xsltproc /usr/share/xml/docbook/stylesheet/nwalsh/current/html/tldp-sections.xsl evolution-plugin-manual.xml");