doc: make pandoc optional (#2866)

Since it's currently unavailable on RHEL 9.
This commit is contained in:
Kleis Auke Wolthuizen 2022-06-15 11:19:49 +02:00 committed by GitHub
parent e0b5eeecde
commit 9c22d74cff
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 55 additions and 35 deletions

View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="utf-8" ?> <?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<refentry id="Cite.md"> <refentry id="Cite">
<para> <para>

View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="utf-8" ?> <?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<refentry id="Examples.md"> <refentry id="Examples">
<para> <para>

View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="utf-8" ?> <?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<refentry id="How-it-opens-files.md"> <refentry id="How-it-opens-files">
<para> <para>

View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="utf-8" ?> <?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<refentry id="How-it-works.md"> <refentry id="How-it-works">
<para> <para>
@ -55,7 +55,7 @@ VipsPel *pixel = VIPS_REGION_ADDR( region, x, y );
g_object_unref( region ); g_object_unref( region );
</programlisting> </programlisting>
<para> <para>
The action that <literal>vips_region_prepare()</literal> takes varies with the type of image. If the image is a file on disc, for example, then VIPS will arrange for a refsect3 of the file to be read in. The action that <literal>vips_region_prepare()</literal> takes varies with the type of image. If the image is a file on disc, for example, then VIPS will arrange for a section of the file to be read in.
</para> </para>
<para> <para>
(* there is an image access mode where you can just use a pointer, but its rarely used) (* there is an image access mode where you can just use a pointer, but its rarely used)
@ -136,7 +136,7 @@ g_object_unref( region );
<emphasis role="strong">Data sources</emphasis> <emphasis role="strong">Data sources</emphasis>
</para> </para>
<para> <para>
VIPS has data sources which can supply pixels for processing from a variety of sources. VIPS can stream images from files in VIPS native format, from tiled TIFF files, from binary PPM/PGM/PBM/PFM, from Radiance (HDR) files, from FITS images and from tiled OpenEXR images. VIPS will automatically unpack other formats to temporary disc files for you but this can obviously generate a lot of disc traffic. It also has a special sequential mode for streaming operations on non-random-access formats. Another refsect3 in these docs explains <ulink url="How-it-opens-files.md.html">how libvips opens a file</ulink>. One of the sources uses the <ulink VIPS has data sources which can supply pixels for processing from a variety of sources. VIPS can stream images from files in VIPS native format, from tiled TIFF files, from binary PPM/PGM/PBM/PFM, from Radiance (HDR) files, from FITS images and from tiled OpenEXR images. VIPS will automatically unpack other formats to temporary disc files for you but this can obviously generate a lot of disc traffic. It also has a special sequential mode for streaming operations on non-random-access formats. Another section in these docs explains <ulink url="How-it-opens-files.md.html">how libvips opens a file</ulink>. One of the sources uses the <ulink
url="http://www.imagemagick.org">ImageMagick</ulink> (or optionally <ulink url="http://www.imagemagick.org">ImageMagick</ulink> (or optionally <ulink
url="http://www.graphicsmagick.org">GraphicsMagick</ulink> library, so VIPS can read any image format that these libraries can read. url="http://www.graphicsmagick.org">GraphicsMagick</ulink> library, so VIPS can read any image format that these libraries can read.
</para> </para>

View File

@ -127,7 +127,7 @@ HTML_IMAGES = \
# pandoc makes section headers, we want refsect3 for gtk-doc # pandoc makes section headers, we want refsect3 for gtk-doc
.md.xml: .md.xml:
pandoc -s --template="$(realpath pandoc-docbook-template.docbook)" --wrap=none -V title="$<" -f markdown+smart -t docbook -o $@ $< pandoc -s --template="$(realpath pandoc-docbook-template.docbook)" --wrap=none -V title="$<" -f markdown+smart -t docbook -o $@ $<
sed -e s/section/refsect3/g < $@ > x.$@ && mv x.$@ $@ sed -i -e 's|<section|<refsect3|g' -e 's|</section|</refsect3|g' $@
# Our markdown source files # Our markdown source files
markdown_content_files = \ markdown_content_files = \

View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="utf-8" ?> <?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<refentry id="Making-image-pyramids.md"> <refentry id="Making-image-pyramids">
<para> <para>
@ -66,7 +66,7 @@ operation flags: sequential nocache
You can also call <literal>vips_dzsave()</literal> from any language with a libvips binding, or by using <literal>.dz</literal> or <literal>.szi</literal> as an output file suffix. You can also call <literal>vips_dzsave()</literal> from any language with a libvips binding, or by using <literal>.dz</literal> or <literal>.szi</literal> as an output file suffix.
</para> </para>
<refsect3 xml:id="writing-deepzoom-pyramids"> <refsect3 xml:id="writing-deepzoom-pyramids">
<title>Writing <link xlink:href="http://en.wikipedia.org/wiki/Deep_Zoom">DeepZoom</link> pyramids</title> <title>Writing DeepZoom pyramids</title>
<para> <para>
The <literal>--layout</literal> option sets the basic mode of operation. With no <literal>--layout</literal>, dzsave writes DeepZoom pyramids. For example: The <literal>--layout</literal> option sets the basic mode of operation. With no <literal>--layout</literal>, dzsave writes DeepZoom pyramids. For example:
</para> </para>
@ -102,7 +102,7 @@ $ vips dzsave huge.tif myzoom --layout zoomify
</para> </para>
</refsect3> </refsect3>
<refsect3 xml:id="writing-google-maps-pyramids"> <refsect3 xml:id="writing-google-maps-pyramids">
<title>Writing <link xlink:href="https://developers.google.com/maps/">Google Maps</link> pyramids</title> <title>Writing Google Maps pyramids</title>
<para> <para>
Use <literal>--layout google</literal> to write Google maps-style pyramids. These are compatible with <ulink url="http://leafletjs.com">Leaflet</ulink>. For example: Use <literal>--layout google</literal> to write Google maps-style pyramids. These are compatible with <ulink url="http://leafletjs.com">Leaflet</ulink>. For example:
</para> </para>

View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="utf-8" ?> <?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<refentry id="Using-vipsthumbnail.md"> <refentry id="Using-vipsthumbnail">
<para> <para>
@ -56,7 +56,7 @@ $ cat k2.jpg | \
$ vipsthumbnail *.jpg $ vipsthumbnail *.jpg
</programlisting> </programlisting>
<para> <para>
will make a thumbnail for every jpeg in the current directory.  See the <link linkend="output-directory">Output directory</link> refsect3 below to see how to change where thumbnails are written. will make a thumbnail for every jpeg in the current directory.  See the <link linkend="output-directory">Output directory</link> section below to see how to change where thumbnails are written.
</para> </para>
<para> <para>
<literal>vipsthumbnail</literal> will process images one after the other. You can get a good speedup by running several <literal>vipsthumbnail</literal>s in parallel, depending on how much load you want to put on your system. For example: <literal>vipsthumbnail</literal> will process images one after the other. You can get a good speedup by running several <literal>vipsthumbnail</literal>s in parallel, depending on how much load you want to put on your system. For example:

View File

@ -169,7 +169,7 @@ the method-missing hook and attempt to run any method calls not implemented by
the `Image` class as libvips operators. In effect, the binding is generated at the `Image` class as libvips operators. In effect, the binding is generated at
runtime. runtime.
# Dynamic langauge without FFI # Dynamic language without FFI
PHP does not have a useful FFI, unfortunately, so for this language a small PHP does not have a useful FFI, unfortunately, so for this language a small
C module implements the general `vips_call()` function for PHP language C module implements the general `vips_call()` function for PHP language

View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="utf-8" ?> <?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<refentry id="binding.md"> <refentry id="binding">
<para> <para>
@ -173,8 +173,8 @@ VImage VImage::invert( VOption *options )
Since these languages are dynamic, they can add another trick: they intercept the method-missing hook and attempt to run any method calls not implemented by the <literal>Image</literal> class as libvips operators. In effect, the binding is generated at runtime. Since these languages are dynamic, they can add another trick: they intercept the method-missing hook and attempt to run any method calls not implemented by the <literal>Image</literal> class as libvips operators. In effect, the binding is generated at runtime.
</para> </para>
</refsect3> </refsect3>
<refsect3 xml:id="dynamic-langauge-without-ffi"> <refsect3 xml:id="dynamic-language-without-ffi">
<title>Dynamic langauge without FFI</title> <title>Dynamic language without FFI</title>
<para> <para>
PHP does not have a useful FFI, unfortunately, so for this language a small C module implements the general <literal>vips_call()</literal> function for PHP language types, and a larger pure PHP layer makes it convenient to use. PHP does not have a useful FFI, unfortunately, so for this language a small C module implements the general <literal>vips_call()</literal> function for PHP language types, and a larger pure PHP layer makes it convenient to use.
</para> </para>

View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="utf-8" ?> <?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<refentry id="libvips-from-C++.md"> <refentry id="libvips-from-C++">
<para> <para>

View File

@ -67,25 +67,45 @@ markdown_content_files = files(
'Making-image-pyramids.md', 'Making-image-pyramids.md',
) )
markdown_content_files_docbook = [] pandoc = find_program('pandoc', required: false)
foreach markdown_content_file : markdown_content_files
if pandoc.found()
# we have some files in markdown ... convert to docbook for gtk-doc # we have some files in markdown ... convert to docbook for gtk-doc
# pandoc makes section headers, we want refsect3 for gtk-doc gen = generator(pandoc,
markdown_content_files_docbook += configure_file( output: '@BASENAME@.xml',
input: markdown_content_file, arguments: [
command: [
find_program('pandoc'),
'@INPUT@', '@INPUT@',
'--template', files('pandoc-docbook-template.docbook'), '--template=@0@'.format(join_paths(meson.current_source_dir(), 'pandoc-docbook-template.docbook')),
'--wrap=none', '--wrap=none',
'-V', 'title=@BASENAME@', '-V', 'title=@BASENAME@',
'-f', 'markdown+smart', '-f', 'markdown+smart',
'-t', 'docbook', '-t', 'docbook',
'-o', '@OUTPUT@', '-o', '@OUTPUT@',
], ]
output: '@BASENAME@.xml',
) )
endforeach
markdown_content_files_generated = gen.process(markdown_content_files)
# pandoc makes section headers, we want refsect3 for gtk-doc
markdown_content_files_docbook = custom_target('gen-docs',
output: 'generated',
input: markdown_content_files_generated,
command: [ 'sed', '-i', '-e', 's|<section|<refsect3|g', '-e', 's|</section|</refsect3|g', '@INPUT@' ],
build_by_default: true
)
else
# use the pre-generated docbook files when pandoc is not available
markdown_content_files_docbook = files(
'How-it-works.xml',
'libvips-from-C++.xml',
'Using-vipsthumbnail.xml',
'How-it-opens-files.xml',
'Examples.xml',
'Cite.xml',
'binding.xml',
'Making-image-pyramids.xml',
)
endif
content_files = files( content_files = files(
'using-command-line.xml', 'using-command-line.xml',
@ -124,18 +144,18 @@ gnome.gtkdoc('libvips',
], ],
dependencies: libvips_dep, dependencies: libvips_dep,
scan_args: [ scan_args: [
'--ignore-headers=' + ' '.join(private_headers), '--ignore-headers=' + ' '.join(private_headers),
'--rebuild-types', '--rebuild-types',
], ],
mkdb_args: [ '--default-includes=vips/vips.h' ], mkdb_args: [ '--default-includes=vips/vips.h' ],
fixxref_args: [ fixxref_args: [
'--html-dir=@0@'.format(docpath), '--html-dir=@0@'.format(docpath),
'--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')), '--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')),
'--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')), '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')),
'--extra-dir=@0@'.format(join_paths(glib_docpath, 'gio')), '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gio')),
], ],
content_files: [ content_files, markdown_content_files_docbook ], content_files: [ content_files, markdown_content_files_docbook ],
expand_content_files: [ content_files, markdown_content_files_docbook ], expand_content_files: [ content_files ],
html_assets: images, html_assets: images,
install: true install: true
) )