httpwg
Flatten the structure a little reduce a level from TOC
This is one proposal for addressing the point raised in #3169.
Currently, the bulk of the spec is located in Section 4. We have an entire spec for the topic of resumable uploads, so being shy to use top-level sections for key concepts might be a bit conservative. This PR flattens the structure (but doesn't move any sections around) in order to reduce the amount of third-level sections, making space to only define the new headers in them. (FWIW 4th-level TOC items tend to indicate over-nesting and don't always get rendered in the TOC)
Landing this would number sections and be slightly disruptive to open reviews/issues. If we like the direction, I'd suggest holding it until other issues are closed out.
Current ToC (ignoring appendices)
1. Introduction
2. Conventions and Definitions
3. Overview
3.1. Example 1: Complete upload of representation data with
known size
3.2. Example 2: Upload as a series of parts
4. Upload Resource
4.1. State
4.1.1. Offset
4.1.2. Completeness
4.1.3. Length
4.1.4. Limits
4.2. Upload Creation
4.2.1. Client Behavior
4.2.2. Server Behavior
4.2.3. Examples
4.3. Offset Retrieval
4.3.1. Client Behavior
4.3.2. Server Behavior
4.3.3. Example
4.4. Upload Append
4.4.1. Client Behavior
4.4.2. Server Behavior
4.4.3. Example
4.5. Upload Cancellation
4.5.1. Client Behavior
4.5.2. Server Behavior
4.5.3. Example
4.6. Concurrency
5. Status Code 104 (Upload Resumption Supported)
6. Media Type application/partial-upload
7. Problem Types
7.1. Mismatching Offset
7.2. Completed Upload
7.3. Inconsistent Length
8. Content Codings
9. Transfer Codings
10. Integrity Digests
10.1. Representation Digests
10.2. Content Digests
11. Responses to Uploads
12. Upload Strategies
12.1. Optimistic Upload Creation
12.1.1. Upgrading To Resumable Uploads
12.2. Careful Upload Creation
13. Security Considerations
14. IANA Considerations
14.1. HTTP Fields
14.2. HTTP Status Code
14.3. Media Type
14.4. HTTP Problem Types
15. References
15.1. Normative References
15.2. Informative References
Proposed Toc (ignoring appendices)
1. Introduction
2. Conventions and Definitions
3. Overview
3.1. Example 1: Complete upload of representation data with
known size
3.2. Example 2: Upload as a series of parts
4. Upload Resource
4.1. Offset
4.1.1. Upload-Offset
4.2. Completeness
4.2.1. Upload-Complete
4.3. Length
4.3.1. Upload-Length
4.4. Limits
4.4.1. Upload-Limits
5. Upload Creation
5.1. Client Behavior
5.2. Server Behavior
5.3. Examples
6. Offset Retrieval
6.1. Client Behavior
6.2. Server Behavior
6.3. Example
7. Upload Append
7.1. Client Behavior
7.2. Server Behavior
7.3. Example
8. Upload Cancellation
8.1. Client Behavior
8.2. Server Behavior
8.3. Example
9. Concurrency
10. Status Code 104 (Upload Resumption Supported)
11. Media Type application/partial-upload
12. Problem Types
12.1. Mismatching Offset
12.2. Completed Upload
12.3. Inconsistent Length
13. Content Codings
14. Transfer Codings
15. Integrity Digests
15.1. Representation Digests
15.2. Content Digests
16. Responses to Uploads
17. Upload Strategies
17.1. Optimistic Upload Creation
17.1.1. Upgrading To Resumable Uploads
17.2. Careful Upload Creation
18. Security Considerations
19. IANA Considerations
19.1. HTTP Fields
19.2. HTTP Status Code
19.3. Media Type
19.4. HTTP Problem Types
20. References
20.1. Normative References
20.2. Informative References
Thanks for the feedback. Based on the number of comments/issues we received on the published draft. I suggest holding this change. Perhaps even published as a standalone I-D revision to ensure the WG can more easily spot the deltas. Hence, I've marked it as draft for now.
Its bitrotten and so I stand by the earlier comment. I'd like to see us land changes that address more issues before we do a big restrucutre like this.