[Bf-docboard] Including Introductory Text in index.rst

[Francesco Siddi]

Hi Greg,
the idea of keeping index and introduction separate exists because I though having functional separation would be good (index exists only to link in sibling documents, introduction is actual content). For example, when we get a proper navtree (like the one here http://docs.mongodb.org/manual/) then we might want to keep any content outside of index.rst because it will be hard to access.

In the past I tried what you are suggesting, and did not go for it simply because I was a afraid of making pages that were too long.

So, I think going with your second proposal (including introduction in index, but not removing it) is a good idea.

Cheers,
Francesco

On 26 Feb 2015 at 15:03:13, Greg Zaal (gregzzmail at gmail.com) wrote:

Hey everyone,

Why is it that we have both an index.rst and an introduction.rst? The differences:

Index:
What you see when clicking on a chapter in the navigation bar
What is shown when entering the chapter folder as the URL (e.g. blender.org/manual/render/ takes you to index.html in that folder)
Only contains the table-of-contents, no other text (usually)
Introduction:

Provides a brief explanation on what is covered in that chapter/folder.
Is always the top-most item in the index's table-of-contents.
To me it seems like we should put all the helpful introductory explanations inside the index.rst, since that's what people will be looking at most. Currently if I want to read about (e.g.) modeling, I click on the chapter, and then I have to click again on the introduction in the ToC. Once I've read that, I have to then go back to the index and see where to continue reading.

Additionally, some introduction pages are written as a sort of index page anyway (e.g. modifiers)
I'd like to propose that we put the introductory text on the index page by doing one of the following:

Delete introduction.rst and just move that text to the top/bottom of the index page.
Keep introduction.rst, but make it hidden in the ToC - then add `.. include:: introduction.rst` at the top/bottom of the index to insert the contents of the introduction file in there.
I tried out the second method here: http://gregzaal.com/manual/render/cycles - the RST source for that is: http://www.pasteall.org/56903

What do you guys think? Should we have intro text in the index page? And if so, should we delete introduction.rst or simply include it?

Cheers,
Greg

_______________________________________________  
Bf-docboard mailing list  
Bf-docboard at blender.org  
http://lists.blender.org/mailman/listinfo/bf-docboard  
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20150226/3b393874/attachment.htm