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

Add titles to exercises with non-default capitalisation/punctuation #901

Merged
merged 1 commit into from
Oct 4, 2017
Merged

Add titles to exercises with non-default capitalisation/punctuation #901

merged 1 commit into from
Oct 4, 2017

Conversation

petertseng
Copy link
Member

@petertseng petertseng commented Sep 15, 2017

In generated READMEs, the rule for converting an exercise slug to a
human-readable form is to capitalise only the first letter of each
hyphen-separated word. For example, lorem-ipsum will become "Lorem
Ipsum". This is true of both the Trackler and Configlet README
generators.

Trackler's README generator (see name function):
https://github.com/exercism/trackler/blob/master/lib/trackler/specification.rb

Configlet's README generator (see Name function):
https://github.com/exercism/configlet/blob/master/track/problem_specification.go

For some exercises this is not the best possible title. For example see
http://exercism.io/exercises/haskell/rna-transcription/readme and
observe that the title is "Rna Transcription", whereas "RNA
Transcription" seems more faithful to the rules (RNA, as an initialism,
should be in all caps).

If we would like the README generator to generate these non-default
titles, it seems to make the most sense to add it in
problem-specifications. The alternative of adding the exceptions to
configlet has the disadvantage of requiring an update to configlet for
any new exercise that desires a non-default title.

The proposal is a title field in metadata.yml that overrides the
default capitalisation or punctuation. For those exercises for which the
default title is appropriate, it is recommend that this field be
omitted, to avoid unnecessary configuration.

Please receive confirmation from
exercism/configlet#76 that this proposal is
appropriate on the configlet side before merging.

Please prepare a corresponding update to
https://github.com/exercism/docs/blob/master/language-tracks/exercises/anatomy/readmes.md
before merging.

In generated READMEs, the rule for converting an exercise slug to a
human-readable form is to capitalise only the first letter of each
hyphen-separated word. For example, `lorem-ipsum` will become "Lorem
Ipsum". This is true of both the Trackler and Configlet README
generators.

Trackler's README generator (see `name` function):
https://github.com/exercism/trackler/blob/master/lib/trackler/specification.rb

Configlet's README generator (see `Name` function):
https://github.com/exercism/configlet/blob/master/track/problem_specification.go

For some exercises this is not the best possible title. For example see
http://exercism.io/exercises/haskell/rna-transcription/readme and
observe that the title is "Rna Transcription", whereas "RNA
Transcription" seems more faithful to the rules (RNA, as an initialism,
should be in all caps).

If we would like the README generator to generate these non-default
titles, it seems to make the most sense to add it in
problem-specifications. The alternative of adding the exceptions to
configlet has the disadvantage of requiring an update to configlet for
any new exercise that desires a non-default title.

The proposal is a `title` field in metadata.yml that overrides the
default capitalisation or punctuation. For those exercises for which the
default title is appropriate, it is recommend that this field be
omitted, to avoid unnecessary configuration.

Please receive confirmation from
exercism/configlet#76 that this proposal is
appropriate on the configlet side before merging.

Please prepare a corresponding update to
https://github.com/exercism/docs/blob/master/language-tracks/exercises/anatomy/readmes.md
before merging.
@petertseng petertseng changed the title Add titles to exercises with non-default capitalisation/punctuation Do not merge: Add titles to exercises with non-default capitalisation/punctuation Sep 16, 2017
@petertseng
Copy link
Member Author

Another item that I want to check before merging:

Does anything else translate slugs into human titles and thus would benefit from a code change? Or if I ask very specifically: Does the website need to change?

@petertseng
Copy link
Member Author

Does the website need to change?

v2: Titles are displayed as-is https://github.com/exercism/prototype/blob/master/app/views/exercises/show.html.haml#L21 They are a field in the database https://github.com/exercism/prototype/blob/master/db/schema.rb#L71 . The code that imports the exercises into the database would benefit from being aware of title.

@petertseng
Copy link
Member Author

petertseng commented Sep 22, 2017

Does the website need to change?

v1: https://github.com/exercism/exercism.io/blob/master/app/views/languages/_exercises.erb#L10 which I think comes from Trackler. Nice to change Trackler but not necessary if we assume v1 doesn't stay around for long.

@Insti
Copy link
Contributor

Insti commented Oct 1, 2017

Is there any reason why we could not merge this as it is?
The extra information should be ignored by the tools until they are updated to use it, but once they are it will be already there.

@petertseng
Copy link
Member Author

I guess it can be merged as soon as I got agreement that the title key is acceptable to possible consumers. I guess I got that agreement in exercism/configlet#76.

However, as a rule I do not allow myself to merge this until I write the doc for it. If someone else merges it because their rules != my rules, I guess I can't complain, if they're in a hurry.

@petertseng petertseng changed the title Do not merge: Add titles to exercises with non-default capitalisation/punctuation Add titles to exercises with non-default capitalisation/punctuation Oct 2, 2017
petertseng added a commit to exercism/legacy-docs that referenced this pull request Oct 3, 2017
In generated READMEs, the rule for converting an exercise slug to a
human-readable form is to capitalise only the first letter of each
hyphen-separated word.

For some exercises this is not the best possible title. For example see
http://exercism.io/exercises/haskell/rna-transcription/readme and
observe that the title is "Rna Transcription", whereas "RNA
Transcription" seems more faithful to the rules (RNA, as an initialism,
should be in all caps).

For those exercises, we add an optional `title` field in metadata.yml to
allow overriding the default capitalisation or punctuation.

This documents this field and how it is used in README generation.

Discussion:
exercism/configlet#76

Addition of `title` field:
exercism/problem-specifications#901

Implementation in `configlet`:
exercism/configlet#85
petertseng added a commit to exercism/legacy-docs that referenced this pull request Oct 3, 2017
In generated READMEs, the rule for converting an exercise slug to a
human-readable form is to capitalise only the first letter of each
hyphen-separated word.

For some exercises this is not the best possible title. For example see
http://exercism.io/exercises/haskell/rna-transcription/readme and
observe that the title is "Rna Transcription", whereas "RNA
Transcription" seems more faithful to the rules (RNA, as an initialism,
should be in all caps).

For those exercises, we add an optional `title` field in metadata.yml to
allow overriding the default capitalisation or punctuation.

This documents this field and how it is used in README generation.

Discussion:
exercism/configlet#76

Addition of `title` field:
exercism/problem-specifications#901

Implementation in `configlet`:
exercism/configlet#85
@petertseng petertseng merged commit f0f012a into exercism:master Oct 4, 2017
@petertseng petertseng deleted the custom-title branch October 4, 2017 01:43
ijanos pushed a commit to exercism/rust that referenced this pull request Oct 5, 2017
* Capitalise initialisms
* pascals-triangle: Add apostrophe to title

exercism/problem-specifications#901
exercism/configlet#85 (as-yet unreleased)
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

Successfully merging this pull request may close these issues.

2 participants