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 2019
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 2019
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 2019
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 2019
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 2019
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 2019
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 2019
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 2019