search

exercism / legacy-docs

Other
84 stars 55 forks source link

exercises: Document `title` #97

Closed petertseng closed 7 years ago

petertseng commented 7 years ago

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: https://github.com/exercism/configlet/issues/76

Addition of title field: https://github.com/exercism/problem-specifications/pull/901

Implementation in configlet: https://github.com/exercism/configlet/pull/85

Insti commented 7 years ago

This doesn't seem the right place for this.

Here we're talking about the readme template, all we care is that 'Slug.Name' gives a sensible name, we don't need to care where it comes from.

petertseng commented 7 years ago

I think I got convinced of the fact that this document doesn't need to say too much about where the information comes from. I am considering whether "wordified slug" is now no longer the correct description for it, but if I make the assumption that titles are still wordified slugs but with alternate spellings or capitalisation, I think it holds.

I have found a better place for this documentation. Let's see about putting it in you-can-help/make-up-new-exercises.md.

Insti commented 7 years ago

I think it really belongs in:

https://github.com/exercism/docs/tree/master/language-tracks/exercises/anatomy

Unfortunately this doesn't really exist properly yet. Maybe this could be a start.

Edit: Under "Supporting files."

petertseng commented 7 years ago

Well, it appears that a few things in https://github.com/exercism/docs/blob/master/you-can-help/make-up-new-exercises.md could stand to go in https://github.com/exercism/docs/tree/master/language-tracks/exercises/anatomy . As the documentation stands currently, I added the line in the context it belongs in (with the other fields of metadata.yml). If the move happens, I'm going to contend that it shouldn't happen in this PR, though I'm happy to wait for it to happen before this PR gets merged.

petertseng commented 7 years ago

Awkward, I accidentally used a branch on Exercism's copy of the repo... apparently I didn't set up this repo like the others.

petertseng commented 7 years ago

Awkward, I accidentally used a branch on Exercism's copy of the repo... apparently I didn't set up this repo like the others.

I am sorry, but this causes me so much distress that I cannot proceed without deleting this branch. Nothing I can do about it.

(and by implication, that automatically closes this PR. Nothing I can do about it because the source of the PR cannot be changed after it is made. Only thing for it is to create a new PR)