From b4cd38dc40d2a19e2a4b8d7e8cf796b744058fb8 Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Wed, 8 Mar 2023 16:39:43 -0600 Subject: Fix documentation links now that the crate is called 'rsvg' Part-of: --- Cargo.toml | 2 +- NEWS | 3 ++ README.md | 2 +- devel-docs/api_observability.rst | 2 +- devel-docs/architecture.rst | 88 ++++++++++++++++++++-------------------- devel-docs/ci.rst | 4 +- devel-docs/contributing.rst | 2 +- devel-docs/index.rst | 2 +- devel-docs/product.rst | 2 +- devel-docs/text_layout.rst | 8 ++-- 10 files changed, 59 insertions(+), 56 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 7bd54e69..cc001607 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,7 +4,7 @@ version = "2.55.92" authors = ["Federico Mena Quintero ", "Many others"] description = "Render SVG documents with Cairo" license = "LGPL-2.1-or-later" -documentation = "https://gnome.pages.gitlab.gnome.org/librsvg/doc/librsvg/index.html" +documentation = "https://gnome.pages.gitlab.gnome.org/librsvg/doc/rsvg/index.html" homepage = "https://wiki.gnome.org/Projects/LibRsvg" repository = "https://gitlab.gnome.org/GNOME/librsvg/" build = "build.rs" diff --git a/NEWS b/NEWS index 92f294ea..b12312e7 100644 --- a/NEWS +++ b/NEWS @@ -18,6 +18,9 @@ Version 2.55.92 - The Rust crate is now called "rsvg", for consistency with other crates that don't usually have a "lib" prefix. +- The Rust API documentation is now available at + https://gnome.pages.gitlab.gnome.org/librsvg/doc/rsvg/index.html + Version 2.55.91 =============== diff --git a/README.md b/README.md index 2ccb5845..b01d2e7c 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,7 @@ considerations for librsvg's dependencies, see the [Security chapter][security] in the development guide. [c-docs]: https://gnome.pages.gitlab.gnome.org/librsvg/Rsvg-2.0/index.html -[rust-docs]: https://gnome.pages.gitlab.gnome.org/librsvg/doc/librsvg/index.html +[rust-docs]: https://gnome.pages.gitlab.gnome.org/librsvg/doc/rsvg/index.html # Contributing to librsvg's development diff --git a/devel-docs/api_observability.rst b/devel-docs/api_observability.rst index e4dcbd49..c1837161 100644 --- a/devel-docs/api_observability.rst +++ b/devel-docs/api_observability.rst @@ -166,7 +166,7 @@ Implementation -------------- There is currently the start of a `Session -`_ +`_ type woven throughout the source code, with the idea of it being the thing that records logging events, it may be better to plug into the ``tracing`` ecosystem: diff --git a/devel-docs/architecture.rst b/devel-docs/architecture.rst index a73a65f4..579c9ed7 100644 --- a/devel-docs/architecture.rst +++ b/devel-docs/architecture.rst @@ -8,7 +8,7 @@ corner. The library’s internals are documented as Rust documentation comments; you can look at the rendered version at -https://gnome.pages.gitlab.gnome.org/librsvg/internals/librsvg/index.html +https://gnome.pages.gitlab.gnome.org/librsvg/internals/rsvg/index.html You may also want to see the section below on `interesting parts of the code <#some-interesting-parts-of-the-code>`__. @@ -36,7 +36,7 @@ cross-element references like in SVG filters. Librsvg started as a C library with an ad-hoc API. At some point it got turned into a GObject library, so that the main `RsvgHandle -`_ +`_ class defines most of the entry points into the library. Through `GObject Introspection `__, this allows librsvg to be used from other programming languages. @@ -119,44 +119,44 @@ Loading an SVG document ~~~~~~~~~~~~~~~~~~~~~~~ The Rust API starts by constructing an `SvgHandle -`_ +`_ from a `Loader -`_; +`_; both of those are public types. Internally the ``SvgHandle`` is just a wrapper around a `Handle -`_, +`_, which is a private type. ``Handle`` represents an SVG document loaded in memory; it acts as a wrapper around a `Document -`_, +`_, and provides the basic primitive operations like “render the whole document” or “compute the geometry of an element” that are needed to implement the public APIs. A ``Document`` gets created by loading XML from a stream, into a tree of `Node -`_ +`_ structures. This is similar to a web browser’s DOM tree. Each XML element causes a new ``Node`` to get created with an `Element -`_ +`_ in it. The ``Element`` enum can represent all the SVG element types; for example, a ```` element from XML gets turned into a ``Node::Element(Element::Path)``. When an ``Element`` is created from its corresponding XML, its `Attributes -`_ +`_ get parsed. On one hand, attributes that are specific to a particular element type, like the ``d`` in ```` get parsed by the `set_attributes -`_ +`_ method of each particular element type (in that case, `Path::set_attributes -`_). +`_). On the other hand, attributes that refer to styles, and which may appear for any kind of element, get all parsed into a `SpecifiedValues -`_ +`_ struct. This is a memory-efficient representation of the CSS style properties that an element has. @@ -170,7 +170,7 @@ The CSS cascade ~~~~~~~~~~~~~~~ Each ``Element`` has a `SpecifiedValues -`_, +`_, which has the CSS style properties that the XML specified for that element. However, ``SpecifiedValues`` is sparse, as not all the possible style properties may have been filled in. Cascading means @@ -194,12 +194,12 @@ and are thus not copied to child elements. In librsvg, the individual types for CSS properties are defined with the `make_property -`_ +`_ macro. The cascading step takes each element’s ``SpecifiedValues`` and composes it by CSS inheritance onto a `ComputedValues -`_, +`_, which has the result of the cascade for each element's properties. When cascading is done, each ``Element`` has a fully resolved @@ -213,27 +213,27 @@ Librsvg uses an XML parser (`libxml2 `_ at the time of this writing) to do the first-stage parsing of the SVG document. `XmlState -`_ +`_ contains the XML parsing state, which is a stack of contexts depending on the XML nesting structure. ``XmlState`` has public methods, called from the XML parser as it goes. The most important one is `start_element -`_; +`_; this is responsible for creating new ``Node`` structures in the tree, within the `DocumentBuilder -`_ +`_ being built. Nodes are either SVG elements (the `Element -`_ +`_ enum), or text data inside elements (the `Chars -`_ +`_ struct); this last one will not concern us here, and we will only talk about ``Element``. Each supported kind of ``Element`` parses its attributes in a `set_attributes -`_ +`_ method. Each attribute is just a key/value pair; for example, the ```` element has a ``width`` attribute whose value is ``5px``. @@ -267,12 +267,12 @@ trait. Its `parse_value method takes the name of a CSS property name like ``fill``, plus a value like ``rgb(255, 0, 0)``, and it must return a value that represents a parsed declaration. Librsvg uses the `Declaration -`_ +`_ struct for this. The core of parsing CSS is the ``parse_value`` function, which returns a `ParsedProperty -`_: +`_: .. code:: rust @@ -284,7 +284,7 @@ a `ParsedProperty } What is `SpecifiedValue -`_? +`_? It is the parsed value for a CSS property directly as it comes out of the SVG document: @@ -314,9 +314,9 @@ Let’s break this down: property declarations can have. - ``Opacity(UnitInterval(0.5))`` - This is the type `Opacity - `_ + `_ property, which is a newtype around an internal `UnitInterval - `_ + `_ type, which in turn guarantees that we have a float in the range ``[0.0, 1.0]``. @@ -325,7 +325,7 @@ of these types are newtypes around primitive types like ``f64``. Eventually an entire CSS stylesheet, like the contents of a ``