Permalink
Browse files

try to make the script work a bit better with various projects.

No longer necessary to run the script on all of the xml files
individually, just the "project-docs.sgml" file in the reference
directory.
  • Loading branch information...
1 parent 96b22aa commit 105ab0c02e8e36b27866e9533381f0cd2e87a2f4 @chergert committed Dec 26, 2012
Showing with 45 additions and 7 deletions.
  1. +13 −0 README.md
  2. +32 −7 gtkdoc2man.py
View
@@ -37,3 +37,16 @@ g_ptr_array_unref (3) - arrays of pointers to any type of data, which grow autom
```
Also, Shift+K should work in VIM to see the documentation on the type, macro, or function.
+
+# Building manpages for your project
+
+Make sure you configure your project with --enable-gtk-doc to generate your
+reference documentation. Then run the gtkdoc2man.py script provided in this
+repository.
+
+```sh
+cd doc/reference/my
+/path/to/gtkdoc2man.py -o man/ --prefix=My '--book=My Reference' --section=3 my-docs.sgml
+```
+
+In the example above, the man pages will be placed in the directory man/.
View
@@ -36,6 +36,7 @@
import getopt
import os
from pipes import quote
+from StringIO import StringIO
import sys
import tempfile
@@ -64,8 +65,8 @@ def _rmtmpdir(tmpdir):
os.unlink(os.path.join(tmpdir, f))
os.rmdir(tmpdir)
-def gtkdoc2man(path, output_directory=None, prefix=None, section=3):
- from lxml.etree import parse, HTMLParser
+def gtkdoc2man(path, output_directory=None, prefix=None, section=3, book=None):
+ from lxml.etree import parse
if output_directory is None:
output_directory = os.getcwd()
@@ -77,7 +78,15 @@ def gtkdoc2man(path, output_directory=None, prefix=None, section=3):
try:
# Generate the man page for the gtkdoc section.
- procargs = ['xsltproc', '-o', tmpdir + '/', '-nonet', XSL_URL, path]
+ procargs = ['xsltproc',
+ '-o', tmpdir + '/',
+ '--xinclude',
+ '--stringparam', 'gtkdoc.bookname', "BLAHBLAH",
+ '--stringparam', 'chunk.quietly', '1',
+ '--stringparam', 'chunker.output.quiet', '1',
+ '-nonet',
+ XSL_URL,
+ path]
command = ' '.join([quote(a) for a in procargs])
os.system(command)
@@ -97,8 +106,19 @@ def gtkdoc2man(path, output_directory=None, prefix=None, section=3):
print >> sys.stderr, 'Nothing processed in', path
return
+ # Load in the documentation file.
+ data = file(path).read()
+
+ # Inject xmlns:xi="" so that the XML parser can follow xinclude
+ # paths. Pretty annoying that this isn't done by default.
+ idx = data.index('<book')
+ assert idx, 'Cannot find <book> in XML document.'
+ data = data[:idx + 5] + ' xmlns:xi="http://www.w3.org/2001/XInclude" ' + data[idx+5:]
+ data = StringIO(data)
+
# Generate the links to the generated manpage.
- tree = parse(path, parser=HTMLParser())
+ tree = parse(data)
+ tree.xinclude()
for child in tree.iter():
if child.tag == 'refsect2':
if 'id' in child.attrib and 'role' in child.attrib:
@@ -120,11 +140,12 @@ def usage(stream=sys.stdout):
-s --section=3 The manual section [Default is 3]
-o --output-directory=DIR Set the output directory.
-p --prefix=PREFIX Prefix output filenames.
+ -b --book=NAME The book name.
""" % sys.argv[0]
if __name__ == '__main__':
- longArgs = ['output-directory=', 'prefix=', 'help', 'check', 'section=']
- shortArgs = 'o:p:hcs:'
+ longArgs = ['output-directory=', 'prefix=', 'help', 'check', 'section=', 'book=']
+ shortArgs = 'o:p:hcs:b:'
argv = sys.argv[1:]
try:
@@ -137,6 +158,7 @@ def usage(stream=sys.stdout):
outdir = None
prefix = None
section = 3
+ book = None
for o,a in opts:
if o in ('-h', '--help'):
@@ -159,12 +181,15 @@ def usage(stream=sys.stdout):
section = int(a)
assert section >= 0
assert section < 10
+ elif o in ('-b', '--book'):
+ book = a
for path in args:
if os.path.exists(path):
gtkdoc2man(path,
output_directory=outdir,
prefix=prefix,
- section=section)
+ section=section,
+ book=book)
sys.exit(0)

0 comments on commit 105ab0c

Please sign in to comment.