graphql-spec icon indicating copy to clipboard operation
graphql-spec copied to clipboard

Fixed capitalization of subsections in chapter 7. Response

Open rivantsov opened this issue 3 years ago • 1 comments

Changed capitalization of subsections to first-cap style like in the rest of the doc

rivantsov avatar Aug 03 '22 05:08 rivantsov

Deploy Preview for graphql-spec-draft ready!

Name Link
Latest commit 4e7dff10b191317a2088d01b9e8a998de8f4a37b
Latest deploy log https://app.netlify.com/sites/graphql-spec-draft/deploys/62ea03f38505940008f09aa1
Deploy Preview https://deploy-preview-981--graphql-spec-draft.netlify.app/draft
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

netlify[bot] avatar Aug 03 '22 05:08 netlify[bot]

Notes from the Dec APAC WG: thanks for spotting this inconsistency. We need to decide on a style guide for the spec and then uniformly apply it across the entire document for all **...** titles. If title case, we should have a concrete style guide such as the Chicago style guide or the New York Times style guide so we know which words to capitalise and which not to.

benjie avatar Dec 08 '22 00:12 benjie

I've used:

$ grep -hr '^\*\*.*\*\*$' . | sort -u

To pull out all the titles of this format. They roughly sort into:

Title case

Seems like deliberate title case.

**Circular References**
**Coercing Results**
**Conforming Algorithms**
**Delivery Agnostic**
**Escape Sequences**
**Explanatory Text**
**Field Ordering**
**First Class Documentation**
**Formal Specification**
**Interfaces Implementing Interfaces**
**Lexical Analysis & Syntactic Parse**
**Lookahead Restrictions**
**Non-Normative Portions**
**Parameterized Grammar Productions**
**Static Semantics**
**Supporting Subscriptions at Scale**

Title case via keywords

Seems like title case but could just be that capitalised keywords such as Non-Null Fields are used, having the effect of title case.

**Block Strings**
**Built-in Directives**
**Built-in Scalars**
**Custom Directives**
**Custom Scalars**
**Default Root Operation Type Names**
**Errors and Non-Null Fields**
**Event Streams**
**Input Coercion**
**Input Object**
**Merging Selection Sets**
**Nullable vs. Optional**
**Optionality and Lists**
**Reserved Names**
**Resolving Abstract Types**
**Result Coercion and Serialization**
**Result Coercion**
**Schema Introspection Schema**
**Schema Validation**
**Type Validation**

Sentence case

Unambiguously sentence case.

**Allowing optional variables when default values exist**
**Arguments are unordered**
**Byte order mark**
**Copyright notice**
**Directive order is significant**
**Error result format**
**Field errors**
**Input object fields are unordered**
**Query shorthand**
**Request errors**
**Type system evolution**

Sentence case except keywords

Capitalisation of keywords (Spreads, Interface Scope, Fragments) but sentence case for the rest.

**Interface Spreads in implemented Interface Scope**
**Variable use within Fragments**

Indeterminate

Single words don't sway one way or the other.

**Conformance**
**Constraints**
**Deprecation**
**Enum**
**Examples**
**Interface**
**Introduction**
**Licensing**
**List**
**Non-Null**
**Object**
**Scalar**
**Semantics**
**Union**
**Validation**

One more thing...

There's inconsistency on whether we should capitalise after a hyphen; e.g. we have Built-in but Non-Null. Again this is something a style guide should dictate.

benjie avatar Dec 08 '22 10:12 benjie

After a deeper analysis, I have proposed this: https://github.com/graphql/graphql-spec/pull/1003

benjie avatar Dec 08 '22 12:12 benjie

Perfect!

rivantsov avatar Dec 08 '22 14:12 rivantsov

Since the new style guide sets the Title case for headings, this PR fixes the remaining non-conforming headers to Title case, so it is ready to merge.

rivantsov avatar Jan 04 '23 16:01 rivantsov