granicus.if.org Git - zziplib/blob - docs/zzipdoc/functionlistreference.py

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