RFR: Split up monolithic markdown

[Magnus Ihse Bursie]

On Tue, 16 Mar 2021 13:38:54 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> The original Developer's Guide was split into one html page per chapter. This was (rightly so) combined into a single html page previously by Jesper.
>> 
>> However, this also means that we got a single, monolithic markdown file to edit. This makes the file unnecessarily hard to navigate and edit.
>> 
>> This patch will instead split up the original index.md file into separate markdown documents, one per chapter. At build time, they are recombined into a single index.md file again (exactly identical with the one I started with).
>> 
>> This patch depends on https://github.com/openjdk/guide/pull/46.
>
> Continuing the erroneously placed discussion from PR #46:
>> I don't mind this change but...
> 
> If we want to future-proof this and make it a stable foundation we shouldn't have chapter numbers in the file names. I don't want to rename all chapters just because a new one is inserted or removed somewhere. Also, since we are quite early in the making of this document it's likely that chapters will move within the guide as well.

I thought it was a simple and elegant solution to get the chapters to line up, both when combining them in the make file, and in the IDE when editing them (as long as your IDE sorts files based on name). Again, I don't see renaming as a big problem, maybe that's what makes our opinions differ on this patch.

But sure, if you really prefer, I can provide another way of telling the build system how to organize the files when combining them.

Does it sound like a good idea to you to list them in order in a text file?

-------------

PR: https://git.openjdk.java.net/guide/pull/47