[Bf-docboard] Propsal: fundamentals, citation

Wed Jun 29 13:48:43 CEST 2016

Hello Campbell,

Fundamentals is not out of scope - because I've added few new terms and 
these are even in scope of the glossary. as it is now.

Terms could easily added in a centralized - it just delays the clean up 
to later. Terms are not added often.
     No one added a term in probably more than six years (excluding my 2 
terms).

It has not to be maintained - all the terms I replaced were already 
wrong, when they have been added years ago.

https://www.blender.org/manual/glossary/index.html#term-refraction
     (the speed of light is absolutely constant)

Blender is not a small software program with a bunch of internal name 
terms, where a central glossary might be sufficient,
but not for a complex software suite.

Contra central glossary:

Difficult (impossible) to clean up:

- Finding terms that shouldn't be in the glossary.
- Assimilation of the classification of terms.

https://www.blender.org/manual/glossary/index.html#term-anti-aliasing

A part of the definition is already taken up by the classification:

https://www.blender.org/manual/glossary/index.html#term-environment-map

A lot of links are needed and the terms are not comparable, because they 
are scattered:

https://www.blender.org/manual/glossary/index.html#term-topology
https://www.blender.org/manual/glossary/index.html#term-straight-alpha

Extended content looks bad:

https://www.blender.org/manual/glossary/index.html#term-non-manifold
https://www.blender.org/manual/glossary/index.html#term-color-space

Extended content like images is impossible.

It's not readable top to bottom.

We could also have both:
The old terms sorted in.
The newly created ones in a glossary called "new".
(like the unsorted bookmarks in a browser)

So I'm asking for a test run. It's easy revertible.

Tobias

Am 16.06.2016 um 16:43 schrieb Tobias Heinke:
>
> Hey Campbell,
>
> Thanks for the reply.
>
> As I said, linking to terms still works and the definitions are still 
> compact.
> Searching through the terms is possible thanks to the index.
>
> The Blender Manual never was a pure software manual (specification), 
> it can't because of the audience it addresses.
> And Funda is even a step into the direction making the manual more 
> about the software
> by separating the non Blender specific content.
>
> The problem of a centralized glossary is it get messier with every new 
> term added and cleaning it up is not fun.
>
> Hierarchy occurs naturally and is currently expressed by link between 
> terms:
>
>     Anti-aliasing: MSAA, FSAA...
> https://www.blender.org/manual/glossary/index.html#term-anti-aliasing
>
>
> Non of the paper I cited sofar belongs to that category technical paper,
> in the sense of detailed information about the implementation of a 
> technique.
>
> I disagree, that these papers are just interesting for developers.
> The citation fulfills the different purposes of pioneer papers and 
> recommended literature.
> Why these pioneer papers have to be cited I have written in the 
> previous mail.
>
> Fundamentals doesn't becomes outdated:
> Eric Veach PhD thesis "Robust Monte Carlo methods for light transport 
> simulation" from 1997 still holds up.
> And Blinn will still be the one who introduced bump mapping to 3D CG.
> c.f. http://old.siggraph.org/publications/seminal-graphics.shtml
>
> Tobias
>
> Am 15.06.2016 um 16:11 schrieb Campbell Barton:
>> Am quite against replacing the glossary,
>> in computer graphics their are many cryptic terms (FSAA, SSS, gimbal
>> lock, ngon... etc),
>>
>> As an author you can write :term:`FSAA` which links to the glossary,
>> if the term is missing, you get a warning and you can add it.
>> The descriptions generally short and to the point, with links to
>> expanded information where appropriate.
>> There is also no need to manage page hierarchy, add new categories,
>> think about where each term *belongs*.
>> its a big list which is easy to search and linked to as needed.
>>
>> What you suggest is a more general document on computer graphics
>> fundamentals which is OK,
>> but outside the scope of a software manual.
>>
>> >From reading what you have so far, its quite esoteric from a user
>> perspective and more of interest to developers, with links links to
>> technical papers on each topic.
>> People interested in such papers can find it themselves searching
>> online and don't need us to spend time on a document for this, which
>> is likely to be outdated in a few years anyway.
>>
>> eg:
>>
>> http://blender-manual.readthedocs.io/en/testing/fundamentals/physics/phy_matter.html
>> http://blender-manual.readthedocs.io/en/testing/fundamentals/computer/com_light.html
>>
>> Or, if there is some need for a document like this, I think its
>> different enough from a software reference manual,
>> that it can be maintained as a separately (which the manual could link
>> to, when it makes sense, as with any other web site).
>>
>> On Wed, Jun 15, 2016 at 5:57 AM, Tobias Heinke
>> <heinke.tobias at t-online.de>  wrote:
>>> Hi Campbell,
>>>
>>> Yes, to replace the glossary.
>>> First I want to keep the glossary parallel to Fundamentals and then
>>> dissolve it into Funda term by term.
>>>
>>> Tobias
>>>
>>>
>>> Am 14.06.2016 um 19:23 schrieb Campbell Barton:
>>>> Hi Tobias,
>>>> are you proposing
>>>> http://blender-manual.readthedocs.io/en/testing/fundamentals/index.html
>>>> be moved tohttps://www.blender.org/manual/
>>>> and maintained in our subversion repository along with the rest of the manual?
>>> _______________________________________________
>>> Bf-docboard mailing list
>>> Bf-docboard at blender.org
>>> https://lists.blender.org/mailman/listinfo/bf-docboard
>
>
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> https://lists.blender.org/mailman/listinfo/bf-docboard

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20160629/07f13d41/attachment.htm 