Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

auto-generated Dependencies section? #937

Closed
equalsJeffH opened this issue Feb 24, 2017 · 2 comments
Closed

auto-generated Dependencies section? #937

equalsJeffH opened this issue Feb 24, 2017 · 2 comments

Comments

@equalsJeffH
Copy link

equalsJeffH commented Feb 24, 2017

Various specs have a (manually-generated) "Dependencies" (or equivalent) section towards the "front" of the spec so readers know what kind of things to expect later on (e.g., https://www.w3.org/TR/2016/REC-webstorage-20160419/#dependencies).

Though, bikeshed auto-generates backmatter that essentially duplicates said "dependencies" sections, e.g.: https://www.w3.org/TR/webauthn/#index-defined-elsewhere .

Perhaps bikeshed could have a directive indicating whether to place #index-defined-elsewhere in frontmatter or in backmatter?

@tabatkins
Copy link
Collaborator

While I definitely could free up the index generation a bit so it can be moved around to elsewhere in the document, I highly doubt that editors will generally consider it an improvement over their existing "Dependencies" sections. They're usually hand-crafted to refer to the most significant dependencies, with prose talking about them, rather than just a bare listing of every single external reference used in the entire spec.

Also, those "Dependencies" sections are mostly an artifact of the older spec generators being unable to provide good cross-spec linking and reference checking. For the most part they can be removed in modern Bikeshedded specs.

@domenic
Copy link
Collaborator

domenic commented Feb 24, 2017

Also, those "Dependencies" sections are mostly an artifact of the older spec generators being unable to provide good cross-spec linking and reference checking. For the most part they can be removed in modern Bikeshedded specs.

This has also been my experience.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants