Dividing the guide source file by section

[Magnus Ihse Bursie]

On 2022-05-07 01:08, Jesper Wilhelmsson wrote:
> Hi all,
>
> Most of the shuffling around and major cleanups in the Guide should be done by now and I think it's time to perform a division of the source file as proposed by Magnus in PR#47.
>
> https://github.com/openjdk/guide/pull/47
>
> I do have a few requests for such a split and this mail is sent to gather any other such requests before the work on the makefile starts.
>
> My thinking so far:
>
> * Each source file should be named more or less the same as the section it contains. I don't want to say exactly the same because eventually some typo is found or a section is renamed slightly and I don't want that to enforce a rename of the file. I'll quantify it by saying that the section name and the file name should be 80% the same. Obviously that's just a random number that seems fine for now.
I don't think you should be so afraid of renames. Just trust your 
feelings Luke. And Git rename functionality.
>
> * There should not be any serial numbers in the file names. It must be simple to add new sections in the middle of the guide, and to move a section to a different place. This implies that there must be a separate file that contains the order of the sections. I'm fine with this file to be of any readable, easy editable format. Plain text, XML, markdown - whatever makes it easy to use.
>
> * All section files in the src directory must be included in the composed guide file.

Note that the src directory contains more files than index.md. I'm not 
sure what the purpose of these files are. But to make this work, I 
needed to put the chapters in a separate folder. If we ever remove those 
extra files, we could presumably move the chapters up to the "src" 
level. Not sure it's worth it, though.
> If a section file on disk is not present in the index, a build error should be generated.
Missed that part, fixed now.

/Magnus

> I don't want to have section files that are place holders or things that maybe should be included at some point in there. We could have a separate directory for such files if anyone think that is a good idea. There are currently a couple of files in there that aren't part of the guide today, these must be taken care of before this can be a reality.
>
>
> I'll leave it here for now. Any other suggestions are welcome!
> /Jesper
>