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

[Greg Zaal]

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
<http://gregzaal.com/manual/modifiers/introduction.html#modify>)

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20150226/3f895313/attachment.htm