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

[Martin Bless]

Hello Fabien,

>* 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.

Let's agree on UTF-8. I take that for granted.

Next: Sphinx accepts file with BOM and without BOM. It creates new
files with BOM. I think we should behave like Sphinx: recommendation
is to use UTF-8 with BOM. But we would accept UTF-8 without BOM.

Netbeans (7.0.1) for example gives no choice for individual files. I
can only choose "UTF-8" for the whole project. And I don't know how it
behaves in terms of BOM.



>  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

I find this totally ok in literal blocks (= code blocks = preformatted
text).

I totally disagree for the non liteal text. Some special characters,
empty lines and spaces is all you have to create your markup. I really
need this fine grained control of indentation or I would give up
readability totally. It' like "You can't teach someone to dance if you
only allow him to jump but don't allow to do normal steps."

Example:

- In this list it should be possible to indent by two.

  Next paragraph::

      <?php phpinfo(); ?>

- In this list it should be possible to indent by two.

  List item continued.


Example:

#. In this list it should be possible to indent by two.

   Next paragraph::

       <?php phpinfo(); ?>

#. In this list it should be possible to indent by two.

   List item continued.


I'm afraid I can't show everything here. Especially when it comes to
deeper nested levels you will surely want to use blanks. My
experience. My opinion (except for literal blocks): "Tabs are evil!"


		
>  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.



My answer to this: It depends. Yes, allow this. But allow hardwrapping
as well. And trust your editors to choose what's best in the current
context.


Softwrapping works totally well for long unindented paragraphs. We
only use the ability to "View source" very well in a browser as the
text is running very long to the right. But that's of course
acceptable. It doesn't work well when the line starts at a higher
indentation level. Only for illustration, most simple form:

Example (assume a long line softwrapped):

"""
   Don’t waste your time on jealousy; sometimes
you’re ahead, sometimes you’re behind 
 the race
is long, and in the end, it’s only with yourself.
"""

When you see this it's quit difficutl to immediately detect that this
is a quote that will be indented on output. Which you will immediately
grasp with to following:

"""
   Don’t waste your time on jealousy; sometimes
   you’re ahead, sometimes you’re behind 
 the 
   race is long, and in the end, it’s only with 
   yourself. 
"""


>Let's open the discussion. Feedback welcome!

Let's propose one or two chapters that lead into the direction
"Examples, Best practise, Recommendations, Tips and tricks". (Maybe
you did that already? Can't remember by heart right now.) I would
strengthen the helpful "human" parts of the documentation. The
reference part is usually difficult enough so we are all delighted to
"get some tips".

Just for completeness, as we've written about this elsewhere:
Stick to lowercase in the URL? I would do so. OTH: It's not a total
requirement to do everywhere the same. Although nice to have of
course.

cu, Martin

-- 
Certified TYPO3 Integrator | TYPO3 Documentation Team Member

http://mbless.de