Improve doc/protocol description

[ghost]

Working on a server using the MPD protocol but can't find anything actually mentioning nor showing a single example of a successful command -> response transaction, specifically how and when the server should format and send its response.

How do I format a simple response to a command requesting the status? Before the OK?

client: status\n server: volume 24\n repeat 0\n OK\n

The mpc failed to parse the response. After? The same thing.

Do I format the response like this maybe?

status volume 24\n status repeat 0\n OK\n

When and how do I respond to a command_ok_list? Before or directly after a list_OK? After the last list_OK?

It's nice with an ACK example on the page named response_syntax, but at least the basic examples or for that matter, any mention of how the server should respond to a command requiring information wouldn't hurt.

And I really like

The return value is whatever the return for a list of commands is.

https://www.musicpd.org/doc/protocol/command_lists.html

[MaxKellermann]

Multi-line responses should be multi-line in the documentation as well - i.e. no \n escape codes.
I don't understand your comand list question.
You're right that this documentation page is pretty badly phrased - it's still the original text from >10 years ago before I entered MPD development - blame my predecessos for writing such a text, and blame me for not rewriting it in 10 years ;)

[ghost]

Alright,

Lets say MPC for example sends,

command_list_ok_begin\n
status\n
currentsong\n
command_ok_list_end\n

Should the server response look like this?

volume 25 repeat 0 random 1 single 0...\n
list_OK\n
song info...\n
list_OK\n
OK\n

I'd be happy to help rewrite it when I understand the basics :)

EDIT:

Alright, was just the simple matter of a colon infront of each response object.

volume: 0-100 or -1 if the volume cannot be determined

https://www.musicpd.org/doc/protocol/command_reference.html

This line aren't really clear whether it just describes the volume value or actually shows the response format and value with that colon ^^

Will get to rewrite the protocol docs later on this month if you want.

[MaxKellermann]

The "status" response is multi-line; each line describes one attribute as described in the documentation; format is NAME: VALUE. If you want to know how it looks like, try telnet/netcat to any MPD and type the command.
As bad as it is, the MPD protocol documentation has survived for 15 years because looking at real MPD responses answers most questions.
btw. the protocol documentation is still in DocBook format; the user and developer manual have already been converted to Sphinx (an implementation of reStructuredText). Editing DocBook is somewhat cumbersome.