Dividing the guide source file by section

[Jesper Wilhelmsson]

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.

* 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. If a section file on disk is not present in the index, a build error should be generated. 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