Dividing the guide source file by section

[Magnus Ihse Bursie]

On 2022-05-12 16:09, Magnus Ihse Bursie wrote:
>
>
> 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.
.. but I named each file using the corresponding kebab-case version of 
it's title anyway. I think that is a good convention to keep.

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