Dividing the guide source file by section

[Jesper Wilhelmsson]

> 9 maj 2022 kl. 15:37 skrev Magnus Ihse Bursie <magnus.ihse.bursie at oracle.com>:
> 
> 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
> 
> Would you like me to refresh my PR with the current up-to-date contents of the guide?

Either that or create a new PR. Whichever you think is the easiest.

The version in PR#47 do have the chapter numbers in the file names, so it will need some more work though.

/Jesper

> 
> /Magnus
> 
>> 
>> 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
>>