From a43ca05578cc2fefdd1bab8cd564332eaf9bd191 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Mon, 6 Apr 2020 13:51:22 +0200 Subject: Remove most uses of "e.g." in documentation This causes typesetting issues in some cases (because it is interpreted as the end of a sentence), and it's probably more accessible to write out fully anyway. --- lv2/atom/atom.h | 6 +++--- lv2/atom/util.h | 14 ++++++++++---- lv2/core/lv2.h | 15 +++++++-------- lv2/core/lv2core.meta.ttl | 4 ++-- lv2/dynmanifest/dynmanifest.h | 8 ++++---- lv2/dynmanifest/dynmanifest.meta.ttl | 10 +++++----- lv2/event/event-helpers.h | 2 +- lv2/event/event.h | 2 +- lv2/event/event.meta.ttl | 16 ++++++++-------- lv2/morph/morph.meta.ttl | 4 ++-- lv2/parameters/parameters.meta.ttl | 4 ++-- lv2/port-groups/port-groups.meta.ttl | 4 ++-- lv2/port-props/port-props.meta.ttl | 6 +++--- lv2/state/state.h | 26 +++++++++++++------------- lv2/state/state.meta.ttl | 2 +- lv2/worker/worker.h | 8 ++++---- 16 files changed, 68 insertions(+), 63 deletions(-) diff --git a/lv2/atom/atom.h b/lv2/atom/atom.h index d2c25ff..8c0f30a 100644 --- a/lv2/atom/atom.h +++ b/lv2/atom/atom.h @@ -80,7 +80,7 @@ typedef char lv2_atom_assert_double_fits_in_64_bits[ /** Return a pointer to the contents of an Atom. The "contents" of an atom is the data past the complete type-specific header. - @param type The type of the atom, e.g. LV2_Atom_String. + @param type The type of the atom, for example LV2_Atom_String. @param atom A variable-sized atom. */ #define LV2_ATOM_CONTENTS(type, atom) \ @@ -180,7 +180,7 @@ typedef struct { LV2_Atom_Vector_Body body; /**< Body. */ } LV2_Atom_Vector; -/** The body of an atom:Property (e.g. in an atom:Object). */ +/** The body of an atom:Property (typically in an atom:Object). */ typedef struct { uint32_t key; /**< Key (predicate) (mapped URI). */ uint32_t context; /**< Context URID (may be, and generally is, 0). */ @@ -226,7 +226,7 @@ typedef struct { LV2_Descriptor::run(), the default stamp type is audio frames. The contents of a sequence is a series of LV2_Atom_Event, each aligned - to 64-bits, e.g.: + to 64-bits, for example: 
    | Event 1 (size 6)                              | Event 2
    |       |       |       |       |       |       |       |       |
diff --git a/lv2/atom/util.h b/lv2/atom/util.h
index 051a3cb..383d304 100644
--- a/lv2/atom/util.h
+++ b/lv2/atom/util.h
@@ -114,7 +114,9 @@ lv2_atom_sequence_next(const LV2_Atom_Event* i)
    @param seq  The sequence to iterate over
    @param iter The name of the iterator
 
-   This macro is used similarly to a for loop (which it expands to), e.g.:
+   This macro is used similarly to a for loop (which it expands to), for
+   example:
+
    @code
    LV2_ATOM_SEQUENCE_FOREACH(sequence, ev) {
        // Do something with ev (an LV2_Atom_Event*) here...
@@ -154,7 +156,7 @@ lv2_atom_sequence_clear(LV2_Atom_Sequence* seq)
 
    @param seq Sequence to append to.
    @param capacity Total capacity of the sequence atom
-   (e.g. as set by the host for sequence output ports).
+   (as set by the host for sequence output ports).
    @param event Event to write.
 
    @return A pointer to the newly written event in `seq`,
@@ -211,7 +213,9 @@ lv2_atom_tuple_next(const LV2_Atom* i)
    @param tuple The tuple to iterate over
    @param iter The name of the iterator
 
-   This macro is used similarly to a for loop (which it expands to), e.g.:
+   This macro is used similarly to a for loop (which it expands to), for
+   example:
+
    @code
    LV2_ATOM_TUPLE_FOREACH(tuple, elem) {
        // Do something with elem (an LV2_Atom*) here...
@@ -267,7 +271,9 @@ lv2_atom_object_next(const LV2_Atom_Property_Body* i)
    @param obj The object to iterate over
    @param iter The name of the iterator
 
-   This macro is used similarly to a for loop (which it expands to), e.g.:
+   This macro is used similarly to a for loop (which it expands to), for
+   example:
+
    @code
    LV2_ATOM_OBJECT_FOREACH(object, i) {
        // Do something with i (an LV2_Atom_Property_Body*) here...
diff --git a/lv2/core/lv2.h b/lv2/core/lv2.h
index 57032fe..9b2de6f 100644
--- a/lv2/core/lv2.h
+++ b/lv2/core/lv2.h
@@ -193,9 +193,8 @@ typedef struct LV2_Descriptor {
 	   @param sample_rate Sample rate, in Hz, for the new plugin instance.
 
 	   @param bundle_path Path to the LV2 bundle which contains this plugin
-	   binary. It MUST include the trailing directory separator (e.g. '/') so
-	   that simply appending a filename will yield the path to that file in the
-	   bundle.
+	   binary. It MUST include the trailing directory separator so that simply
+	   appending a filename will yield the path to that file in the bundle.
 
 	   @param features A NULL terminated array of LV2_Feature structs which
 	   represent the features the host supports. Plugins may refuse to
@@ -243,7 +242,7 @@ typedef struct LV2_Descriptor {
 	   it does, the plugin's behaviour is undefined (a crash is likely).
 
 	   @param data_location Pointer to data of the type defined by the port
-	   type in the plugin's RDF data (e.g. an array of float for an
+	   type in the plugin's RDF data (for example, an array of float for an
 	   lv2:AudioPort). This pointer must be stored by the plugin instance and
 	   used to read/write data when run() is called. Data present at the time
 	   of the connect_port() call MUST NOT be considered meaningful.
@@ -287,10 +286,10 @@ typedef struct LV2_Descriptor {
 	   lv2core.ttl for details).
 
 	   As a special case, when `sample_count` is 0, the plugin should update
-	   any output ports that represent a single instant in time (e.g. control
-	   ports, but not audio ports). This is particularly useful for latent
-	   plugins, which should update their latency output port so hosts can
-	   pre-roll plugins to compute latency. Plugins MUST NOT crash when
+	   any output ports that represent a single instant in time (for example,
+	   control ports, but not audio ports). This is particularly useful for
+	   latent plugins, which should update their latency output port so hosts
+	   can pre-roll plugins to compute latency. Plugins MUST NOT crash when
 	   `sample_count` is 0.
 
 	   @param instance Instance to be run.
diff --git a/lv2/core/lv2core.meta.ttl b/lv2/core/lv2core.meta.ttl
index 45e1a5a..1826a06 100644
--- a/lv2/core/lv2core.meta.ttl
+++ b/lv2/core/lv2core.meta.ttl
@@ -465,7 +465,7 @@ number with the usual semantics:
     plugin.
 
   * The micro version is incremented for changes which do not affect
-    compatibility at all, e.g. bug fixes or documentation updates.
+    compatibility at all, for example bug fixes or documentation updates.
 
 Note that there is deliberately no major version: all versions with the same
 URI are compatible by definition.  Replacing a resource with a newer version of
@@ -670,7 +670,7 @@ lv2:control
 
 This should be used as the lv2:designation of ports that are used to send
 commands and receive responses.  Typically this will be an event port that
-supports some protocol, e.g. MIDI or LV2 Atoms.
+supports some protocol, for example MIDI or LV2 Atoms.
 
 """^^lv2:Markdown .
 
diff --git a/lv2/dynmanifest/dynmanifest.h b/lv2/dynmanifest/dynmanifest.h
index 0feda89..16274e4 100644
--- a/lv2/dynmanifest/dynmanifest.h
+++ b/lv2/dynmanifest/dynmanifest.h
@@ -86,8 +86,8 @@ int lv2_dyn_manifest_open(LV2_Dyn_Manifest_Handle *  handle,
    @param fp FILE * identifying the resource the host has to set up for the
    dynamic manifest generator. The host MUST pass a writable, empty resource to
    this function, and the dynamic manifest generator MUST ONLY perform write
-   operations on it at the end of the stream (e.g., using only fprintf(),
-   fwrite() and similar).
+   operations on it at the end of the stream (for example, using only
+   fprintf(), fwrite() and similar).
 
    @return 0 on success, otherwise a non-zero error code.
 */
@@ -116,8 +116,8 @@ int lv2_dyn_manifest_get_subjects(LV2_Dyn_Manifest_Handle handle,
    @param fp FILE * identifying the resource the host has to set up for the
    dynamic manifest generator. The host MUST pass a writable resource to this
    function, and the dynamic manifest generator MUST ONLY perform write
-   operations on it at the current position of the stream (e.g. using only
-   fprintf(), fwrite() and similar).
+   operations on it at the current position of the stream (for example, using
+   only fprintf(), fwrite() and similar).
 
    @param uri URI to get data about (in the "plain" form, i.e., absolute URI
    without Turtle prefixes).
diff --git a/lv2/dynmanifest/dynmanifest.meta.ttl b/lv2/dynmanifest/dynmanifest.meta.ttl
index 7527494..4e66d98 100644
--- a/lv2/dynmanifest/dynmanifest.meta.ttl
+++ b/lv2/dynmanifest/dynmanifest.meta.ttl
@@ -58,9 +58,9 @@
 	lv2:documentation """
 
 The LV2 API, on its own, cannot be used to write plugin libraries where data is
-dynamically generated at runtime (e.g. API wrappers), since LV2 requires needed
-information to be provided in one or more static data (RDF) files. This API
-addresses this limitation by extending the LV2 API.
+dynamically generated at runtime, since LV2 requires needed information to be
+provided in one or more static data (RDF) files. This API addresses this
+limitation by extending the LV2 API.
 
 To detect that a plugin library implements a dynamic manifest generator, the
 host checks its static manifest for a description like:
@@ -70,8 +70,8 @@ host checks its static manifest for a description like:
         a dman:DynManifest ;
         lv2:binary  .
 
-To load the data, the host loads the library (e.g. `mydynmanifest.so`) as usual
-and fetches the dynamic Turtle data from it using this API.
+To load the data, the host loads the library (`mydynmanifest.so` in this
+example) as usual and fetches the dynamic Turtle data from it using this API.
 
 The host is allowed to request regeneration of the dynamic manifest multiple
 times, and the plugin library is expected to provide updated data if/when
diff --git a/lv2/event/event-helpers.h b/lv2/event/event-helpers.h
index af72d76..ca3abec 100644
--- a/lv2/event/event-helpers.h
+++ b/lv2/event/event-helpers.h
@@ -90,7 +90,7 @@ lv2_event_buffer_new(uint32_t capacity, uint16_t stamp_type)
 /** An iterator over an LV2_Event_Buffer.
  *
  * Multiple simultaneous read iterators over a single buffer is fine,
- * but changing the buffer invalidates all iterators (e.g. RW Lock). */
+ * but changing the buffer invalidates all iterators. */
 typedef struct {
 	LV2_Event_Buffer* buf;
 	uint32_t          offset;
diff --git a/lv2/event/event.h b/lv2/event/event.h
index 30d73a6..aa67390 100644
--- a/lv2/event/event.h
+++ b/lv2/event/event.h
@@ -81,7 +81,7 @@ typedef struct {
 	   The frames portion of timestamp. The units used here can optionally be
 	   set for a port (with the lv2ev:timeUnits property), otherwise this is
 	   audio frames, corresponding to the sample_count parameter of the LV2 run
-	   method (e.g. frame 0 is the first frame for that call to run).
+	   method (frame 0 is the first frame for that call to run).
 	*/
 	uint32_t frames;
 
diff --git a/lv2/event/event.meta.ttl b/lv2/event/event.meta.ttl
index 22d8f92..80593ce 100644
--- a/lv2/event/event.meta.ttl
+++ b/lv2/event/event.meta.ttl
@@ -139,8 +139,8 @@ An ev:EventPort contains an LV2_Event_Buffer which contains a sequence of these
 events.  The binary format of LV2 events is defined by the LV2_Event struct in
 event.h.
 
-Specific event types (e.g. MIDI, OSC) are defined by extensions, and should be
-rdfs:subClassOf this class.
+Specific event types (such as MIDI or OSC) are defined by extensions, and
+should be rdfs:subClassOf this class.
 
 """^^lv2:Markdown .
 
@@ -164,8 +164,8 @@ frames (in the sample rate passed to intantiate), and the subframes field is
 ev:generic
 	lv2:documentation """
 
-Indicates that this port does something meaningful for any event type
-(e.g. event mixers, delays, serialisers, etc).
+Indicates that this port does something meaningful for any event type.  This is
+useful for things like event mixers, delays, serialisers, and so on.
 
 If this property is set, hosts should consider the port suitable for any type
 of event.  Otherwise, hosts should consider the port 'appropriate' only for the
@@ -188,10 +188,10 @@ set (use ev:inheritsEvent for that).
 Plugins with event input ports must always gracefully handle any type of event,
 even if it does not 'support' it.  This property should always be set for event
 types the plugin understands/generates so hosts can discover plugins
-appropriate for a given scenario (e.g. plugins with a MIDI input). Hosts are
-not expected to consider event ports suitable for some type of event if the
-relevant :supportsEvent property is not set, unless the ev:generic property for
-that port is also set.
+appropriate for a given scenario (for example, plugins with a MIDI input).
+Hosts are not expected to consider event ports suitable for some type of event
+if the relevant :supportsEvent property is not set, unless the ev:generic
+property for that port is also set.
 
 
 """^^lv2:Markdown .
diff --git a/lv2/morph/morph.meta.ttl b/lv2/morph/morph.meta.ttl
index 0616473..c247783 100644
--- a/lv2/morph/morph.meta.ttl
+++ b/lv2/morph/morph.meta.ttl
@@ -55,8 +55,8 @@ morph:AutoMorphPort
 	lv2:documentation """
 
 Ports of this type MUST have another type which defines the default buffer
-format (e.g. lv2:ControlPort) but may dynamically change types based on the
-configured types of any morph:MorphPort ports on the same plugin instance.
+format (for example, lv2:ControlPort) but may dynamically change types based on
+the configured types of any morph:MorphPort ports on the same plugin instance.
 
 The type of a port may only change in response to a host call to
 LV2_Options_Interface::set().  Whenever any port type on the instance changes,
diff --git a/lv2/parameters/parameters.meta.ttl b/lv2/parameters/parameters.meta.ttl
index 5fcd047..9d7c623 100644
--- a/lv2/parameters/parameters.meta.ttl
+++ b/lv2/parameters/parameters.meta.ttl
@@ -52,8 +52,8 @@
 This is a vocabulary for parameters that are common in audio processing
 software.  A parameter is purely a metadata concept, unrelated to any
 particular code mechanism.  Parameters are used to assign meaning to controls
-(e.g. using lv2:designation for ports) so they can be used more intelligently
-or presented to the user more efficiently.
+(for example, using lv2:designation for ports) so they can be used more
+intelligently or presented to the user more efficiently.
 
 """^^lv2:Markdown .
 
diff --git a/lv2/port-groups/port-groups.meta.ttl b/lv2/port-groups/port-groups.meta.ttl
index b3ddaaf..210e9dd 100644
--- a/lv2/port-groups/port-groups.meta.ttl
+++ b/lv2/port-groups/port-groups.meta.ttl
@@ -79,8 +79,8 @@ pg:subGroupOf
 
 Indicates that this group is a child of another group.  This property has no
 meaning with respect to plugin execution, but the host may find this
-information useful (e.g. to provide a compact user interface).  Note that being
-a sub-group does not relax the restriction that the group MUST have a unique
+information useful to provide a better user interface.  Note that being a
+sub-group does not relax the restriction that the group MUST have a unique
 symbol with respect to the plugin.
 
 """^^lv2:Markdown .
diff --git a/lv2/port-props/port-props.meta.ttl b/lv2/port-props/port-props.meta.ttl
index ddb8605..7077e4b 100644
--- a/lv2/port-props/port-props.meta.ttl
+++ b/lv2/port-props/port-props.meta.ttl
@@ -85,8 +85,8 @@ pprops:expensive
 	lv2:documentation """
 
 Input ports only.  Indicates that any changes to the port value may trigger
-expensive background calculation (e.g. regenerate some lookup tables in a
-background thread).  Any value changes may have not have immediate effect, or
+expensive background calculation (for example, regeneration of lookup tables in
+a background thread).  Any value changes may have not have immediate effect, or
 may cause silence or diminished-quality version of the output until background
 processing is finished.  Ports having this property are typically not well
 suited for connection to outputs of other plugins, and should not be offered as
@@ -114,7 +114,7 @@ signals (knobs with smoothing, modulation rate oscillators, output ports with
 continuousCV type, etc.).  Typically, the plugin with ports which have this
 property will implement appropriate smoothing to avoid audio artifacts.  For
 output ports, this property suggests the value of the port is likely to change
-frequently, and describes a smooth signal (e.g. successive values may be
+frequently, and describes a smooth signal (so successive values may be
 considered points along a curve).
 
 """^^lv2:Markdown .
diff --git a/lv2/state/state.h b/lv2/state/state.h
index cea4037..2823989 100644
--- a/lv2/state/state.h
+++ b/lv2/state/state.h
@@ -69,8 +69,8 @@ typedef enum {
 	   Values with this flag contain no pointers or references to other areas
 	   of memory.  It is safe to copy POD values with a simple memcpy and store
 	   them for the duration of the process.  A POD value is not necessarily
-	   safe to trasmit between processes or machines (e.g. filenames are POD),
-	   see LV2_STATE_IS_PORTABLE for details.
+	   safe to trasmit between processes or machines (for example, filenames
+	   are POD), see LV2_STATE_IS_PORTABLE for details.
 
 	   Implementations MUST NOT attempt to copy or serialise a non-POD value if
 	   they do not understand its type (and thus know how to correctly do so).
@@ -92,9 +92,9 @@ typedef enum {
 	   Native data.
 
 	   This flag is used by the host to indicate that the saved data is only
-	   going to be used locally in the currently running process (e.g. for
-	   instance duplication or snapshots), so the plugin should use the most
-	   efficient representation possible and not worry about serialisation
+	   going to be used locally in the currently running process (for things
+	   like instance duplication or snapshots), so the plugin should use the
+	   most efficient representation possible and not worry about serialisation
 	   and portability.
 	*/
 	LV2_STATE_IS_NATIVE = 1 << 2
@@ -128,7 +128,7 @@ typedef enum {
    DO NOT INVENT NONSENSE URI SCHEMES FOR THE KEY.  Best is to use keys from
    existing vocabularies.  If nothing appropriate is available, use http URIs
    that point to somewhere you can host documents so documentation can be made
-   resolvable (e.g. a child of the plugin or project URI).  If this is not
+   resolvable (typically a child of the plugin or project URI).  If this is not
    possible, invent a URN scheme, e.g. urn:myproj:whatever.  The plugin MUST
    NOT pass an invalid URI key.
 
@@ -219,10 +219,10 @@ typedef struct {
 	   This function has its own special threading class: it may not be called
 	   concurrently with any "Instantiation" function, but it may be called
 	   concurrently with functions in any other class, unless the definition of
-	   that class prohibits it (e.g. it may not be called concurrently with a
-	   "Discovery" function, but it may be called concurrently with an "Audio"
-	   function.  The plugin is responsible for any locking or lock-free
-	   techniques necessary to make this possible.
+	   that class prohibits it (for example, it may not be called concurrently
+	   with a "Discovery" function, but it may be called concurrently with an
+	   "Audio" function.  The plugin is responsible for any locking or
+	   lock-free techniques necessary to make this possible.
 
 	   Note that in the simple case where state is only modified by restore(),
 	   there are no synchronization issues since save() is never called
@@ -304,7 +304,7 @@ typedef struct {
 	/**
 	   Map an abstract path from plugin state to an absolute path.
 	   @param handle MUST be the `handle` member of this struct.
-	   @param abstract_path An abstract path (e.g. a path from plugin state).
+	   @param abstract_path An abstract path (typically from plugin state).
 	   @return An absolute file system path.
 
 	   The plugin MUST use this function in order to actually open or otherwise
@@ -340,8 +340,8 @@ typedef struct {
 	   LV2_Descriptor.instantiate()).
 
 	   The host MUST do whatever is necessary for the plugin to be able to
-	   create a file at the returned path (e.g. using fopen), including
-	   creating any leading directories.
+	   create a file at the returned path (for example, using fopen()),
+	   including creating any leading directories.
 
 	   If this function is passed to LV2_Descriptor.instantiate(), it may be
 	   called from any non-realtime context.  If it is passed to
diff --git a/lv2/state/state.meta.ttl b/lv2/state/state.meta.ttl
index ac3f2d6..03a4085 100644
--- a/lv2/state/state.meta.ttl
+++ b/lv2/state/state.meta.ttl
@@ -124,7 +124,7 @@ types is recommended. Hosts MUST implement at least
 
 ### Referring to Files
 
-Plugins may need to refer to existing files (e.g. loaded samples) in their
+Plugins may need to refer to existing files (such as loaded samples) in their
 state. This is done by storing the file's path as a property just like any
 other value. However, there are some rules which MUST be followed when storing
 paths, see state:mapPath for details. Plugins MUST use the type
diff --git a/lv2/worker/worker.h b/lv2/worker/worker.h
index 35b82b5..69cc1d3 100644
--- a/lv2/worker/worker.h
+++ b/lv2/worker/worker.h
@@ -145,10 +145,10 @@ typedef struct {
 
 	   This function is always safe to call from run(), but it is not
 	   guaranteed that the worker is actually called from a different thread.
-	   In particular, when free-wheeling (e.g. for offline rendering), the
-	   worker may be executed immediately.  This allows single-threaded
-	   processing with sample accuracy and avoids timing problems when run() is
-	   executing much faster or slower than real-time.
+	   In particular, when free-wheeling (for example, during offline
+	   rendering), the worker may be executed immediately.  This allows
+	   single-threaded processing with sample accuracy and avoids timing
+	   problems when run() is executing much faster or slower than real-time.
 
 	   Plugins SHOULD be written in such a way that if the worker runs
 	   immediately, and responses from the worker are delivered immediately,
-- 
cgit v1.2.1