From fa03989b6022ce2602a8fff35bae01e9e81a1a7d Mon Sep 17 00:00:00 2001 From: Kleis Auke Wolthuizen Date: Wed, 30 Nov 2022 01:07:57 +0100 Subject: [PATCH] Minor doc improvements (#3202) * doc: avoid use of GCC's old syntax (`-Wgnu-designator`) * doc: highlight shell commands * doc: point the C++ docs to v8.12 * doc: avoid highlight on output matching bash keywords --- doc/Examples.md | 10 +++++----- doc/Examples.xml | 6 +++--- doc/How-it-opens-files.md | 4 ++-- doc/How-it-opens-files.xml | 4 ++-- doc/How-it-works.md | 2 +- doc/How-it-works.xml | 2 +- doc/Making-image-pyramids.md | 16 ++++++++-------- doc/Making-image-pyramids.xml | 16 ++++++++-------- doc/Using-vipsthumbnail.md | 30 +++++++++++++++--------------- doc/Using-vipsthumbnail.xml | 30 +++++++++++++++--------------- doc/binding.md | 6 +++--- doc/binding.xml | 6 +++--- doc/libvips-from-C++.md | 2 +- doc/libvips-from-C++.xml | 2 +- 14 files changed, 68 insertions(+), 68 deletions(-) diff --git a/doc/Examples.md b/doc/Examples.md index 026cadba..40fb46d5 100644 --- a/doc/Examples.md +++ b/doc/Examples.md @@ -17,7 +17,7 @@ in the API. It's also a useful source of examples. # Average a region of interest box on an image -``` python +```python #!/usr/bin/python3 import sys @@ -124,20 +124,20 @@ To test it, first make a large 1-bit image. This command will take the green channel and write as a 1-bit fax image. `wtc.jpg` is a test 10,000 x 10,000 jpeg: -``` +```bash $ vips extract_band wtc.jpg x.tif[squash,compression=ccittfax4,strip] 1 ``` Now make 1,000 copies of that image in a subdirectory: -``` +```bash $ mkdir test $ for i in {1..1000}; do cp x.tif test/$i.tif; done ``` And run this Python program on them: -``` +```bash $ time python try255.py x.tif[squash,compression=ccittfax4,strip,bigtiff] test/* real 1m59.924s user 4m5.388s @@ -152,7 +152,7 @@ If you wanted to handle transparency, or if you wanted mixed CMYK and RGB images, you'd need to do some more work to convert them all into the same colourspace before inserting them. -``` python +```python #!/usr/bin/python3 #file try255.py diff --git a/doc/Examples.xml b/doc/Examples.xml index 19143f17..a5f381f0 100644 --- a/doc/Examples.xml +++ b/doc/Examples.xml @@ -121,20 +121,20 @@ vi.write_to_file(sys.argv[2]) To test it, first make a large 1-bit image. This command will take the green channel and write as a 1-bit fax image. wtc.jpg is a test 10,000 x 10,000 jpeg: - + $ vips extract_band wtc.jpg x.tif[squash,compression=ccittfax4,strip] 1 Now make 1,000 copies of that image in a subdirectory: - + $ mkdir test $ for i in {1..1000}; do cp x.tif test/$i.tif; done And run this Python program on them: - + $ time python try255.py x.tif[squash,compression=ccittfax4,strip,bigtiff] test/* real 1m59.924s user 4m5.388s diff --git a/doc/How-it-opens-files.md b/doc/How-it-opens-files.md index 3b1f4b05..fb4f75bb 100644 --- a/doc/How-it-opens-files.md +++ b/doc/How-it-opens-files.md @@ -85,7 +85,7 @@ two. Imagine how this command might be executed: -``` +```bash $ vips flip fred.jpg jim.jpg vertical ``` @@ -99,7 +99,7 @@ before it can run the flip operation. However many useful operations do not require true random access.  For example: -``` +```bash $ vips shrink fred.png jim.png 10 10 ``` diff --git a/doc/How-it-opens-files.xml b/doc/How-it-opens-files.xml index a7a1bc16..e686a122 100644 --- a/doc/How-it-opens-files.xml +++ b/doc/How-it-opens-files.xml @@ -63,7 +63,7 @@ Imagine how this command might be executed: - + $ vips flip fred.jpg jim.jpg vertical @@ -75,7 +75,7 @@ $ vips flip fred.jpg jim.jpg vertical However many useful operations do not require true random access.  For example: - + $ vips shrink fred.png jim.png 10 10 diff --git a/doc/How-it-works.md b/doc/How-it-works.md index 64ee1a9c..05c18bb0 100644 --- a/doc/How-it-works.md +++ b/doc/How-it-works.md @@ -36,7 +36,7 @@ VipsImage *image = vips_image_new_from_file( filename, NULL ); VipsRegion *region = vips_region_new( image ); // ask for a 100x100 pixel region at 0x0 (top left) -VipsRect r = { left: 0, top: 0, width: 100, height: 100 }; +VipsRect r = { .left = 0, .top = 0, .width = 100, .height = 100 }; if( vips_region_prepare( region, &r ) ) vips_error( ... ); diff --git a/doc/How-it-works.xml b/doc/How-it-works.xml index 69a243d2..9e541584 100644 --- a/doc/How-it-works.xml +++ b/doc/How-it-works.xml @@ -33,7 +33,7 @@ VipsImage *image = vips_image_new_from_file( filename, NULL ); VipsRegion *region = vips_region_new( image ); // ask for a 100x100 pixel region at 0x0 (top left) -VipsRect r = { left: 0, top: 0, width: 100, height: 100 }; +VipsRect r = { .left = 0, .top = 0, .width = 100, .height = 100 }; if( vips_region_prepare( region, &r ) ) vips_error( ... ); diff --git a/doc/Making-image-pyramids.md b/doc/Making-image-pyramids.md index 5909b76b..6fcef77e 100644 --- a/doc/Making-image-pyramids.md +++ b/doc/Making-image-pyramids.md @@ -72,7 +72,7 @@ by using `.dz` or `.szi` as an output file suffix. The `--layout` option sets the basic mode of operation. With no `--layout`, dzsave writes DeepZoom pyramids. For example: -``` +```bash $ vips dzsave huge.tif mydz ``` @@ -83,7 +83,7 @@ metadata.  You can use the `--suffix` option to control how tiles are written. For example: -``` +```bash $ vips dzsave huge.tif mydz --suffix .jpg[Q=90] ``` @@ -95,7 +95,7 @@ for details. Use `--layout zoomify` to put dzsave into zoomify mode. For example: -``` +```bash $ vips dzsave huge.tif myzoom --layout zoomify ``` @@ -111,7 +111,7 @@ Use `--layout google` to write Google maps-style pyramids. These are compatible with Leaflet. For example: -``` +```bash $ vips dzsave wtc.tif gmapdir --layout google ``` @@ -132,7 +132,7 @@ centred. For example: -``` +```bash $ vips dzsave wtc.tif gmapdir --layout google --background 0 --centre ``` @@ -157,7 +157,7 @@ You can use `--container` to set the container type. Normally dzsave will write a tree of directories, but with `--container zip` you'll get a zip file instead. Use .zip as the directory suffix to turn on zip format automatically: -``` +```bash $ vips dzsave wtc.tif mypyr.zip ``` @@ -174,7 +174,7 @@ You can use `.dz` as a filename suffix, meaning send the image to `vips_dzsave()`. This means you can write the output of any vips operation to a pyramid. For example: -``` +```bash $ vips extract_area huge.svs mypy.dz[layout=google] 100 100 10000 10000 ``` @@ -186,7 +186,7 @@ build a pyramid in Google layout using just those pixels. If you are working from OpenSlide images, you can use the shrink-on-load feature of many of those formats. For example: -``` +```bash $ vips dzsave CMU-1.mrxs[level=1] x ``` diff --git a/doc/Making-image-pyramids.xml b/doc/Making-image-pyramids.xml index 6e09c6fa..5c848f16 100644 --- a/doc/Making-image-pyramids.xml +++ b/doc/Making-image-pyramids.xml @@ -70,7 +70,7 @@ operation flags: sequential nocache The --layout option sets the basic mode of operation. With no --layout, dzsave writes DeepZoom pyramids. For example: - + $ vips dzsave huge.tif mydz @@ -79,7 +79,7 @@ $ vips dzsave huge.tif mydz You can use the --suffix option to control how tiles are written. For example: - + $ vips dzsave huge.tif mydz --suffix .jpg[Q=90] @@ -91,7 +91,7 @@ $ vips dzsave huge.tif mydz --suffix .jpg[Q=90] Use --layout zoomify to put dzsave into zoomify mode. For example: - + $ vips dzsave huge.tif myzoom --layout zoomify @@ -106,7 +106,7 @@ $ vips dzsave huge.tif myzoom --layout zoomify Use --layout google to write Google maps-style pyramids. These are compatible with Leaflet. For example: - + $ vips dzsave wtc.tif gmapdir --layout google @@ -124,7 +124,7 @@ $ vips dzsave wtc.tif gmapdir --layout google For example: - + $ vips dzsave wtc.tif gmapdir --layout google --background 0 --centre @@ -142,7 +142,7 @@ $ vips dzsave wtc.tif gmapdir --layout google --background 0 --centre You can use --container to set the container type. Normally dzsave will write a tree of directories, but with --container zip you’ll get a zip file instead. Use .zip as the directory suffix to turn on zip format automatically: - + $ vips dzsave wtc.tif mypyr.zip @@ -157,7 +157,7 @@ $ vips dzsave wtc.tif mypyr.zip You can use .dz as a filename suffix, meaning send the image to vips_dzsave(). This means you can write the output of any vips operation to a pyramid. For example: - + $ vips extract_area huge.svs mypy.dz[layout=google] 100 100 10000 10000 @@ -166,7 +166,7 @@ $ vips extract_area huge.svs mypy.dz[layout=google] 100 100 10000 10000 If you are working from OpenSlide images, you can use the shrink-on-load feature of many of those formats. For example: - + $ vips dzsave CMU-1.mrxs[level=1] x diff --git a/doc/Using-vipsthumbnail.md b/doc/Using-vipsthumbnail.md index e309f06a..fc169c8f 100644 --- a/doc/Using-vipsthumbnail.md +++ b/doc/Using-vipsthumbnail.md @@ -25,7 +25,7 @@ $image->writeToFile("my-thumbnail.jpg"); You can also call `thumbnail_source` from the CLI, for example: -``` +```bash $ cat k2.jpg | \ vips thumbnail_source [descriptor=0] .jpg[Q=90] 128 | \ cat > x.jpg @@ -52,7 +52,7 @@ is running.  `vipsthumbnail` can process many images in one command. For example: -``` +```bash $ vipsthumbnail *.jpg ``` @@ -64,7 +64,7 @@ where thumbnails are written. speedup by running several `vipsthumbnail`s in parallel, depending on how much load you want to put on your system. For example: -``` +```bash $ parallel vipsthumbnail ::: *.jpg ``` @@ -73,14 +73,14 @@ $ parallel vipsthumbnail ::: *.jpg You can set the bounding box of the generated thumbnail with the `--size` option. For example: -``` +```bash $ vipsthumbnail shark.jpg --size 200x100 ``` Use a single number to set a square bounding box. You can omit either number but keep the x to mean resize just based on that axis, for example: -``` +```bash $ vipsthumbnail shark.jpg --size 200x ``` @@ -99,7 +99,7 @@ the aspect ratio. You can use the `--smartcrop` option to crop to fill the box instead. Excess pixels are trimmed away using the strategy you set. For example: -``` +```bash $ vipsthumbnail owl.jpg --smartcrop attention -s 128 ``` @@ -126,7 +126,7 @@ to the voltage that should be applied to the electron gun in a CRT display. `vipsthumbnail` has an option to perform image shrinking in linear space, that is, a colourspace where values are proportional to photon numbers. For example: -``` +```bash $ vipsthumbnail fred.jpg --linear ``` @@ -137,7 +137,7 @@ photons. This can make linear light thumbnailing of large images extremely slow. For example, for a 10,000 x 10,000 pixel JPEG I see: -``` +```bash $ time vipsthumbnail wtc.jpg real 0m0.317s user 0m0.292s @@ -154,7 +154,7 @@ You set the thumbnail write parameters with the `-o` option. This is a pattern which the input filename is pasted into to produce the output filename. For example: -``` +```bash $ vipsthumbnail fred.jpg jim.tif -o tn_%s.jpg ``` @@ -167,7 +167,7 @@ If the pattern given to `-o` is an absolute path, any path components are dropped from the input filenames. This lets you write all of your thumbnails to a specific directory, if you want. For example: -``` +```bash $ vipsthumbnail fred.jpg ../jim.tif -o /mythumbs/tn_%s.jpg ``` @@ -177,7 +177,7 @@ images are in different directories. Conversely, if `-o` is set to a relative path, any path component from the input file is prepended. For example: -``` +```bash $ vipsthumbnail fred.jpg ../jim.tif -o mythumbs/tn_%s.jpg ``` @@ -188,7 +188,7 @@ their current directory. You can use `-o` to specify the thumbnail image format too. For example:  -``` +```bash $ vipsthumbnail fred.jpg ../jim.tif -o tn_%s.png ``` @@ -197,7 +197,7 @@ Will write thumbnails in PNG format. You can give options to the image write operation as a list of comma-separated arguments in square brackets. For example: -``` +```bash $ vipsthumbnail fred.jpg ../jim.tif -o tn_%s.jpg[Q=90,optimize_coding] ``` @@ -294,7 +294,7 @@ embedded one. For example, perhaps you somehow know that a JPG is in Adobe98 space, even though it has no embedded profile. -``` +```bash $ vipsthumbnail kgdev.jpg --input-profile /my/profiles/a98.icm ``` @@ -302,7 +302,7 @@ $ vipsthumbnail kgdev.jpg --input-profile /my/profiles/a98.icm Putting all this together, I suggest this as a sensible set of options: -``` +```bash $ vipsthumbnail fred.jpg \ --size 128 \ --export-profile srgb \ diff --git a/doc/Using-vipsthumbnail.xml b/doc/Using-vipsthumbnail.xml index f71be415..bbaa04f1 100644 --- a/doc/Using-vipsthumbnail.xml +++ b/doc/Using-vipsthumbnail.xml @@ -24,7 +24,7 @@ $image->writeToFile("my-thumbnail.jpg"); You can also call thumbnail_source from the CLI, for example: - + $ cat k2.jpg | \ vips thumbnail_source [descriptor=0] .jpg[Q=90] 128 | \ cat > x.jpg @@ -52,7 +52,7 @@ $ cat k2.jpg | \ vipsthumbnail can process many images in one command. For example: - + $ vipsthumbnail *.jpg @@ -61,7 +61,7 @@ $ vipsthumbnail *.jpg vipsthumbnail will process images one after the other. You can get a good speedup by running several vipsthumbnails in parallel, depending on how much load you want to put on your system. For example: - + $ parallel vipsthumbnail ::: *.jpg @@ -70,13 +70,13 @@ $ parallel vipsthumbnail ::: *.jpg You can set the bounding box of the generated thumbnail with the --size option. For example: - + $ vipsthumbnail shark.jpg --size 200x100 Use a single number to set a square bounding box. You can omit either number but keep the x to mean resize just based on that axis, for example: - + $ vipsthumbnail shark.jpg --size 200x @@ -94,7 +94,7 @@ $ vipsthumbnail shark.jpg --size 200x vipsthumbnail normally shrinks images to fit within the box set by --size. You can use the --smartcrop option to crop to fill the box instead. Excess pixels are trimmed away using the strategy you set. For example: - + $ vipsthumbnail owl.jpg --smartcrop attention -s 128 @@ -129,7 +129,7 @@ $ vipsthumbnail owl.jpg --smartcrop attention -s 128 vipsthumbnail has an option to perform image shrinking in linear space, that is, a colourspace where values are proportional to photon numbers. For example: - + $ vipsthumbnail fred.jpg --linear @@ -138,7 +138,7 @@ $ vipsthumbnail fred.jpg --linear For example, for a 10,000 x 10,000 pixel JPEG I see: - + $ time vipsthumbnail wtc.jpg real 0m0.317s user 0m0.292s @@ -154,7 +154,7 @@ sys 0m0.016s You set the thumbnail write parameters with the -o option. This is a pattern which the input filename is pasted into to produce the output filename. For example: - + $ vipsthumbnail fred.jpg jim.tif -o tn_%s.jpg @@ -163,7 +163,7 @@ $ vipsthumbnail fred.jpg jim.tif -o tn_%s.jpg If the pattern given to -o is an absolute path, any path components are dropped from the input filenames. This lets you write all of your thumbnails to a specific directory, if you want. For example: - + $ vipsthumbnail fred.jpg ../jim.tif -o /mythumbs/tn_%s.jpg @@ -172,7 +172,7 @@ $ vipsthumbnail fred.jpg ../jim.tif -o /mythumbs/tn_%s.jpg Conversely, if -o is set to a relative path, any path component from the input file is prepended. For example: - + $ vipsthumbnail fred.jpg ../jim.tif -o mythumbs/tn_%s.jpg @@ -184,7 +184,7 @@ $ vipsthumbnail fred.jpg ../jim.tif -o mythumbs/tn_%s.jpg You can use -o to specify the thumbnail image format too. For example:  - + $ vipsthumbnail fred.jpg ../jim.tif -o tn_%s.png @@ -193,7 +193,7 @@ $ vipsthumbnail fred.jpg ../jim.tif -o tn_%s.png You can give options to the image write operation as a list of comma-separated arguments in square brackets. For example: - + $ vipsthumbnail fred.jpg ../jim.tif -o tn_%s.jpg[Q=90,optimize_coding] @@ -284,7 +284,7 @@ $ ls -l tn_shark.jpg You can also specify a fallback input profile to use if the image has no embedded one. For example, perhaps you somehow know that a JPG is in Adobe98 space, even though it has no embedded profile. - + $ vipsthumbnail kgdev.jpg --input-profile /my/profiles/a98.icm @@ -293,7 +293,7 @@ $ vipsthumbnail kgdev.jpg --input-profile /my/profiles/a98.icm Putting all this together, I suggest this as a sensible set of options: - + $ vipsthumbnail fred.jpg \ --size 128 \ --export-profile srgb \ diff --git a/doc/binding.md b/doc/binding.md index dee65318..0042b5cc 100644 --- a/doc/binding.md +++ b/doc/binding.md @@ -206,19 +206,19 @@ You can generate searchable docs from a .gir (the thing that is built from scanning libvips and which in turn turn the typelib is made from) with g-ir-doc-tool, for example: -``` +```bash $ g-ir-doc-tool --language=Python -o ~/mydocs Vips-8.0.gir ``` Then to view them, either: -``` +```bash $ yelp ~/mydocs ``` Or perhaps: -``` +```bash $ cd ~/mydocs $ yelp-build html . ``` diff --git a/doc/binding.xml b/doc/binding.xml index 097651e7..0f50df1c 100644 --- a/doc/binding.xml +++ b/doc/binding.xml @@ -202,19 +202,19 @@ from gi.repository import Vips You can generate searchable docs from a .gir (the thing that is built from scanning libvips and which in turn turn the typelib is made from) with g-ir-doc-tool, for example: - + $ g-ir-doc-tool --language=Python -o ~/mydocs Vips-8.0.gir Then to view them, either: - + $ yelp ~/mydocs Or perhaps: - + $ cd ~/mydocs $ yelp-build html . diff --git a/doc/libvips-from-C++.md b/doc/libvips-from-C++.md index bf20d7c8..29abe8cc 100644 --- a/doc/libvips-from-C++.md +++ b/doc/libvips-from-C++.md @@ -14,6 +14,6 @@ C API and adds automatic reference counting, exceptions, operator overloads, and automatic constant expansion. See the - + C++ API documentation for more details. diff --git a/doc/libvips-from-C++.xml b/doc/libvips-from-C++.xml index 381d1bf7..ba6995af 100644 --- a/doc/libvips-from-C++.xml +++ b/doc/libvips-from-C++.xml @@ -14,7 +14,7 @@ libvips comes with a convenient C++ API. It is a very thin wrapper over the C API and adds automatic reference counting, exceptions, operator overloads, and automatic constant expansion. - See the C++ API documentation for more details. + See the C++ API documentation for more details.