[librsvg: 2/7] Make rsvg-convert.rst markup closer to RST conventions

From: Marge Bot <marge-bot src gnome org>
To: commits-list gnome org
Cc:
Subject: [librsvg: 2/7] Make rsvg-convert.rst markup closer to RST conventions
Date: Tue, 4 Jan 2022 23:20:47 +0000 (UTC)

commit 192aced5440416a2ad0354a678775c0da512386c
Author: Federico Mena Quintero <federico gnome org>
Date:   Tue Jan 4 13:26:14 2022 -0600

    Make rsvg-convert.rst markup closer to RST conventions
    
    By convention, man pages in troff format use boldface (.B) to indicate
    literal text, but RST uses double backticks.  So, distinguish between
    things that are meant to be boldface from those that are quoted
    literally.
    
    Also, include some links and clarifications.
    
    Part-of: <https://gitlab.gnome.org/GNOME/librsvg/-/merge_requests/648>

 rsvg-convert.rst | 230 ++++++++++++++++++++++++++++++-------------------------
 1 file changed, 126 insertions(+), 104 deletions(-)
---
diff --git a/rsvg-convert.rst b/rsvg-convert.rst
index 1921599b5..6b4ca7065 100644
--- a/rsvg-convert.rst
+++ b/rsvg-convert.rst
@@ -21,7 +21,8 @@ argument:
 
    **rsvg-convert** **--output=**\ *output.png* *input.svg*
 
-Configure dots-per-inch (DPI), default is 96:
+Configure dots-per-inch (DPI) for SVGs that have physical units, as in
+``<svg width="5cm" height="3cm">`` - the default is 96 DPI:
 
    **rsvg-convert** **--dpi-x=**\ *300* **--dpi-y=**\ *300* *input.svg*
    **>** *output.png*
@@ -34,35 +35,36 @@ Render an SVG at a specific pixel size, scaled proportionally:
 DESCRIPTION
 ===========
 
-**rsvg-convert** renders SVG documents into PNG raster images, or
+``rsvg-convert`` renders SVG documents into PNG raster images, or
 converts them to PDF or PS as vector objects. By default
-**rsvg-convert** will render an SVG document to a raster PNG image and
+``rsvg-convert`` will render an SVG document to a raster PNG image and
 write it to standard output:
 
    **rsvg-convert** *input.svg* **>** *output.png*
 
-To select another format, use the **--format** option:
+To select another format, use the ``--format`` option:
 
    **rsvg-convert --format=pdf** *input.svg* **>** *output.pdf*
 
-You can use **rsvg-convert** as part of a pipeline; without an argument
+You can use ``rsvg-convert`` as part of a pipeline; without an argument
 for the input filename it will read the document from standard input:
 
    **cat** *input.svg* **\|** **rsvg-convert** **>** *output.png*
 
+
 SPECIFYING THE RENDERED SIZE
 ----------------------------
 
-You can use the **--width** and **--height** options to specify the size
+You can use the ``--width`` and ``--height`` options to specify the size
 of the output image. Most of the time you should specify
-**--keep-aspect-ratio** to scale the image proportionally; for
+``--keep-aspect-ratio`` to scale the image proportionally; for
 compatibility with old versions this is not the default.
 
    **rsvg-convert** **--width=**\ *100* **--height=**\ *200*
    **--keep-aspect-ratio** *input.svg* **>** *output.png*
 
-You can also specify dimensions as CSS lengths, for example **10px** or
-**8.5in**. The unit specifiers supported are as follows:
+You can also specify dimensions as CSS lengths, for example ``10px`` or
+``8.5in``. The unit specifiers supported are as follows:
 
    == ==========================================
    px pixels (the unit specifier can be omitted)
@@ -87,15 +89,20 @@ PDF:
    **--height=**\ *297mm* **--keep-aspect-ratio** *input.svg* **>**
    *output.pdf*
 
+
 SPECIFYING A PAGE SIZE
 ----------------------
 
 By default the size of the output comes from the rendered size, which
-can be specified with the **--width** and **--height** options, but you
+can be specified with the ``--width`` and ``--height`` options, but you
 can specify a page size independently of the rendered size with
-**--page-width** and **--page-height**, together with **--top** and
-**--left** to control the position of the rendered image within the
-page.
+``--page-width`` and ``--page-height``, together with ``--top`` and
+``--left`` to control the position of the rendered image within the
+page.  In short:
+
+* ``--page-width`` and ``--page-height`` together - set the page size.
+* ``--top`` and ``--left`` - set the margins.
+* ``--width`` and ``--height`` - set the rendered size.
 
 This will create a PDF with a landscape A4 page, by scaling an SVG
 document to 10*10 cm, and placing it with its top-left corner 5 cm away
@@ -106,26 +113,28 @@ from the top and 8 cm from the left of the page:
    **--height=**\ *10cm* **--keep-aspect-ratio** **--top=**\ *5cm*
    **--left=**\ *8cm* *input.svg* **>** *output.pdf*
 
+
 SPECIFYING A SCALE FACTOR INSTEAD OF A RENDERED SIZE
 ----------------------------------------------------
 
-The **--zoom** option lets you scale the natural size of an SVG
+The ``--zoom`` option lets you scale the natural size of an SVG
 document. For example, if *input.svg* is a document with a declared size
 of 100*200 pixels, then the following command will render it at 250*500
 pixels (zoom 2.5):
 
    **rsvg-convert** **--zoom=2.5** *input.svg* **>** *output.png*
 
-You can limit the maximum scaled size by specifying the **--width** and
-**--height** options together with **--zoom.** Here, the image will be
+You can limit the maximum scaled size by specifying the ``--width`` and
+``--height`` options together with ``--zoom``.  Here, the image will be
 scaled 10x, but limited to 1000*1000 pixels at the most:
 
    **rsvg-convert** **--zoom=10** **--width=1000** **--height=1000**
    *input.svg* **>** *output.png*
 
 If you need different scale factors for the horizontal and vertical
-dimensions, use the **--x-zoom** and **--y-zoom** options instead of
-**--zoom.**
+dimensions, use the ``--x-zoom`` and ``--y-zoom`` options instead of
+``--zoom``.
+
 
 CREATING A MULTI-PAGE DOCUMENT
 ------------------------------
@@ -134,7 +143,7 @@ The "pdf", "ps", and "eps" output formats support multiple pages. These
 can be created by combining multiple input SVG files. For example, this
 PDF file will have three pages:
 
-   **rsvg-convert** **--format=**\ *pdf* *pg1.svg* *pg2.svg* *pg3.svg*
+   **rsvg-convert** **--format=**\ *pdf* *page1.svg* *page2.svg* *page3.svg*
    **>** *out.pdf*
 
 The size of each page will be computed, separately, as described in the
@@ -143,19 +152,21 @@ with differently-sized pages. If you need to produce a PDF with all
 pages set to exactly the same size, use the **--page-width** and
 **--page-height** options.
 
-For example, the following command creates a three-page PDF out of three
-SVG documents. All the pages are portrait US Letter, and each SVG is
-scaled to fit so that there is a 1in margin around each page:
+For example, the following command creates a three-page PDF out of
+three SVG documents. All the pages are portrait US Letter, and each
+SVG is scaled to fit so that there is a 1in margin around each page
+(hence the width of 6.5in and height of 9in for the rendered size).
 
    **rsvg-convert** **--format=**\ *pdf* **--page-width=**\ *8.5in*
    **--page-height=**\ *11in* **--width=**\ *6.5in* **--height=**\ *9in*
    **--keep-aspect-ratio** **--top=**\ *1in* **--left=**\ *1in*
    *pg1.svg* *pg2.svg* *pg3.svg* **>** *out.pdf*
 
+
 CONVERSION OF PIXELS BASED ON THE DOTS-PER-INCH
 -----------------------------------------------
 
-**rsvg-convert** uses the **--dpi-x** and **--dpi-y** options to
+**rsvg-convert** uses the ``--dpi-x`` and ``--dpi-y`` options to
 configure the dots-per-inch (DPI) by which pixels will be converted
 to/from physical units like inches or centimeters. The default for both
 options is 96 DPI.
@@ -202,52 +213,54 @@ inch at 300 DPI:
    **--dpi-x=**\ *300* **--dpi-y=**\ *300* *input.svg* **>**
    *output.png* #### outputs 300x300 pixel PNG
 
+
 DEFAULT OUTPUT SIZE
 -------------------
 
-If you do not specify **--width** or **--height** options for the output
+If you do not specify ``--width`` or ``--height`` options for the output
 size, **rsvg-convert** will figure out a "natural size" for the SVG as
 follows:
 
--  **SVG with width and height in pixel units (px):** **<svg
-   width="96px" height="192px">** For PNG output, those same dimensions
+-  **SVG with width and height in pixel units (px):** ``<svg
+   width="96px" height="192px">`` For PNG output, those same dimensions
    in pixels are used. For PDF/PS/EPS, that pixel size is converted to
-   physical units based on the DPI value (see the **--dpi-x** and
-   **--dpi-y** options),
+   physical units based on the DPI value (see the ``--dpi-x`` and
+   ``--dpi-y`` options),
 
--  **SVG with width and height in physical units:** **<svg width="1in"
-   height="2in">** For PNG output, the **width** and **height**
+-  **SVG with width and height in physical units:** ``<svg width="1in"
+   height="2in">`` For PNG output, the ``width`` and ``height``
    attributes get converted to pixels, based on the DPI value (see the
-   **--dpi-x** and **--dpi-y** options). For PDF/PS/EPS output, the
+   ``--dpi-x`` and ``--dpi-y`` options). For PDF/PS/EPS output, the
    width/height in physical units define the size of the PDF unless you
    specify options for the page size; see **SPECIFYING A PAGE SIZE**
    above.
 
--  **SVG with viewBox only:** **<svg viewBox="0 0 20 30">** The size of
-   the **viewBox** attribute gets used for the pixel size of the image
+-  **SVG with viewBox only:** ``<svg viewBox="0 0 20 30">`` The size of
+   the ``viewBox`` attribute gets used for the pixel size of the image
    as in the first case above.
 
--  **SVG with width and height in percentages:** **<svg width="100%"
-   height="100%" viewBox="0 0 20 30">** Percentages are meaningless
-   unless you specify a viewport size with the **--width** and
-   **--height** options. In their absence, **rsvg-convert** will just
-   use the size of the **viewBox** for the pixel size, as described
+-  **SVG with width and height in percentages:** ``<svg width="100%"
+   height="100%" viewBox="0 0 20 30">`` Percentages are meaningless
+   unless you specify a viewport size with the ``--width`` and
+   ``--height`` options. In their absence, **rsvg-convert** will just
+   use the size of the ``viewBox`` for the pixel size, as described
    above.
 
 -  **SVG with no width, height, or viewBox:** **rsvg-convert** will
    measure the extents of all graphical objects in the SVG document and
    render them at 1:1 scale (1 pixel for each CSS px unit). It is
    strongly recommended that you give SVG documents an explicit size
-   with the **width, height,** or **viewBox** attributes.
+   with the ``width``, ``height``, or ``viewBox`` attributes.
+
 
 BACKGROUND COLOR
 ----------------
 
-You can use the **--background-color** option ( **-b** for short) to
-specify the backgroung color that will appear in parts of the image that
+You can use the ``--background-color`` option (``-b`` for short) to
+specify the background color that will appear in parts of the image that
 would otherwise be transparent. This option accepts the same syntax as
-the CSS **color** property, so you can use **#rrggbb** syntax or CSS
-named colors like **white**.
+the CSS ``color`` property, so you can use ``#rrggbb`` syntax, or CSS
+named colors like ``white``, or ``rgba()``.
 
    **rsvg-convert** **--background-color=**\ *white* *input.svg* **>**
    *output.png* #### opaque white
@@ -258,11 +271,12 @@ named colors like **white**.
    #### translucent red - use shell quotes so the # is not interpreted
    as a comment
 
+
 SELECTING A LANGUAGE FOR MULTI-LANGUAGE SVG
 -------------------------------------------
 
-An SVG document can use the **<switch>** element and children with the
-**systemLanguage** attribute to provide different content depending on
+An SVG document can use the ``<switch>`` element and children with the
+``systemLanguage`` attribute to provide different content depending on
 the user's language. For example:
 
 ::
@@ -279,7 +293,7 @@ the user's language. For example:
      </g>
    </svg>
 
-You can use the **--accept-language** option to select which language to
+You can use the ``--accept-language`` option to select which language to
 use when rendering. This option accepts strings formatted like an HTTP
 Accept-Language header, which is a comma-separated list of BCP47
 language tags: https://www.rfc-editor.org/info/bcp47
@@ -287,15 +301,16 @@ language tags: https://www.rfc-editor.org/info/bcp47
    **rsvg-convert** **--accept-language=**\ *es-MX* *input.svg* **>**
    *output.png* #### selects Mexican Spanish; renders "Español".
 
+
 USER STYLESHEET
 ---------------
 
 You can include an extra CSS stylesheet to be used when rendering an SVG
-document with the **--stylesheet** option. The stylesheet will have the
+document with the ``--stylesheet`` option. The stylesheet will have the
 CSS user origin, while styles declared in the SVG document will have the
 CSS author origin. This means your extra stylesheet's styles will
 override or augment the ones in the document, unless the document has
-**!important** in its styles.
+``!important`` in its styles.
 
    **rsvg-convert** **--stylesheet=**\ *extra-styles.css* *input.svg*
    **>** *output.png*
@@ -323,91 +338,100 @@ And this is *extra-styles.css*:
 Then the PNG created by the command above will have these elements:
 
 -  A blue square instead of a red one, because of the selector for the
-   the **recolorable** class.
+   the ``recolorable`` class.
 
--  Text in green, since a fill with **currentColor** gets substituted to
-   the value of the **color** property, and the **\*** selector applies
+-  Text in green, since a fill with ``currentColor`` gets substituted to
+   the value of the ``color`` property, and the ``*`` selector applies
    to all elements.
 
+
 OPTIONS
 =======
 
 GENERAL OPTIONS
 ---------------
 
-*-f --format [png, pdf, ps, eps, svg]*
-   Output format for the rendered document. Default is png.
+``-f`` *format*, ``--format=[png, pdf, ps, eps, svg]``
+   Output format for the rendered document. Default is ``png``.
 
-*-o --output filename*
+``-o`` *filename*, ``--output`` *filename*
    Specify the output filename. If unspecified, outputs to standard
    output.
 
-*-v --version*
+``-v, ``--version``
    Display what version of rsvg-convert you are running.
 
-*--help*
+``--help``
    Display a summary of usage and options.
 
+
 SIZE AND POSITION
 -----------------
 
-*--page-width length --page-height length*
-   Page size of the output document; both options must be used together.
-   The default is to use the image's width and height as modified by the
-   options below.
+In the following, *<length>* values must be specified with CSS <length>
+syntax: https://developer.mozilla.org/en-US/docs/Web/CSS/length.
+For example, ``640px`` or ``25cm``.
+
+``--page-width`` *<length>* ``--page-height`` *<length>*
+   Page size of the output document; both options must be used
+   together.  The default is to use the image's width and height as
+   modified by the options below.
 
-*--top length*
+``--top`` *<length>*
    Distance between top edge of the page and the rendered image. Default
    is 0.
 
-*--left length*
+``--left`` *<length>*
    Distance between left edge of the page and the rendered image.
    Default is 0.
 
-*-w --width length*
+``-w`` *<length>*, ``--width`` *<length>*
    Width of the rendered image. If unspecified, the natural width of the
    image is used as the default. See the section "SPECIFYING DIMENSIONS"
    above for details.
 
-*-h --height integer*
+``-h`` *<length>*, ``--height`` *<length>*
    Height of the rendered image. If unspecified, the natural height of
    the image is used as the default. See the section "SPECIFYING
    DIMENSIONS" above for details.
 
-*-a --keep-aspect-ratio*
+``-a``, ``--keep-aspect-ratio``
    Specify that the aspect ratio is to be preserved, i.e. the image is
    scaled proportionally to fit in the **--width** and **--height**. If
    not specified, aspect ratio will not be preserved.
 
-*-d --dpi-x number*
+``-d`` *number*, ``--dpi-x`` *number*
    Set the X resolution of the image in pixels per inch. Default is 96
    DPI.
 
-*-p --dpi-y number*
+``-p`` *number*, ``--dpi-y`` *number*
    Set the Y resolution of the image in pixels per inch. Default is 96
    DPI.
 
-*-x --x-zoom number*
+``-x`` *number*, ``--x-zoom`` *number*
    Horizontal scaling factor. Default is 1.0.
 
-*-y --y-zoom number*
+``-y`` *number*, ``--y-zoom`` *number*
    Vertical factor factor. Default is 1.0.
 
-*-z --zoom number*
+``-z`` *number*, ``--zoom`` *number*
    Horizontal and vertical scaling factor. Default is 1.0.
 
+
 CONTROLLING THE RENDERED APPEARANCE
 -----------------------------------
 
-*-b --background-color [black, white, #abccee, #aaa...]*
-   Specify the background color. If unspecified, none is used as the
-   default; this will create transparent PNGs, or PDF/PS/EPS without a
-   special background.
+``-b`` *<color>*, ``--background-color`` *[black, white, #abccee, #aaa...]*
+   Specify the background color. If unspecified, ``none`` is used as
+   the default; this will create transparent PNGs, or PDF/PS/EPS
+   without a special background.  The *<color>* must be specified in
+   CSS <color> syntax: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value.
+   For example, ``black``, ``#ff0000``, ``rgba(0.0, 1.0, 0.0, 1.0)``.
 
-*-s --stylesheet filename.css*
+``-s`` *filename.css*, ``--stylesheet`` *filename.css*
    Filename of a custom CSS stylesheet.
 
-*-l --accept-language [es-MX,fr,en]*
+``-l`` *language-tag*, ``--accept-language`` *[es-MX,fr,en]*
    Specify which languages will be used for SVG documents with multiple
    languages. The string is formatted like an HTTP Accept-Language
    header, which is a comma-separated list of BCP47 language tags:
@@ -415,40 +439,44 @@ CONTROLLING THE RENDERED APPEARANCE
    language specified by environment variables; see the section
    "ENVIRONMENT VARIABLES" below.
 
+
 OPTIONS SPECIFIC TO PDF/PS/EPS OUTPUT
 -------------------------------------
 
-*--keep-image-data*
-   Include the original, compressed images in the final output, rather
-   than uncompressed RGB data. This is the default behavior for PDF and
+``--keep-image-data``
+   For SVG documents that reference PNG or JPEG images, include the
+   original, compressed images in the final output, rather than
+   uncompressed RGB data. This is the default behavior for PDF and
    (E)PS output.
 
-*--no-keep-image-data*
+``--no-keep-image-data``
    Do not include the original, compressed images but instead embed
    uncompressed RGB date in PDF or (E)PS output. This will most likely
    result in larger documents that are slower to read.
 
+
 MISCELLANEOUS
 -------------
 
-*-i --export-id object-id*
+``-i`` *object-id*, ``--export-id`` *object-id*
    Allows to specify an SVG object that should be exported based on its
-   XML id. If not specified, all objects will be exported.
+   XML ``id`` attribute. If not specified, all objects will be exported.
 
-*-u --unlimited*
+``-u``, ``--unlimited``
    The XML parser has some guards designed to mitigate large CPU or
    memory consumption in the face of malicious documents. It may also
-   refuse to resolve data: URIs used to embed image data. If you are
-   running into such issues when converting a SVG, this option allows to
-   turn off these guards.
+   refuse to resolve ``data:`` URIs used to embed image data in SVG
+   documents. If you are running into such issues when converting a
+   SVG, this option allows to turn off these guards.
 
-*--testing*
+``--testing``
    For developers only: render images for librsvg's test suite.
 
+
 ENVIRONMENT VARIABLES
 =====================
 
-*SOURCE_DATE_EPOCH*
+``SOURCE_DATE_EPOCH``
    If the selected output format is PDF, this variable can be used to
    control the CreationDate in the PDF file. This is useful for
    reproducible output. The environment variable must be set to a
@@ -457,28 +485,22 @@ ENVIRONMENT VARIABLES
    UTC. The specification for this can be found at
    https://reproducible-builds.org/specs/source-date-epoch/
 
-*System language*
-   Unless the **--accept-language** option is specified, the default is
+**System language**
+   Unless the ``--accept-language`` option is specified, the default is
    to use the system's environment to detect the user's preferred
-   language. This consults the environment variables *LANGUAGE*,
-   *LC_ALL*, *LC_MESSAGES*, and *LANG*.
+   language. This consults the environment variables ``LANGUAGE``,
+   ``LC_ALL``, ``LC_MESSAGES``, and ``LANG``.
+
 
 MORE INFORMATION
 ================
 
-https://gitlab.gnome.org/GNOME/librsvg
-
-https://wiki.gnome.org/Projects/LibRsvg
+Librsvg source repository and bug tracker: https://gitlab.gnome.org/GNOME/librsvg
 
-http://www.w3.org/TR/SVG11/
+Wiki project page: https://wiki.gnome.org/Projects/LibRsvg
 
-http://www.w3.org/TR/SVG2
+SVG1.1 specification: http://www.w3.org/TR/SVG11/
 
-http://www.gnome.org/
-
-AUTHORS
-=======
+SVG2 specification: http://www.w3.org/TR/SVG2
 
-Dom Lachowicz (cinamod hotmail com), Caleb Moore
-(c moore student unsw edu au), Federico Mena-Quintero
-(federico gnome org), and a host of others.
+GNOME project page: http://www.gnome.org/
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]