[Bf-docboard] Overviews

[Tobias Heinke]

Hi all,

I removed the overviews from the manual (rBM3885 - rBM3900).
These are links, commonly on intro pages, to the subsections of the 
chapter and a brief ~2 sentence summary.
(last remaining: 
https://docs.blender.org/manual/en/dev/editors/3dview/object/types.html).
I guess these whereoriginally created because the wiki has no TOCs, so 
pages had to be linked manually.

The reason for removing them was:
Duplicated content: every page should start with a summary anyway, so 
merging these together could raise the quality.
Additional work to keep them up-to-date: which was confirmed by missing 
summaries or even whole items.

The question is if we should add them back in, but this time 
automatically generating them with a script.
Almost all it would take it to do is copy the first sentences of a page. 
This can be achieved in different ways:

1. The build-in include:
Would need either to be line based or with comment marks (.. copy from 
here). I didn't actually tried it.
con: marks in the text or breaks easily, without a way to check it
pro: full-automatic

2. Custom extension: nope

3. A custom script:
I think the most intuitive way is to select per sentence.
con: "e.g. " or any other dot space could breaks it. semi-automatic
pro: easy to check (diff), line wraps

I quickly created a proof of concept.
The overview on the intro page (physics in this case) would be generated 
based on a pseudo directive:

     .. overview
        particles/introduction: 2
        collision: 0
        fluid/introduction: 2
        soft_body/introduction: 1

It is composed out of the relative path and the number of sentences to 
copy. It is stored on the page as a comment for future generations :)

Here is the current raw output of the script:

particles
Particles are lots of items emitted from mesh objects, typically in the 
thousands. Each particle can be a point of light or a mesh, and be 
joined or dynamic.
collision

fluid
Fluid physics are used to simulate physical properties of liquids 
especially water. While creating a scene in Blender, certain objects can 
be marked to participate in the fluid simulation.

soft body
A Soft Body in general, is a simulation of a soft or rigid deformable 
object.

>The output could then be appended formatted as normal RST syntax.
The directive can be compared with index's toc to detect modifications.

Regards,
Tobias




-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.blender.org/pipermail/bf-docboard/attachments/20171207/8b5deb9e/attachment.html>