-
-
Notifications
You must be signed in to change notification settings - Fork 547
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
Conversation
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.
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? |
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 |
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. |
Is there any reason why we could not merge this as it is? |
I guess it can be merged as soon as I got agreement that the 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. |
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
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
* Capitalise initialisms * pascals-triangle: Add apostrophe to title exercism/problem-specifications#901 exercism/configlet#85 (as-yet unreleased)
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 "LoremIpsum". 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 thedefault 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.