source/libs/zziplib/zziplib-0.13.62/docs/zzipdoc/functionlistreference.py

   1 #! /usr/bin/env python
   2 # -*- coding: UTF-8 -*-
   3 from match import Match
   4 from htm2dbk import *
   5
   6 class FunctionListReference:
   7     """ Creating a docbook-style <reference> list of <refentry> parts
   8     that will each be translated into a unix manual page in a second step """
   9     def __init__(self, o = None):
  10         self.o = o
  11         self.pages = []
  12         self.entry = None
  13     def cut(self):
  14         if not self.entry: return
  15         self.pages += [ self.entry ]
  16         self.entry = None
  17     def add(self, entry):
  18         name = entry.get_name()
  19         description = entry.body_xml_text(name)
  20         funcsynopsis = entry.head_xml_text()
  21         if not funcsynopsis:
  22             print "no funcsynopsis for", name
  23             return
  24         if self.entry is None:
  25             self.entry = FunctionListRefEntry(entry, self.o)
  26             self.entry.funcsynopsisinfo = entry.get_mainheader()
  27             self.entry.refpurpose = entry.get_title()
  28             self.entry.refentrytitle = entry.get_name()
  29             # self.entry.refname = entry.get_name()
  30         self.entry.funcsynopsis_list += [ funcsynopsis ]
  31         self.entry.description_list += [ description ]
  32         self.entry.refname_list += [ name ]
  33         if entry.list_seealso():
  34             for item in entry.list_seealso():
  35                 if item not in self.entry.seealso_list:
  36                     self.entry.seealso_list += [ item ]
  37     def get_title(self):
  38         return self.o.package+" Function List"
  39     def xml_text(self):
  40         T = "<reference><title>"+self.get_title()+"</title>\n"
  41         for item in self.pages:
  42             text = item.refentry_text()
  43             if not text: "OOPS, no text for", item.name ; continue
  44             T += self.sane(text)
  45         T += "</reference>\n"
  46         return T
  47     def sane(self, text):
  48         return (html2docbook(text)
  49                 .replace("<link>","<function>")
  50                 .replace("</link>","</function>")
  51                 .replace("<fu:protospec>","<funcprototype>")
  52                 .replace("</fu:protospec>","</funcprototype>")
  53                 .replace("<fu:prespec>","<funcdef>")
  54                 .replace("</fu:prespec>","")
  55                 .replace("<fu:namespec>","")
  56                 .replace("</fu:namespec>","</funcdef>")
  57                 .replace("</fu:callspec>","</paramdef>")
  58                 .replace("<fu:callspec>","<paramdef>"))
  59
  60
  61 class FunctionListRefEntry:
  62     def __init__(self, func, o):
  63         """ initialize the fields needed for a man page entry - the fields are
  64            named after the docbook-markup that encloses (!!) the text we store
  65            the entries like X.refhint = "hello" will be printed therefore as
  66            <refhint>hello</refhint>. Names with underscores are only used as
  67            temporaries but they are memorized, perhaps for later usage. """
  68         self.name = func.get_name()
  69         self.refhint = "\n<!--========= "+self.name+" (3) ============-->\n"
  70         self.refentry = None
  71         self.refentry_date = o.version.strip()        #! //refentryinfo/date
  72         self.refentry_productname = o.package.strip() #! //refentryinfo/prod*
  73         self.refentry_title = None                    #! //refentryinfo/title
  74         self.refentryinfo = None                      #! override
  75         self.manvolnum = "3"                         # //refmeta/manvolnum
  76         self.refentrytitle = None                    # //refmeta/refentrytitle
  77         self.refmeta = None                          # override
  78         self.refpurpose = None                       # //refnamediv/refpurpose
  79         self.refname = None                          # //refnamediv/refname
  80         self.refname_list = []
  81         self.refnamediv = None                       # override
  82         self.mainheader = func.get_mainheader()
  83         self.includes = func.get_includes()
  84         self.funcsynopsisinfo = ""       # //funcsynopsisdiv/funcsynopsisinfo
  85         self.funcsynopsis = None         # //funcsynopsisdiv/funcsynopsis
  86         self.funcsynopsis_list = []
  87         self.description = None
  88         self.description_list = []
  89         # optional sections
  90         self.authors_list = []           # //sect1[authors]/listitem
  91         self.authors = None              # override
  92         self.copyright = None
  93         self.copyright_list = []
  94         self.seealso = None
  95         self.seealso_list = []
  96         if  func.list_seealso():
  97             for item in func.list_seealso():
  98                 self.seealso_list += [ item ]
  99         self.file_authors = None
 100         if  func.get_authors():
 101             self.file_authors = func.get_authors()
 102             self.authors_list += [ self.file_authors ]
 103         self.file_copyright = None
 104         if  func.get_copyright():
 105             self.file_copyright = func.get_copyright()
 106             self.copyright_list += [ self.file_copyright ]
 107     #fu
 108     def refentryinfo_text(self):
 109         """ the manvol formatter wants to render a footer line and header line
 110             on each manpage and such info is set in <refentryinfo> """
 111         if self.refentryinfo:
 112             return self.refentryinfo
 113         if self.refentry_date and \
 114            self.refentry_productname and \
 115            self.refentry_title: return (
 116             "\n <date>"+self.refentry_date+"</date>"+
 117             "\n <productname>"+self.refentry_productname+"</productname>"+
 118             "\n <title>"+self.refentry_title+"</title>")
 119         if self.refentry_date and \
 120            self.refentry_productname: return (
 121             "\n <date>"+self.refentry_date+"</date>"+
 122             "\n <productname>"+self.refentry_productname+"</productname>")
 123         return ""
 124     def refmeta_text(self):
 125         """ the manvol formatter needs to know the filename of the manpage to
 126             be made up and these parts are set in <refmeta> actually """
 127         if self.refmeta:
 128             return self.refmeta
 129         if self.manvolnum and self.refentrytitle:
 130             return (
 131                 "\n <refentrytitle>"+self.refentrytitle+"</refentrytitle>"+
 132                 "\n <manvolnum>"+self.manvolnum+"</manvolnum>")
 133         if self.manvolnum and self.name:
 134             return (
 135                 "\n <refentrytitle>"+self.name+"</refentrytitle>"+
 136                 "\n <manvolnum>"+self.manvolnum+"</manvolnum>")
 137         return ""
 138     def refnamediv_text(self):
 139         """ the manvol formatter prints a header line with a <refpurpose> line
 140             and <refname>'d functions that are described later. For each of
 141             the <refname>s listed here, a mangpage is generated, and for each
 142             of the <refname>!=<refentrytitle> then a symlink is created """
 143         if self.refnamediv:
 144             return self.refnamediv
 145         if self.refpurpose and self.refname:
 146             return ("\n <refname>"+self.refname+'</refname>'+
 147                     "\n <refpurpose>"+self.refpurpose+" </refpurpose>")
 148         if self.refpurpose and self.refname_list:
 149             T = ""
 150             for refname in self.refname_list:
 151                 T += "\n <refname>"+refname+'</refname>'
 152             T += "\n <refpurpose>"+self.refpurpose+" </refpurpose>"
 153             return T
 154         return ""
 155     def funcsynopsisdiv_text(self):
 156         """ refsynopsisdiv shall be between the manvol mangemaent information
 157             and the reference page description blocks """
 158         T=""
 159         if self.funcsynopsis:
 160             T += "\n<funcsynopsis>"
 161             if self.funcsynopsisinfo:
 162                 T += "\n<funcsynopsisinfo>"+    self.funcsynopsisinfo + \
 163                      "\n</funcsynopsisinfo>\n"
 164             T += self.funcsynopsis + \
 165                  "\n</funcsynopsis>\n"
 166         if self.funcsynopsis_list:
 167             T += "\n<funcsynopsis>"
 168             if self.funcsynopsisinfo:
 169                 T += "\n<funcsynopsisinfo>"+    self.funcsynopsisinfo + \
 170                      "\n</funcsynopsisinfo>\n"
 171             for funcsynopsis in self.funcsynopsis_list:
 172                 T += funcsynopsis
 173             T += "\n</funcsynopsis>\n"
 174         #fi
 175         return T
 176     def description_text(self):
 177         """ the description section on a manpage is the main part. Here
 178             it is generated from the per-function comment area. """
 179         if self.description:
 180             return self.description
 181         if self.description_list:
 182             T = ""
 183             for description in self.description_list:
 184                 if not description: continue
 185                 T += description
 186             if T.strip() != "": return T
 187         return "<para>(missing description)</para>"
 188     def authors_text(self):
 189         """ part of the footer sections on a manpage and a description of
 190             original authors. We prever an itimizedlist to let the manvol
 191             show a nice vertical aligment of authors of this ref item """
 192         if self.authors:
 193             return self.authors
 194         if self.authors_list:
 195             T = "<itemizedlist>"
 196             previous=""
 197             for authors in self.authors_list:
 198                 if not authors: continue
 199                 if previous == authors: continue
 200                 T += "\n <listitem><para>"+authors+"</para></listitem>"
 201                 previous = authors
 202             T += "</itemizedlist>"
 203             return T
 204         if self.authors:
 205             return self.authors
 206         return ""
 207     def copyright_text(self):
 208         """ the copyright section is almost last on a manpage and purely
 209             optional. We list the part of the per-file copyright info """
 210         if self.copyright:
 211             return self.copyright
 212         """ we only return the first valid instead of merging them """
 213         if self.copyright_list:
 214             T = ""
 215             for copyright in self.copyright_list:
 216                 if not copyright: continue
 217                 return copyright # !!!
 218         return ""
 219     def seealso_text(self):
 220         """ the last section on a manpage is called 'SEE ALSO' usally and
 221             contains a comma-separated list of references. Some manpage
 222             viewers can parse these and convert them into hyperlinks """
 223         if self.seealso:
 224             return self.seealso
 225         if self.seealso_list:
 226             T = ""
 227             for seealso in self.seealso_list:
 228                 if not seealso: continue
 229                 if T: T += ", "
 230                 T += seealso
 231             if T: return T
 232         return ""
 233     def refentry_text(self, id=None):
 234         """ combine fields into a proper docbook refentry """
 235         if id is None:
 236             id = self.refentry
 237         if id:
 238             T = '<refentry id="'+id+'">'
 239         else:
 240             T = '<refentry>' # this is an error
 241
 242         if self.refentryinfo_text():
 243             T += "\n<refentryinfo>"+       self.refentryinfo_text()+ \
 244                  "\n</refentryinfo>\n"
 245         if self.refmeta_text():
 246             T += "\n<refmeta>"+            self.refmeta_text() + \
 247                  "\n</refmeta>\n"
 248         if self.refnamediv_text():
 249             T += "\n<refnamediv>"+         self.refnamediv_text() + \
 250                  "\n</refnamediv>\n"
 251         if self.funcsynopsisdiv_text():
 252             T += "\n<refsynopsisdiv>\n"+   self.funcsynopsisdiv_text()+ \
 253                  "\n</refsynopsisdiv>\n"
 254         if self.description_text():
 255             T += "\n<refsect1><title>Description</title> " + \
 256                  self.description_text() + "\n</refsect1>"
 257         if self.authors_text():
 258             T += "\n<refsect1><title>Author</title> " + \
 259                  self.authors_text() + "\n</refsect1>"
 260         if self.copyright_text():
 261             T += "\n<refsect1><title>Copyright</title> " + \
 262                  self.copyright_text() + "\n</refsect1>\n"
 263         if self.seealso_text():
 264             T += "\n<refsect1><title>See Also</title><para> " + \
 265                  self.seealso_text() + "\n</para></refsect1>\n"
 266
 267         T +=  "\n</refentry>\n"
 268         return T
 269     #fu
 270 #end