3 # External command, intended to be called with custom_target() in meson.build
6 # tutorial-custom-cmd.py <subcommand> <xxx>...
13 subcommand = sys.argv[1]
17 # <input_xml_file> <output_html_dir>
19 input_xml_file = sys.argv[2]
20 output_html_dir = sys.argv[3]
22 # Set the use.id.as.filename param so that we don't use the chapter / section
23 # number as the filename, otherwise the url will change every time anything is
24 # re-ordered or inserted in the documentation.
25 # For a list of available parameters, see http://docbook.sourceforge.net/release/xsl/current/doc/html/
27 '--param', 'toc.section.depth', '1',
28 '--stringparam', 'chunker.output.indent', 'yes',
29 '--stringparam', 'chunker.output.encoding', 'UTF-8',
30 '--stringparam', 'toc.list.type', 'ul',
31 '--param', 'use.id.as.filename', '1',
34 # The recommended stylesheet for DocBook V5.0 is .../xsl-ns/...
35 # It's not used here because the docbook-xsl-ns package is not available
36 # when building with gnome-build-meta.
37 xslt_stylesheet = 'http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl'
39 # Remove old files and create the destination directory.
40 shutil.rmtree(output_html_dir, ignore_errors=True)
41 os.makedirs(output_html_dir, exist_ok=True)
46 '-o', output_html_dir + '/',
51 result = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
52 universal_newlines=True)
53 # xsltproc prints the names of all written files. Don't print those lines.
54 for line in result.stdout.splitlines():
55 if not line.startswith('Writing '):
58 return result.returncode
61 from pathlib import Path
63 # argv[2] argv[3] argv[4]
64 # <validate> <input_xml_file> <stamp_file_path>
66 validate = sys.argv[2]
67 input_xml_file = sys.argv[3]
68 stamp_file_path = sys.argv[4]
70 relax_ng_schema = 'http://docbook.org/xml/5.0/rng/docbook.rng'
71 # schematron_schema = 'http://docbook.org/xml/5.0/sch/docbook.sch'
73 # Validation against the Schematron schema does not work on Ubuntu 21.04:
74 # file:///usr/share/xml/docbook/schema/schematron/5.0/docbook.sch:6: element rule:
75 # Schemas parser error : Failed to compile context expression db:firstterm[@linkend]
77 # Schematron schema http://docbook.org/xml/5.0/sch/docbook.sch failed to compile
85 if validate == 'true':
87 '--relaxng', relax_ng_schema,
88 #'--schematron', schematron_schema,
90 cmd += [input_xml_file]
91 result = subprocess.run(cmd)
93 return result.returncode
95 Path(stamp_file_path).touch(exist_ok=True)
98 # dblatex and xsltproc+fop generate a PDF file.
99 # docbook2pdf can generate PDF files from DocBook4 files, but not from DocBook5 files.
100 # xsltproc+xmlroff (version 0.6.3) does not seem to work acceptably.
103 # <input_xml_file> <output_pdf_file>
104 # Create a PDF file, using dblatex.
106 input_xml_file = sys.argv[2]
107 output_pdf_file = sys.argv[3]
109 # For a list of available parameters, see http://dblatex.sourceforge.net/doc/manual/
111 '-P', 'toc.section.depth=1',
112 '-P', 'paper.type=a4paper',
113 '-P', 'doc.collab.show=1',
114 '-P', 'latex.output.revhistory=0',
119 ] + dblatex_params + [
120 '-o', output_pdf_file,
124 return subprocess.run(cmd).returncode
128 # <input_xml_file> <output_pdf_file>
129 # Create a PDF file, using fop.
131 input_xml_file = sys.argv[2]
132 output_pdf_file = sys.argv[3]
134 fo_file = os.path.splitext(output_pdf_file)[0] + '.fo'
136 # For a list of available parameters, see http://docbook.sourceforge.net/release/xsl/current/doc/fo/
137 # For a list of available paper types, see the description of the page.width.portrait parameter.
139 '--param', 'toc.section.depth', '1',
140 '--stringparam', 'fop1.extensions', '1',
141 '--stringparam', 'page.orientation', 'portrait',
142 '--stringparam', 'paper.type', 'A4',
145 xslt_stylesheet = 'http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl'
147 # Generate a .fo (formatting object) file.
148 # fop can take an xslt stylesheet parameter, but it can only read local files.
149 # xsltproc is necessary if you want to read the stylesheet from the internet.
158 result = subprocess.run(cmd)
159 if result.returncode:
160 return result.returncode
165 '-pdf', output_pdf_file,
167 return subprocess.run(cmd).returncode
169 # Invoked from meson.add_dist_script().
171 # argv[2] argv[3] argv[4] argv[5]
172 # <doc_dist_dir> <doc_build_dir> <xml_file> <pdf_file>
174 # <doc_dist_dir> is a distribution directory, relative to MESON_PROJECT_DIST_ROOT.
175 # <doc_build_dir> is a relative or absolute path in the build directory.
176 # <xml_file> is a relative or absolute path in the source directory.
177 # <pdf_file> is a relative or absolute path in the build directory.
179 # MESON_PROJECT_DIST_ROOT is set only if meson.version() >= 0.58.0.
180 project_dist_root = os.getenv('MESON_PROJECT_DIST_ROOT', os.getenv('MESON_DIST_ROOT'))
181 doc_dist_dir = os.path.join(project_dist_root, sys.argv[2])
182 doc_build_dir = sys.argv[3]
183 xml_file = sys.argv[4]
184 pdf_file = sys.argv[5]
186 # Create the distribution directory, if it does not exist.
187 os.makedirs(doc_dist_dir, exist_ok=True)
189 # Distribute built html files.
190 shutil.copytree(os.path.join(doc_build_dir, 'html'),
191 os.path.join(doc_dist_dir, 'html'),
192 copy_function=shutil.copy)
194 # If there is an updated PDF file, distribute it.
195 if os.path.isfile(pdf_file) and \
196 os.stat(pdf_file).st_mtime > os.stat(xml_file).st_mtime:
197 shutil.copy(pdf_file, doc_dist_dir)
199 print('--- Info: No updated PDF file found.')
204 if subcommand == 'html':
206 if subcommand == 'xmllint':
208 if subcommand == 'dblatex':
210 if subcommand == 'fop':
212 if subcommand == 'dist_doc':
214 print(sys.argv[0], ': illegal subcommand,', subcommand)