On Fri, Sep 25, 2009 at 03:33:41PM +0200, Daniel Veillard wrote:
> On Fri, Sep 25, 2009 at 01:28:51PM +0100, Daniel P. Berrange wrote:
> > The python method help docs are copied across from the C
> > funtion comments, but in the process all line breaks and
> > indentation was being lost. This made the resulting text
> > and code examples completely unreadable. Both the API
> > doc extractor and the python generator were destroying
> > whitespace & this fixes them to preserve it exactly.
> >
> > * docs/apibuild.py: Preserve all whitespace when extracting
> > function comments. Print function comment inside a <![CDATA[
> > section to fully preserve all whitespace. Look for the
> > word 'returns' to describe return values, instead of 'return'
> > to avoid getting confused with code examples including the
> > C 'return' statement.
> > * python/generator.py: Preserve all whitespace when printing
> > function help docs
> > * src/libvirt.c: Change any return parameter indicated by
> > 'return' to be 'returns', to avoid confusing the API extractor
> [...]
> > if desc != None and desc != "":
> > - output.write(" <info>%s</info>\n" % (escape(desc)))
> > + output.write(" <info><![CDATA[%s]]></info>\n" % (desc))
>
> Ah, okay you're using CDATA !
>
> > self.indexString(name, desc)
> > for arg in args:
> > (name, desc) = arg
> > @@ -1760,7 +1771,7 @@ class docBuilder:
> > try:
> > desc = id.extra
> > if desc != None and desc != "":
> > - output.write(">\n <info>%s</info>\n" % (escape(desc)))
> > + output.write(">\n <info><![CDATA[%s]]></info>\n" % (desc))
> > output.write(" </typedef>\n")
> > else:
> > output.write("/>\n")
> > @@ -1796,7 +1807,7 @@ class docBuilder:
> > output.write(" <cond>%s</cond>\n"% (apstr));
> > try:
> > (ret, params, desc) = id.info
> > - output.write(" <info>%s</info>\n" % (escape(desc)))
> > + output.write(" <info><![CDATA[%s]]></info>\n" % (desc))
> > self.indexString(name, desc)
> > if ret[0] != None:
> > if ret[0] == "void":
> > diff --git a/python/generator.py b/python/generator.py
> > index c34cb34..178a415 100755
> > --- a/python/generator.py
> > +++ b/python/generator.py
> > @@ -44,6 +44,7 @@ if sgmlop:
> > self.finish_starttag = target.start
> > self.finish_endtag = target.end
> > self.handle_data = target.data
> > + self.handle_cdata = target.cdata
> >
> > # activate parser
> > self.parser = sgmlop.XMLParser()
> > @@ -78,6 +79,7 @@ class SlowParser(xmllib.XMLParser):
> > def __init__(self, target):
> > self.unknown_starttag = target.start
> > self.handle_data = target.data
> > + self.handle_cdata = target.cdata
> > self.unknown_endtag = target.end
> > xmllib.XMLParser.__init__(self)
> >
> > @@ -108,6 +110,11 @@ class docParser:
> > print "data %s" % text
> > self._data.append(text)
> >
> > + def cdata(self, text):
> > + if debug:
> > + print "data %s" % text
> > + self._data.append(text)
> > +
> > def start(self, tag, attrs):
>
> Okay makes sense, plus the large amount of return -> Returns changes
>
> ACK !
>
> I'm still waiting to see what this gives in the HTML docs :-)
Hmm, I didn't check that yet, but I guess it shouldn't make any
difference, since the HTML will still collapse the whitespace
as before - we'd need to insert real <p> breaks & use <pre>
during generation of the HTML if we wanted to maintain any kind
of sane formatting
Daniel
--
|: Red Hat, Engineering, London -o- http://people.redhat.com/berrange/ :|
|: http://libvirt.org -o- http://virt-manager.org -o- http://ovirt.org :|
|: http://autobuild.org -o- http://search.cpan.org/~danberr/ :|
|: GnuPG: 7D3B9505 -o- F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|
--
Libvir-list mailing list
Libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list