ADC 1.0 specification draft issues.

A private forum for us Super-Humans, I even trust you to be able to edit your own posts =)

Moderator: Moderators

Locked
cologic
Programmer
Posts: 337
Joined: 2003-01-06 13:32
Contact:

ADC 1.0 specification draft issues.

Post by cologic » 2005-12-20 13:15

This seems a more appropriate place than the wiki.

Get some trivialities dealt with, the mass of CSEs in particular:
  • "like it to stand for, Advanced DC". Comma splice error.
  • "a|b means a or b, either a or b may be used" has another CSE.
  • CSE in "port must always be specified, default ports don.t exist"
  • "Named parameters, these ". CSE again.
  • Sec 3.2: smaller files, for large. CSE.
  • "recoverable, if a client gets a recoverable error ". CSE
  • "send NTD, otherwise the passive client" CSE
  • S4.3.16. "transfer files, this way " CSE
  • S4.3.14: "Get File Information, request that ". CSE.
  • S6.2, S6.2.2. Zlib vs zlib.
Other small grammatical issues/typos:
  • nick.s --> nicks (Sec 2.1)
  • "invalid commands, and should dispatch": remove comma.
  • "that is not entered by the user, including protocol names, extensions etc": should have an "and foobar" somewhere, for example. Et cetera too vague, in any case. [Not really a CSE, but related.]
  • "Since action is separated from the message type" -> "Since a message's action is separate from its type", minimally. See comment about 'is' though.
  • "conserve space requirements": a client can conserve space, or it can e.g. respect space requirements. I don't see that it can in this context conserve space requirements (are space requirements a conservable resource?).
  • "Clients must always offer the tree regardless of available slots.". Hm. I'd tend to put a comma there.
  • S6.3.1. "Name uniquely ...". See comment about declared names becoming essentially proper nouns.
  • S6.3: "User commands. User commands are used". Stuttering text?
  • "server, to indicate". Comma unnecessary; contributes nothing that I detect.
  • S4.3.7. "should just be copied directly". s/just // probably works better.
  • "other end actually supports" in S4.3.2. "actually" unnecessary.
  • S4.3.3. "Most of these fields are only interesting in the client-hub communication". interesting to, or interesting during, or etc.
  • ".TTH. is the base32 encoded tth root of the file.". base32 encoded to base32-encoded
  • S4.3.3. "such as share size or client version". s/or/and/
Then, internal consistency proves an issue:
  • unicode is a proper noun (Sec 2.1)
  • TCP-Active --> TCP-active, probably.
  • S4.3.13. "Requests for a certain file or binary data to be transmitted." s/for /that //, for example. More broadly, though, there's no consistent tense across the command descriptions. GFI has "request that ..." where SND has no verb at all
  • TCP active and TCP-Active/TCP-active both occur. Use consistent hyphenation.
  • S4.3.10. "(not Tiger Tree)". Perhaps "(not TTH)"? The document otherwise defines TTH once and drops the expansion.
  • ("State transition to DATA state"), just from what's visible now. Pick one and use it.
  • "depend on the .no slots.". s/the //, but needs rewording anyway. It's already called a "53 Slots full" error; at least use that...
  • "Message is sent directly" -> "This message ..." in accordance with others. I'm not overly fond of the whole structure, but *shrug*.
  • "Type and identifier are the same as for GET." Declared names ("<type> <identifier>") should probably act as proper nouns and keep their capitalization or lack thereof. Either "The specified type and identifier ..." or "<type> and <identifier>" or somesuch.
  • "encoded tth root of the file" and maybe others: pick a consistent capitalization (preferably, the correct one) of TTH. Ditto utf-8 versus UTF-8, except if/when it has to appear in a particular capitalization in some file format illustrated. Also Unicode vs unicode, ZLib vs zlib...
  • In discussing message types: A:"Hub must" vs B: "Hub should" vs C: "are sent" vs D: "must always be sent" vs etc. Consistency needed; IETF normative terminology suggsted. Some message types don't even mention the action of sending or transmitting.
Implementation makes for a poor specification:
  • S6.1. "(must be compatible with libpcre, http://www.pcre.org/)". Not fond of software-as-specification, though PCRE presumable has documentation here.
  • S6.3 "then through the equivalent of the C standard function .strftime., with the current local time specified." See pcre comment.
And, finally, miscellany:
  • Lack of whitespace between section and subsection numbers and titles.
  • General stylistic issues: overreliance on "is" as a sentence's sole verb. Just look at the first few sentences; A is B. C is D. E <other verb> F. G is H. etc. Numbing.
  • 'sometimes' and 'conditionally' in "sometimes conditionally mandatory" mostly overlap. Pick one, or otherwise render more precise this.
  • pseudo-FOURCC? Either simply define what a FOURCC in ADC is, or otherwise elaborate. As far as I can tell, a FOURCC overwhelmingly refers to the AVI field, with which ADC's, er, pseudo-FOURCCs share little. I don't see this as a helpful analogy, when spelling out its lexical grammar's so easy.
  • RFC2732 ([x:x:x:x:x:x:x:x]:port) <--- IIRC, it's more complex, with abbreviated forms, et cetera.
  • "Clients must ignore unknown/badly formatted messages completely", rather than partially or grotesquely or ...? Ignore covers it.
  • WRT to reference to "keep-alive (a single newline)." in Sec 2.1, should be documented elsewhere if not already done...
  • Replace various ad hoc natural language grammar descriptions with BNF, or at least regexes where possible?
  • "The connecting party always speaks first"; a specification probably should avoid such metaphor.
  • "anything outside brackets is to be sent literally" only applies when sending, not receving/parsing/etc. s/sent/interpreted/, perhaps.
  • "one viewable byte" as opposed to "one byte": so, character ::= <non-viewable-byte><viewable-byte> in a name conforms to ADC?
  • "UTF-8 encoding (ASCII codes 33-127)": preferably, express this without reference to ASCII. An ideal client, by my reading of the rest of the document, should behave as if ASCII doesn't exist.
  • "The typical message" -> "A typical message". In fact, though, that not only encompasses all messages, rather than merely typical ones, but cannot exist in any specific message, since such would require a message simultaneously to possess types of D and F.
  • Message layout's special cases cry out for a more systematic description. e.g.

    message_head ::= YYY <myCID>
    message_tail ::= [p0] [p1] ... [pn] [AAq0] [BBq1] ... [XXqn]\n
    message_type_d ::= D <message_head> <targetCID> <message_tail>
    message_type_f ::= F <message_head> <feature> <message_tail>
    message_broadcast ::= <message_type> <message_head> <message_tail>

    Or something. The current, er, conditionally mandatory fields should at least be marked in the "typical message".
  • "Positional parameters, these". One guess... targetCID and feature contain this error too.
  • Better define the grammar, such as depicted previously, and such redundancies as "All messages must have the originating CID specified as first parameter. Type D must also have the target CID as second parameter." may be dropped.
  • "that the other party interprets" [I don't know what I meant. I'll assume I wasn't too asleep at the time and leave it in.]
  • Parenthetical comments should probably be gradually deprecated. Either drop them or integrate them into the text.
  • "Simple hubs can treat this type the same as type B." People will do that kind of thing anyway. This would needlessly and unfortunately fork ADC into "simple base ADC" and "base ADC" when the latter's intended to be sufficiently easy to implement anyway.
  • "unnamed root ./.; / is a name, arguably.
  • ".Generator. is for statistical and informative purposes only and should not be used for extra content discovery." Extra content discovery is? (CDMs, I guess?)
  • "Only rootless directory names may be requested, for instance ./. and ./share/.. Not actually sure if it's a CSE. But, mostly, / and /share/ are rootless?
  • "Error responses should not be sent for obvious errors (a passive client sending a CTM for example).". Whilst I agree, this needs clarification. Does a complete set of obvious errors exist? Can one? An insufficient basis for a standard.
  • S5.1. Hub's IINF should show the HI1.
  • S6.2.1: "all subsequent message passing will be tunneled in one long zlib stream." This begins, presumably, in the message immediately following the one in which the second client mentions ZLIF?
  • S6.3. "Parameters are essentially dictionaries that map one string to another, and each context has its own maps. The strings passed to the hub must first be passed through a dictionary replacement that replaces all keywords in the string," First sentence and first part of second sentence duplicate each other heavily.

GargoyleMT
DC++ Contributor
Posts: 3212
Joined: 2003-01-07 21:46
Location: .pa.us

Post by GargoyleMT » 2005-12-20 16:32

For reference, in case we lose the URL again: http://dcplusplus.sourceforge.net/ADC-0.10pre.html

Edit: I'm retarded.

Locked