[TYPO3-doc] Official docs: Mostly CamelCased now (to be pushed again)

[François Suter]

Hi all,

> Source folder structure
> =======================
>
> For example:
> http://srv123.typo3.org/~mbless/git.typo3.org/Documentation/TYPO3/Guide/Security.git

I thought some more about this and I must say that I am really 
disappointed to have to come to such a complex structure. I would like 
us to brainstorm about which elements are really necessary and how they 
could be placed inside a "package" (this being meant in a very general 
way as either a TYPO3 extension, a documentation repo or a FLOW3 package).

I found the initial situation ideal: the "Documentation" folder 
contained just the documentation.

As far as I understand, the conf.py and make* files are necessary to 
perform a local rendering. Although I understand the need to do that and 
will certainly want to do it myself at some point, I think we should 
strive as much as possible to avoid having these files in the packages. 
Couldn't they all be downloaded when needed?

I took a quick look at the conf.py file and saw that there's metadata 
concerning the manual inside it. That's a very bad surprise as far as 
I'm concerned. We can enter metadata in the top reST file. Is it really 
mandatory to duplicate that information in conf.py? Can tools like 
Sphinx not retrieve the meta-information from the reST files themselves?

In his latest mail, Martin mentioned something about Intersphinx and the 
conf.py file. Does that make the conf.py really unavoidable?

The Makefile does not seem to contain information specific to a given 
manual. Why include it then? It could be downloaded as needed, couldn't it?

On top of that come the requirements to have the necessary files to 
interact with Pootle and also to have local (i.e. inside the package) 
translations for documents which are not public.

Could we imagine having all this extra stuff (after having cleared which 
are absolutely necessary) in subfolders? Technical files (like conf.py 
and Makefile) could go to some "rendering" sub-folder, translations to 
"translations" and Pootle stuff to "locales". We could prepend those 
folders with underscores (_) to tell the rendering process to ignore them.

Let's brainstorm to try and reach a cleaner structure (just note that 
I'll be away this week-end again, so I may not answer before a couple of 
days).

Cheers

-- 

Francois Suter
Cobweb Development Sarl - http://www.cobweb.ch