From f69f4e9736b90f451e7de13af3a67390405cb46a Mon Sep 17 00:00:00 2001 From: Nils <> Date: Wed, 8 Jul 2020 20:31:19 +0200 Subject: [PATCH] API fix typos, grammar. Thanks to Ben Trolley for proof-reading --- docs/api/index.html | 55 +++++++++++++++++++++++++++-------------- docs/src/api/index.adoc | 20 +++++++-------- 2 files changed, 46 insertions(+), 29 deletions(-) diff --git a/docs/api/index.html b/docs/api/index.html index 23b65da..15b3bdb 100644 --- a/docs/api/index.html +++ b/docs/api/index.html @@ -532,7 +532,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
Important
-"New Session Manager" is community version of the +"New Session Manager" is a community version of the "Non Session Manager" by Jonathan Moore Liles, who also wrote the majority of this API document, especially the API itself. The API is the same. Any technical changes or differences in behaviour are described in API Versions and Behaviour Changes. @@ -567,9 +567,11 @@ guidelines, which can easily be implemented by various applications.

This project contains a program called nsmd which is an implementation of the server side of -the NSM API. nsmd can be controlled by direct OSC messages, or (more commone) a GUI: +the NSM API. nsmd can be controlled by direct OSC messages, or (more commonly) a GUI: Included in this package is the nsm-legacy-gui, which gets symlinked to "non-session-manager`. -Another GUI is "Argodejo".

+Another GUI is "Argodejo". Other applications exist that (partially) support the NSM API and are able +to load clients, but they do not use the New-Session-Manager (or Non-Session-Manager) implementation +and are therefore out of scope for this document.

However, the same server-side API can also be implemented by other programs (such as Carla), @@ -623,7 +625,7 @@ It MUST NOT allow the user to create a new project/file in another location.

This option MUST be disabled.

-

The application MAY elect to implement an option called 'Import into Session', creates a +

The application MAY elect to implement an option called "Import into Session", which creates a copy of a file/project which is then saved at the session path provided by NSM.

@@ -660,7 +662,7 @@ management.

This option MAY behave as normal (possibly asking the user to confirm exiting), or MAY do nothing to only allow quit from the session-manager control. -When the client supports :optional-gui: this option SHOULD be replaced with hiding the clients GUI +When the client supports :optional-gui: this option SHOULD be replaced with hiding the client’s GUI so a quit by window manager hides.

@@ -684,7 +686,7 @@ SHOULD be referenced by creating a symbolic link within the assigned session are referring to the symlink. This allows sessions to be archived and transported simply (e.g. with "tar -h") by tools that have no knowledge of the project formats of the various clients in the session. The symlinks thus created should, at the very least, be named after the files they refer -to (some unique component may be required to prevent collisions)

+to. Some unique component may be required to prevent collisions.

@@ -731,7 +733,7 @@ the name that would normally be passed to jack_client_open. For exa receiving an open message; the open message will provide a unique client name prefix suitable for passing to JACK. This is probably the most complex requirement of the NSM API, but it isn’t difficult to implement, especially if the application simply wishes to delay its initialization -process breifly while awaiting the announce reply and subsequent open message.

+process briefly while awaiting the announce reply and subsequent open message.

capabilities MUST be a string containing a colon separated list of the special capabilities the @@ -929,10 +931,14 @@ name.ID can be used to look up all its files. (For example to clean up the sessi

+

If a project exists at the path, the client MUST immediately open it.

@@ -1161,7 +1171,7 @@ separate program, it should be killed.

-

No response is message is required.

+

This message does not require a response.

@@ -1171,7 +1181,7 @@ separate program, it should be killed.

2.4.1. Optional GUI

If the client has specified the optional-gui capability, then it MUST send this message whenever -the state of visibility of the optional GUI has changed. It also MUST send this message after it’s +the state of visibility of the optional GUI has changed. It also MUST send this message after its announce message to indicate the initial visibility state of the optional GUI.

@@ -1643,7 +1653,7 @@ misbehaves and sends too-new messages outside of announced :capabilites:

Changed versioning scheme to Semantic Versioning with three positions Major.Minor.Patch

  • -

    Quit or Exit SHOULD hide instead or exiting when :optional-gui: is supported and MAY not +

    Quit or Exit SHOULD hide instead of exiting when :optional-gui: is supported and MAY not act on the quit through menu otherwise.

  • @@ -1655,7 +1665,7 @@ possibilities for save paths. We added MUST because the rule was just implied be multi-jack clients is "/".

  • -

    Optional GUI SHOULD start hidden, always after a fresh add to the session, after that saving +

    Optional GUI SHOULD start hidden, always after a fresh add to the session. After that saving the visibility state may override it for next time.

  • @@ -1687,16 +1697,23 @@ a symbolically irrelevant console message "Done."

  • unstable /nsm/gui protocol: Send client status after a GUI attaches to running server. This -was not happening before, but it was the intention. It was just broken in nsmd.cpp. This alone would only require API_VERSION_PATCH increment, but we are already incrementing minor.

    +was not happening before, but it was the intention. It was just broken in nsmd.cpp. This alone +would only require API_VERSION_PATCH increment, but we are already incrementing minor.

  • -

    unstable /nsm/gui protocol: Send label "launch error!" when a program is added (or loaded) that does not exist in $PATH. This requires no adaptation of any client, server or GUI because labels are arbitrary already and this is not meant for automatic parsing, but as user information.

    +

    unstable /nsm/gui protocol: Send label "launch error!" when a program is added (or loaded) that +does not exist in $PATH. This requires no adaptation of any client, server or GUI because labels +are arbitrary already and this is not meant for automatic parsing, but as user information.

  • -

    Replies to /nsm/server/save etc. will now be sent back to the sender and not falsely to the last client who replied to /nsm/client/save. This alone would only require API_VERSION_PATCH increment, but we are already incrementing minor.

    +

    Replies to /nsm/server/save etc. will now be sent back to the sender and not falsely to the last +client who replied to /nsm/client/save. This alone would only require API_VERSION_PATCH +increment, but we are already incrementing minor.

  • -

    Server Control API: /nsm/server/add was replying with an undocumented error code on success. Instead, as this document already stated, it now sends "/reply", path, "Launched.". Again, this would have been just API_VERSION_PATCH on its own.

    +

    Server Control API: /nsm/server/add was replying with an undocumented error code on success. +Instead, as this document always specificed, it now sends "/reply", path, "Launched.". +Again, this would have been just API_VERSION_PATCH on its own.

    • @@ -1707,7 +1724,7 @@ was not happening before, but it was the intention. It was just broken in nsmd.c diff --git a/docs/src/api/index.adoc b/docs/src/api/index.adoc index 62df414..56be354 100644 --- a/docs/src/api/index.adoc +++ b/docs/src/api/index.adoc @@ -98,7 +98,7 @@ It MUST NOT allow the user to create a new project/file in another location. This option MUST be disabled. -The application MAY elect to implement an option called 'Import into Session', creates a +The application MAY elect to implement an option called "Import into Session", which creates a copy of a file/project which is then saved at the session path provided by NSM. @@ -129,7 +129,7 @@ management. This option MAY behave as normal (possibly asking the user to confirm exiting), or MAY do nothing to only allow quit from the session-manager control. -When the client supports :optional-gui: this option SHOULD be replaced with hiding the clients GUI +When the client supports :optional-gui: this option SHOULD be replaced with hiding the client's GUI so a quit by window manager hides. @@ -151,7 +151,7 @@ SHOULD be referenced by creating a symbolic link within the assigned session are referring to the symlink. This allows sessions to be archived and transported simply (e.g. with "tar -h") by tools that have no knowledge of the project formats of the various clients in the session. The symlinks thus created should, at the very least, be named after the files they refer -to (some unique component may be required to prevent collisions) +to. Some unique component may be required to prevent collisions. @@ -192,7 +192,7 @@ the name that would normally be passed to `jack_client_open`. For example, Non-M receiving an `open` message; the `open` message will provide a unique client name prefix suitable for passing to JACK. This is probably the most complex requirement of the NSM API, but it isn't difficult to implement, especially if the application simply wishes to delay its initialization -process breifly while awaiting the `announce` reply and subsequent `open` message. +process briefly while awaiting the `announce` reply and subsequent `open` message. `capabilities` MUST be a string containing a colon separated list of the special capabilities the client possesses. e.g. `:dirty:switch:progress:` @@ -323,12 +323,12 @@ save, so that every file in the session can be traced back to a client and, vice name.ID can be used to look up all its files. (For example to clean up the session dir) * The client has no state and does not save at all - * and it MUST NOT misuse e.g. ~/.config to save session specific information e.g. synth-instrument settings + ** and it MUST NOT misuse e.g. ~/.config to save session specific information e.g. synth-instrument settings * The client may use the path client_name.ID directly, resulting in a file client_name.ID in the session directory * The client may append its native file extension (e.g. `.json`) to the path client_name.ID * The client may use the path as directory, creating arbitrary files below, for example recorded .wav. - * and it MUST NOT not use the client ID below this point. This way the data stays transferable by hand to another client instance (in another session). - * best case practice is to always use the same file names, for example `client_name.ID/savefile.json` + ** and it MUST NOT use the client ID below this point. This way the data stays transferable by hand to another client instance (in another session). + ** best case practice is to always use the same file names, for example `client_name.ID/savefile.json` If a project exists at the path, the client MUST immediately open it. @@ -484,7 +484,7 @@ separate program, it should be killed. /nsm/client/hide_optional_gui ---- -No response is message is required. +This message does not require a response. @@ -493,7 +493,7 @@ No response is message is required. ==== Optional GUI If the client has specified the `optional-gui` capability, then it MUST send this message whenever -the state of visibility of the optional GUI has changed. It also MUST send this message after it's +the state of visibility of the optional GUI has changed. It also MUST send this message after its announce message to indicate the initial visibility state of the optional GUI. The client SHOULD always start hidden, if not saved as visible. That implies the first load, after @@ -780,7 +780,7 @@ Rewritten API document without code changes to adapt to existing code or existin possibilities for save paths. We added MUST because the rule was just implied before. * <<#server-to-client-control-messages-open,Open>>: Make clear that the delimiter for multi-jack clients is "/". -* <> SHOULD start hidden, always after a fresh add to the session, after that saving +* <> SHOULD start hidden, always after a fresh add to the session. After that saving the visibility state may override it for next time. * <> MUST be announced in :capabilities: . Before there was a lower case "should", which means nothing. Parallel-examples in the specs cleary say that supporting optional features must be announced first.