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

[Martin Bless]

Hi Fabien and all,


about wrapping long lines:

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

Actually you don't have to do re re-adjustment yourself. Its perfectly
ok to split a line, insert a word on on extra line and leave it that
way. Like in HTML a sequence of whitespace is treated just as one
space character. And you can just split the line where otherwise a
blank is. No nightmare involved, not even with links, as the reST
markup is designed for that. I discovered that when I wrote the OO to
reST parser. I had **very** long lines in the beginning. Now I'm just
splitting them in reasonable portions of about 72 characters and then
those blocks are indented as needed. 

Example, from "If I could offer you only one tip for the future":

    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. 


Just the same:

    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. 

Both example well readable and rendered to the same result.

It's all different of course with `code blocks` = `preformatted text`.


> please provide an editor / way where paragraph could 
> be easily re-formated.

For Windows people this is notepad++. 

I just came across an opensource editor that seems to be similar. It's
available for Linux, Mac and Windows: Editra. See:

http://editra.org/preview

It seems capable of almost all what we would need right out of the
box. I'm missing only one thing: automatically rewrap a long line 
to a bunch of small lines. But notepad++ needs as plugin for that as
well. And Editra knows plugins as well.

It would be interesting if people could give it a try. Especially on
Mac and Linux.

Thanks for your attention!

Martin

-- 
Certified TYPO3 Integrator | TYPO3 Documentation Team Member

http://mbless.de