exercises: Document title
#98
Conversation
This reverts commit cc645d2. I got convinced after discussion that wrt README generation we don't need to give implementation details, we just need to know it is the wordified slug. It should belong wherever the other possible fields of metadata.yml are documented.
|
Previous discussion in #97: cc645d2 does not seem an appropriate place for the documentation. cc645d2 has been reverted and now we look at 3bf39d4 . It could go in https://github.com/exercism/docs/tree/master/language-tracks/exercises/anatomy, if other lines in the https://github.com/exercism/docs/blob/master/you-can-help/make-up-new-exercises.md get moved as well. I don't wish to claim responsibility for the move. |
|
This looks like a much better initial place for this information 👍 I agree that moving the section (if required) is a separate unrelated PR. |
| @@ -25,6 +25,7 @@ The `metadata.yml` contains the blurb and source. It has the following structure | |||
| ``` | |||
| --- | |||
| blurb: "A one-sentence summary of the problem to be solved." | |||
| title: "An *optional* field containing the name of this exercise if it contains punctuation or capitalization other than the first letter of each word." | |||
There was a problem hiding this comment.
unsure if this sentence is too clunky, but also unsure of a better way to put it
There was a problem hiding this comment.
Maybe something like: ".. if the slug is not correctly converted by the default algorithm"
But I'm not sure that is an improvement.. or whether the default algorithm needs to be specified.
There was a problem hiding this comment.
if the slug is not correctly converted by the default algorithm
I like this. I think it would make sense to say something about what the default algorithm is as a second sentence.
Okay. I have also added another sentence saying to omit the field if the default algorithm converts correctly, let's see how that looks. |
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
Hmm. Guilty as charged. The third sentence is probably implicitly apparent from the first. Sort of forgot about that.
I'll go with it since it got approvals, I didn't want to re-ask "so what does it look like with the sentence removed" and I guess it doesn't hurt. Except for "perfection is gained not when you have nothing more to add, but nothing more to take away", etc. |
…901) 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. Requires (and has received) confirmation from exercism/configlet#76 that this proposal is appropriate on the configlet side before merging. Requires documentation update before merging: exercism/docs#98 Configlet usage of the `title` field: 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
titlefield in metadata.yml toallow overriding the default capitalisation or punctuation.
This documents this field and how it is used in README generation.
Discussion:
exercism/configlet#76
Addition of
titlefield:exercism/problem-specifications#901
Implementation in
configlet:exercism/configlet#85