Reorder tour; a script for reordering

[S11001001]

The tour introduction also mentions those tour pages that weren't mentioned before.

A script is included that does renumbering.

$ ruby renumber.rb --help
Usage: ./renumber.rb [OPTIONS] [-i INDEX | FILES]
    -i, --index FILE                 Use newline-separated list of files
    -e, --encoding ENC               Set character encoding
    -x, --print-index                Show index, don't change any files
    -s, --start-from NUM             Use fresh numbers instead of reorganizing the existing numbers

The workflow is pretty straightforward for using this script to
reorganize a multi-file document.

1. Have a clean tree.
2. Use -x *.md to print an index; write that to a file.
3. Reorder the lines in the file to match your desired order.
4. Feed the index back in with -i.

[SethTisue]

LGTM, thank you! After we get #312 merged, can you rebase this and ping me?

[heathermiller]

I don't quite why you've reorganized the numbering? Why was the previous ordering bad and why is this better? Is a Ruby script really necessary for this? (We run on Github pages so Github won't run any plugins for us.)

[SethTisue]

good questions.

re: GitHub pages, if I understand correctly the idea is to run the reordering script during development and then check the resulting changes into version control.

as for ordering,

the old order is: Introduction, Abstract Types, Annotations, Classes, Case Classes, Compound Types, Sequence Comprehensions, Extractor Objects, Generic Classes, Implicit Parameters, Inner Classes, Mixin Class Composition, Nested Functions, Anonymous Function Syntax, Currying, Automatic Type-Dependent Closure Construction, Operators, Higher-order Functions, Pattern Matching, Polymorphic Methods, Regular Expression Patterns, Traits, Upper Type Bounds, Lower Type Bounds, Explicitly Typed Self References, Local Type Inference, Unified Types, Variances, Views, XML Processing, Default Parameter values, Named Parameters

the new order is: Introduction, Unified Types, Classes, Traits, Mixin Class Composition, Anonymous Function Syntax, Higher-order Functions, Nested Functions, Currying, Case Classes, Pattern Matching
XML Processing, Regular Expression Patterns, Extractor Objects, Sequence Comprehensions, Generic Classes, Variances, Upper Type Bounds, Lower Type Bounds, Inner Classes, Abstract Types, Compound Types, Explicitly Typed Self References, Implicit Parameters, Views, Polymorphic Methods, Local Type Inference, Operators, Automatic Type-Dependent Closure Construction, Annotations, Default Parameter values, Named Parameters

the old ordering doesn't have any rhyme or reason to it that I can see — not sure how it got that way. the new ordering seems to me like a reasonable attempt at putting beginning topics first.

[heathermiller]

Ah, ok. I see. While I agree with you about the ordering now being more sensible, I don't agree that we should be adding Ruby scripts to be automatically enforcing that ordering. Since we have like 20 or so stub articles, I think it's sufficient to reorder once by hand and assume that the ordering stays that way. We currently don't rely on any external Ruby scripts and the addition of one for such a trivial reason (reordering articles only once) seems like overkill.

[SethTisue]

fine w/ me

[SethTisue]

the ordering is harder now — there are now "next" and "previous" links that have to be updated.

so, I cherry-picked the two commits in this PR that don't have to do with ordering onto master; they are now 8cea9b0 and a856263

as for reordering, I'll put together a fresh PR on that myself.

[S11001001]

It is not really enough to do the renumbering once; if you want to insert an article early in the chain, you have to shift all the numbers after it forward by 1. And then again the next time.

[heathermiller]

@S11001001, we've added maybe 1 stub article in like 6 years so I think that manually re-ordering isn't a big issue.

@SethTisue Really? Why do we have next/previous links? I didn't realize someone added those. I think those are also unnecessary given that there's a whole TOC that's more easily accessible on the right side of the page...

[heathermiller]

Haha! I'm the one who enthusiastically accepted the next/previous link PR for tutorials. Apparently I didn't think these through at the time. While they're nice to have, I think I might revert this commit... I think they don't add as much value for the complexity.

[S11001001]

IIRC—this was a while ago—I chose this ordering to match up with the introduction's order of mentioning topics.

[SethTisue]

@heathermiller if after you merge #436 you want to rip out the next/previous links again, it's fine with me. I don't have a strong feeling about it either way.