www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - [spec] Numbered chapters

reply Dibyendu Majumdar <d.majumdar gmail.com> writes:
Hi,

I would like to put a number prefix to each chapter so that the 
order is obvious. So the documents will also be renamed to 
nn-doc.html etc. Thoughts?

Thanks
May 14
next sibling parent Nicholas Wilson <iamthewilsonator hotmail.com> writes:
On Tuesday, 14 May 2019 at 21:29:17 UTC, Dibyendu Majumdar wrote:
 Hi,

 I would like to put a number prefix to each chapter so that the 
 order is obvious. So the documents will also be renamed to 
 nn-doc.html etc. Thoughts?

 Thanks
Sounds like a good idea. I think the ordering of some sections will be a bit arbitrary but that is fine. Its probably best to post a the order that you think makes sense and get a bit of feedback on it. Thanks Nic
May 14
prev sibling next sibling parent Seb <seb wilzba.ch> writes:
On Tuesday, 14 May 2019 at 21:29:17 UTC, Dibyendu Majumdar wrote:
 Hi,

 I would like to put a number prefix to each chapter so that the 
 order is obvious. So the documents will also be renamed to 
 nn-doc.html etc. Thoughts?

 Thanks
Be careful here as this will break the existing URLs, we can do redirects in .htaccess However, I'm not sure whether renaming to include the number is a good idea as it will break a lot of links whenever the order is changed and mess with the git history. I am aware that both problems can be fixed, but I'm not sure whether it's worth the effort?
May 14
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 5/14/19 10:29 PM, Dibyendu Majumdar wrote:
 Hi,
 
 I would like to put a number prefix to each chapter so that the order is 
 obvious. So the documents will also be renamed to nn-doc.html etc. 
 Thoughts?
I strongly suggest to start with lower-scale PRs. Numbering chapters, renaming files, reorganizations etc are attractive for newcomers but not recommended.
May 14
parent reply Dibyendu Majumdar <d.majumdar gmail.com> writes:
On Wednesday, 15 May 2019 at 00:14:15 UTC, Andrei Alexandrescu 
wrote:
 I strongly suggest to start with lower-scale PRs. Numbering 
 chapters, renaming files, reorganizations etc are attractive 
 for newcomers but not recommended.
Okay will leave renaming and numbering for now, but I would like to add files and change the order for some topics. For instance the full grammar should be in an appendix I think rather than the third topic - as the grammar would/should be covered in the individual sections anyway. Does that make sense? Regards
May 15
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.com> writes:
On 5/15/19 6:23 AM, Dibyendu Majumdar wrote:
 On Wednesday, 15 May 2019 at 00:14:15 UTC, Andrei Alexandrescu wrote:
 I strongly suggest to start with lower-scale PRs. Numbering chapters, 
 renaming files, reorganizations etc are attractive for newcomers but 
 not recommended.
Okay will leave renaming and numbering for now, but I would like to add files and change the order for some topics. For instance the full grammar should be in an appendix I think rather than the third topic - as the grammar would/should be covered in the individual sections anyway. Does that make sense?
I think some things ought indeed to be reordered. Not sure about moving the grammar to the appendix. Larger point is - do you really want your first contribution to be a major revamp? Why? No need to mark your territory. There's so many good things to do there that can be done quickly while learning the ropes.
May 15
next sibling parent Dibyendu Majumdar <d.majumdar gmail.com> writes:
On Wednesday, 15 May 2019 at 15:22:53 UTC, Andrei Alexandrescu 
wrote:
 I think some things ought indeed to be reordered. Not sure 
 about moving the grammar to the appendix. Larger point is - do 
 you really want your first contribution to be a major revamp? 
 Why? No need to mark your territory. There's so many good 
 things to do there that can be done quickly while learning the 
 ropes.
No it isn't that. I hope to submit small changes at a time, so it won't be a major revamp at all. I am looking at the C, C++, Go, and Java specs as the model to follow, and as I work down the spec, I'd like things to be in the right order. But I am getting ahead here as I am still on intro right now. I just wanted to give a heads up that I'd like to move the full grammar down to the end. Regards
May 15
prev sibling parent Dibyendu Majumdar <d.majumdar gmail.com> writes:
On Wednesday, 15 May 2019 at 15:22:53 UTC, Andrei Alexandrescu 
wrote:
 I think some things ought indeed to be reordered. Not sure 
 about moving the grammar to the appendix. Larger point is - do 
 you really want your first contribution to be a major revamp? 
 Why? No need to mark your territory. There's so many good 
 things to do there that can be done quickly while learning the 
 ropes.
Also to clarify - not trying to mark territory or anything like that. Just want to help D in a concrete way - I do not use D so nothing to prove.
May 15