[TYPO3-doc] reST DocTemplate for Extension Developer - first draft

[Fabien Udriot]

Dear reST fans,

I have made some progress recently in the migration in our doc_template towards reST and I am coming
up with a first draft version pushed onto a temporary repository. To clone the repository:

git clone git://github.com/fudriot/doc_template.git

* Target group: extension developer. While working on it, I put myself in the shoes of an extension
developers who doesn't want to bother too much with documentation. Given this underlying idea, an
extension developer shouldn't be forced, IMO, to install software on his machine to start writing
documentation (This is not its main focus). In a later step, we should provide the necessary
infrastructure to have the documentation compile in a easy peasy way. (Mid term, I have in mind a
kind of webservice where the developer could send, in one command line, its documentation to be
generated on a server. There are already emerging service (from Xavier ?) where a doc could be
uploaded) . As a result, don't be surprise if you don't see any "Makefile" nor "conf.py" which
shouldn't be versionned since tight to an environment.

* Convention: I would like to come with as much writing "convention" as possible. Since, everybody
has its opinion and I tried to stay as Cartesian as possible:

  1. utf-8 with BOM as encoding.

    -> I think everybody agrees
		
  2. tab indentation with 4 characters (no space):

    -> in order to be "compatible" with PHP code when copy / pasting bits
    -> FYI, F3 has adopted this way of doing
    -> remark: sometimes reST could have 3 indent. Just put 1 tab, as well, in those cases
		
  3. no wrapping when reaching the end of the margin, configuration with soft carriage return

    -> based on my experience automatic returns by margin really sucks more particularly during
       the redaction process. One always has to re-adjust the paragraph because lines get wrongly
       packed when deleting / inserting new words. On the top of that, whenever dealing with URL,
       PHP code, or whatever "unsecable" content, it just becomes a nightmare.
       If you don't agree with this convention, please provide an editor / way where paragraph
       could be easily re-formated. The "best" soft, I know so far, would be Thunderbird in
       plain text mode.

* I have slightly renamed the chapters for the sake of clarity, emphasising the target groups: User
manual, Administrator manual, Developer corner.

* Translation: although there is a little need for an extension translation. I still see the benefit
to give recommendation and encourage people to put a translated for chapter "User manual". Just
imagine the Use Case where a company compiles a documentation for its client and have the
possibility to include the User Manual in a native language.

This is a state of the art. Let's open the discussion. Feedback welcome!

My wish is that we could also find a consensus with the FLOW3 / Phoenix team, eventually.

Cheers,

Fabien